jsonid —— 以字符串形式上 wire 的主键(雪花 ID 不能用数字)
本仓主键由 sonyflake 生成,量级约
1e17,而 JavaScript 的Number只能精确表示到2^53-1(约9.0e15)。ID 比上限大一个数量级,超出部分在JSON.parse时被静默截断。
wire 上真实的 id: 94883951113533126
JS 解析后变成: 94883951113533120 ← 末 6 位被吃掉
信息在解析那一刻就没了,前端侧任何补救都拿不回真值。把截断后的值回传后端就会 404 —— 身份切换就死在这里。这不是前端能修的问题:JS 语言层面就没有 64 位整数, 大整数只能靠字符串传。
功能
jsonid 提供三件东西:
ID——uint64的新类型,在 JSON 上序列化成字符串、反序列化成字符串。 只影响 JSON,不碰 GORM 列类型(库里仍是uint64)。IDList——[]ID的批量形式。json:",string"内置选项管不了数组 (标准库只支持 string / float / int / bool 标量),批量 ID 字段必须换真类型。- 全仓扫描器(
ScanDir/Violation/RenderAllowlist)—— 找出"该打,string却是 integer"的 json tag,作为一条自动化的棘轮守卫。
不解决:前端拿 ID 之后的比较逻辑(JS 里必须用字符串比较)。
配置
本包无 yaml 配置 —— 这是 wire 格式契约,不是运行期配置。
使用方法
类型声明
type IdentityView struct {
ID jsonid.ID `json:"id"`
Role jsonid.ID `json:"role_id"`
Tags jsonid.IDList `json:"tag_ids"`
}
转换
view.ID = jsonid.FromUint(identity.ID) // uint64 → ID
id := view.ID.Uint64() // ID → uint64(给 service / GORM 用)
list := jsonid.FromUints([]uint64{1, 2, 3}) // []uint64 → IDList
us := list.Uints() // IDList → []uint64
序列化
b, _ := json.Marshal(jsonid.FromUint(97013624807423348))
// "97013624807423348"
反序列化
var got jsonid.ID
err := json.Unmarshal([]byte(`"97013624807423348"`), &got)
扫描器(接新模块的人必读)
扫描器是棘轮:它扫全仓 .go 文件,找出"整数字段 + id 类 json 名 + 没按规矩序列化"的
违规,产出一张 Violation 列表。
violations, err := jsonid.ScanDir(root) // root = internal/ 之类
for _, v := range violations {
fmt.Println(v.File, v.Line, v.Struct+"."+v.Field, v.JSONName, v.GoType)
fmt.Println(v.Fix()) // 这一条该怎么改
}
Violation 的字段:File(相对仓库根的路径)、Line、Struct、Field、
JSONName、GoType、Tagged(是否已打 ,string)。
v.Key() 给出稳定标识(用于清单对账),v.Fix() 直接给出改法。
怎么跑:
- 日常:
go test ./internal/pkg/jsonid/ -run TestNoBareIntegerIDTags—— 新增违规让测试红;已改完却还挂在清单上,同样红(清单不许只增不减)。 确需临时豁免时,重建清单(会覆盖整个文件,只在建清单时用):
UPDATE_ID_ALLOWLIST=1 go test ./internal/pkg/jsonid/ -run TestNoBareIntegerIDTags之后改造就手工删对应行,不要重新生成 —— 重新生成会让清单永远只反映当下, 失去"不许新增"的约束力。
- 清单文件路径:
internal/pkg/jsonid/id_tag_allowlist.txt(常量jsonid.AllowlistFile)。当前这个文件不存在 —— 2026-10-21 259 个字段 已全部改完,现在是零容忍模式,allowlist 机制只在"确实需要临时豁免"时才重建。 - 清单每行的格式由
LoadAllowlist强制:<位置> # <怎么改>—— 缺" # "分隔符会返错 (allowlist 行缺少 ' # ' 说明(每行都要写为什么还没改))。 渲染用jsonid.RenderAllowlist(violations),解析单行用jsonid.ParseAllowlistLine(line)。
完整示例见 examples/jsonid/main.go。
注意事项
- ⚠️
json:",string"对数组/切片/结构体无效。 标准库文档原话:"It applies only to fields of string, floating point, integer, or boolean types"。本仓有identity_ids/department_ids/order_ids这类批量 ID 字段,它们是[]uint64⇒ 必须换成jsonid.IDList,加,string一点用没有。 - ⚠️ 标量有两种合规写法,别混:
jsonid.ID类型(推荐,类型层面就对了)uint64+json:"id,string"(也可以,GORM / service 层一行都不用改) 两种方向必须一致 —— 一边发字符串一边收数字,就是"登录能过、提交报 400"的经典成因。
- ⚠️
UnmarshalJSON也接受裸数字(如123),那是"改造尚未完成的兄弟接口"的 兼容通道 —— 拒绝会让整个前端在改造完成前全挂,而改造是分模块推进的。 新代码别依赖它;规范格式是字符串。改完全部走字符串之后这条路径自然死掉。 - ⚠️
IDList的null与[]是两回事。反序列化时null→nil, 保留"没传"与"传了空数组"的区别 —— 前端据此区分"不过滤"和"过滤到空"。IDList为 nil 时序列化结果是null(不是[])。 - ⚠️
ID反序列化时""(空串)→ 0,不报错。空串与 0 在下游是同一个值, 排查"查不到数据"时别忘了这一条。 - ⚠️ 扫描器按类型名猜整数类型,不解析类型别名链。
用
type UserID uint64这种别名的字段可能漏扫(别名在 AST 里就是UserID, 不在integerish表里)。误报方向是"多查",不会漏 —— 但别名那类是真的会漏。 - ⚠️ 扫描器排除了一类"看起来像 ID"的字段:
captcha_id/trace_id/request_id/open_id/key_id/handler_id—— 验证码令牌、链路追踪 id、微信 unionid 这类本来就不是数字 ID。 后缀_by(created_by/review_by/last_changed_by)算 ID (都是操作人 user_id,同样会溢出)—— 第一版规则只认_id,结果全仓 22 个"谁干的" 字段一个没扫到。 - ⚠️
Violation.Key()不含行号 —— 行号会在任何一次编辑后漂移,进了清单就永远对不上, 棘轮会误报成"新增违规"。代价是两个同名匿名结构体只记一条,改的时候按文件定位即可。 - ⚠️
examples/jsonid/main.go的注释里写的go run ./cmd/scan-jsonid -root . -out ...这条命令在本仓不存在 ——cmd/下只有server/migrate/seed/seed_audit/seed_dept/gen-errcode-doc/gen-swagger-schema。 真正的入口是上面那个UPDATE_ID_ALLOWLIST=1的测试。