us-tariff-lookup Go 包使用教程:离线 HTS 搜索与变更日志(go get 上手)

Invoice × Tariff 编辑部

适用对象要把离线 HTS 查询与关税变动追踪接进服务、CLI 和内部工具的 Go 开发者。

go get github.com/invoicetariff/us-tariff-lookup-go 即可安装——零依赖 Go 模块,版本化规则快照随包内置。tariff.SearchHTS 做英文/中文 HTS 搜索,tariff.Meta() 报快照版本,tariff.Changelog() 给机器可读规则变更。完全离线、MIT 许可;v1 只含查询面——落地成本计算在 npm 包与网页计算器里。

这个模块是什么

us-tariff-lookup-go 是驱动本站计算器与 npm 包的同一份版本化快照的 Go 形态:数据经 go:embed 随包内置、零依赖、无需 API Key、无网络请求。以 tariff 包名导入后,每个答案对固定的模块版本都是确定的——每条结果都带 rulesetVersion 与 dataAsOf 日期。

MIT 许可。v1 提供查询面:HTS 搜索、规则集 meta 与机器可读变更日志。叠加落地成本计算有意不在这个模块里——文末详述。

安装

需要 Go 1.22 或更新版本。

go get github.com/invoicetariff/us-tariff-lookup-go
# 可选 CLI:
go install github.com/invoicetariff/us-tariff-lookup-go/cmd/us-tariff@latest

第一个程序:meta、search、changelog

一个 main.go 跑完整套 API 面:

package main

import (
	"fmt"

	tariff "github.com/invoicetariff/us-tariff-lookup-go"
)

func main() {
	// 你手里是哪份快照——展示任何数字时都把这两个字段带上。
	meta := tariff.Meta()
	fmt.Println(meta.RulesetVersion, meta.DataAsOf) // 0.3.4 2026-10-07(每月重建)

	// HTS 搜索:编码前缀、英文描述或中文关键词。
	// 多词查询按 AND 分词,覆盖全部匹配面。
	for _, hit := range tariff.SearchHTS("cotton t-shirt", 5) {
		fmt.Println(hit.Entry.HTS8, hit.Entry.General, hit.MatchedBy)
		// 61091000 16.5% en
	}

	// 规则变更,日期从新到旧(published + upcoming + historical)。
	for _, e := range tariff.Changelog() {
		fmt.Println(e.Date, e.Layer, e.Status, e.TitleEn)
	}
}

第一行搜索就是黄金测试用例:cotton t-shirt 命中 HTS 61091000,带官方 USITC 普通税率。中文同理——tariff.SearchHTS("保温杯", 5) 通过内置的中文描述与关键词找到保温杯条目(96170010),hit.MatchedBy 返回 "zh"。

CLI:三条命令

装了 cmd/us-tariff 之后,同一份数据在任意 shell 里都能驱动——接流水线、定时任务和 LLM 工具都方便:

us-tariff meta                  # 包里有什么 / 当前数据版本
us-tariff search "steel screws" # EN / 中文 / 编码前缀,可带条数:us-tariff search 保温杯 20
us-tariff changelog 5           # 近期规则变更,新的在前

所有命令输出缩进 JSON,信封含 rulesetVersion、dataAsOf 与 disclaimer,载荷在 result 下——可以直接接 jq。

读懂结果字段

搜索命中([]tariff.Hit)= 精选 MFN 条目 + 命中面:

  • hit.Entry.HTS8 / .Description / .DescriptionZh——8 位编码与双语描述。
  • hit.Entry.General——官方 USITC 第一栏普通税率,形如 "16.5%" 的字符串。
  • hit.MatchedBy——"code"、"en" 或 "zh";多词查询要求每个词都在该条目的某处命中(AND 语义)。
  • hit.Entry.Sample——为 true 表示该税率行尚未逐行对照 Federal Register 原文核实:规划级,不是核定的报关数据。

变更条目([]tariff.ChangelogEntry)带 Date、Layer、Status("published" = 已生效、"upcoming" = 未来生效、"historical" = 已被接替、供退税查询保留的历史层)、TitleEn,以及含 Federal Register 文号的中文 Title/Summary。

错误处理与限频——如实盘点

设计上几乎无需处理:

  • 调用期无 error 值、无 panic。 JSON 在 init 时从内置数据一次性解析;查询函数都是纯函数。空查询(或无命中)直接返回 nil——像对待任何切片那样判空即可。
  • 无限频、无密钥、无超时。 没有任何网络请求,CI、内网隔离环境、serverless 冷路径都能放心用。
  • 真正的风险是版本漂移,不是失败。 在 go.mod 里钉住模块版本(裸 go get 解析最新 tag;不钉版本,@latest 工具链会让你的数字在两次构建之间变动)。每个结果都回显 tariff.Meta() 的 RulesetVersion/DataAsOf,并把导出的 tariff.Disclaimer 常量透传给终端用户。
  • tariff.SearchHTS 的 limit 在 <= 0 时默认 10;结果按快照的精选顺序返回,不是相关性打分。

保持数据新鲜

规则快照每月重建(重大政策落地时临时加更),来源是开放的税率数据仓;本模块随每份快照重新打 tag——用 go get github.com/invoicetariff/us-tariff-lookup-go@latest 升级。版本之间动了什么,读 tariff.Changelog()(或 us-tariff changelog)。带新旧值的实时 feed 在关税雷达,附 RSS,方便你自动化响应。

包内规则快照一览

下表数字对应当前 release(快照 v0.3.4,截至 2026-10-07)——跑一下 tariff.Meta() 看你自己构建里的值:

数据面 数量 说明
精选 MFN 编码 484 高频 HTS 8 位码,带官方 USITC 普通税率(英文+中文)
对华 Section 301 行 25 清单 2/3/4A + 2026 四年复审新增
全球 301 档位 60 2026 全球 Section 301 计划档位
Section 232 措施 8 钢铝 / 铜 / 汽车 / 家具 / 药品 / 半导体 / 木材
变更条目 57 published + upcoming + historical,每条带官方来源

需要模块没有建模的层?tariff.RulesetSeedRaw() 与 tariff.ChangelogRaw() 返回完整的内置 JSON(规费表、232 措施、IEEPA 历史、逐条来源 URL),直接 unmarshal 即可。内置搜索覆盖精选高频码,不是全部 5,689 条 HTS——全量表在 hs-codes-database 仓与 HTS 搜索页。

v1 没有落地成本计算——请用 npm 包或网页计算器

这个模块有意只做查询面。叠加税层、从量/复合税率、MPF/HMF 规费与单件落地成本在 us-tariff-lookup npm 包(同一快照,TypeScript,Node 可用)和本站关税计算器里——后者完全不用写代码。常见组合拳:Go 侧查码、追规则变动,再用 npm 包按同一 rulesetVersion 给这条线计价,两边逐位一致。

常见问题

Go 模块能像 npm 包那样算落地成本吗?
v1 不能。us-tariff-lookup-go 只提供查询面——HTS 搜索、规则集 meta 与变更日志。叠加计算(MFN + 301 + 232 + MPF/HMF、单件落地成本)在 us-tariff-lookup npm 包与网页计算器里,三者跑同一份快照,可以对齐同一个 rulesetVersion 搭配使用。
它会调 API 吗?需要 API Key 吗?
都不需要。规则 JSON 经 go:embed 内置于模块,零依赖,运行期不碰网络。因此没有密钥、没有配额、没有超时——CI、内网隔离环境、serverless 函数都能用。
数据有多新?怎么更新?
快照每月从开放的 us-tariff-rates-2026 数据仓重建,Go 模块随每份快照重新发版。跑 tariff.Meta()(或 us-tariff meta)看你内置的版本与 data-as-of 日期,然后 go get github.com/invoicetariff/us-tariff-lookup-go@latest 升级。tariff.Changelog() 列出变动内容。
能用在商业产品里吗?什么许可?
MIT——商业使用、修改、再分发都没问题,包括放进收费产品。保留许可声明,并把免责声明展示给用户:数据是规划级(多数行带 sample/unverified 标),最终应缴关税由 CBP 在入境时核定。
SearchHTS 为什么找不到我的产品?
内置搜索覆盖精选高频码(当前 release 484 条),不是全部 5,689 条 HTS 8 位码。全量表在 hs-codes-database 仓或 HTS 搜索页;模块没解析的税层,用 RulesetSeedRaw() 拿完整 JSON 自己解析。
pkg.go.dev 上的 us-tariff-lookup-go

MIT 许可、零依赖、Go 1.22+。源码仓、发布版本与姊妹 npm / PHP 包都见开源项目页。