Go snowflake JSON数字传给JavaScript为什么可能丢精度

我在把 Go 服务里的雪花 ID 接到前端时，最容易误判的一点是：ID 生成得唯一，并不代表它作为 JSON 数字传到 JavaScript 后仍然精确。只要接口把 64 位 ID 暴露成 JSON number，前端的 Number 就可能在解析时把末尾几位舍入。

稳妥的做法是把跨 JavaScript 边界的 snowflake ID 固定成字符串；只有确实需要数值运算时，才在前端把字符串显式转换为 BigInt，不要先转成 Number。

官方文档：https://pkg.go.dev/github.com/bwmarrin/snowflake

JavaScript 数字边界：https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/MAX_SAFE_INTEGER

变化一句话：问题出在 JSON 契约，不在 snowflake 生成器

github.com/bwmarrin/snowflake 的 ID 可以返回 int64 形式，也提供 String() 和 MarshalJSON() 等方法。这里有一个很关键的分叉：字段类型仍是 snowflake.ID 时，可以利用它自己的 JSON 序列化行为；如果先调用 Int64()，再把结果放进普通的 int64 字段，就等于主动要求 JSON 编码器输出数字。

为什么 JavaScript 解析 JSON 数字会丢精度

JavaScript 的 Number 是双精度浮点数，整数只有在 -(2^53 - 1) 到 2^53 - 1 之间时，才能保证精确表示。上限就是 9007199254740991。雪花 ID 通常是不断增长的 64 位整数，很容易超过这个范围。

这不是“JSON 不允许大整数”，而是接收方把 JSON 数字转换成 JavaScript Number 时，无法为每一个 64 位整数保留全部位数。常见表现包括前端打印出的 ID 与服务端不同、两个相邻 ID 比较相等，以及用这个 ID 请求详情时命中错误记录。

const payload = JSON.parse('{"id":9007199254740993}');
// 这里故意用超过安全整数范围的边界值观察 Number 的限制
console.log(payload.id);
console.log(Number.isSafeInteger(payload.id));

const safePayload = JSON.parse('{"id":"9007199254740993"}');
// 字符串先保留原始字符，比较和传回服务端都不会丢位
console.log(safePayload.id);
console.log(BigInt(safePayload.id));

这里的判断重点不是某一个具体 ID，而是字段的表示类型。只要接口文档把 ID 定义成字符串，前端就不会在 JSON.parse() 阶段偷偷把它压成 Number。

对旧代码的影响：调用 Int64 会改变序列化结果

我更愿意把这看成一次接口契约调整，而不是给生成器打补丁。下面两个结构体看起来都来自同一个 ID，但它们对 JSON 的承诺并不一样：

package api

import (
    "encoding/json"
    "github.com/bwmarrin/snowflake"
)

type NativePayload struct {
    ID snowflake.ID `json:"id"`
}

type NumericPayload struct {
    ID int64 `json:"id"`
}

func marshalExamples(id snowflake.ID) ([]byte, []byte, error) {
    native := NativePayload{ID: id}
    numeric := NumericPayload{ID: id.Int64()}

    // 保留 snowflake.ID 类型，让它的 MarshalJSON 参与序列化。
    nativeJSON, err := json.Marshal(native)
    if err != nil {
        return nil, nil, err
    }
    // 显式取 Int64 后，字段会按普通 JSON 数字处理，跨端风险由调用方承担。
    numericJSON, err := json.Marshal(numeric)
    if err != nil {
        return nil, nil, err
    }
    return nativeJSON, numericJSON, nil
}

如果项目已经把 int64 数字返回给前端，不要只在某个页面上加格式化。更稳的是从 API DTO、OpenAPI 定义、前端类型和测试数据四处同时改成字符串；数据库内部仍然可以使用 64 位整数，外部契约不必跟着变成数字。

迁移建议：在 Go API DTO 层固定为字符串

对于列表、详情、分页游标和关联对象，我通常会在出站 DTO 层统一使用 string。这样数据库模型可以保留原有的整数类型，序列化策略也不会依赖某个包的隐式方法：

type ArticleDTO struct {
    ID       string `json:"id"`
    ParentID string `json:"parentId,omitempty"`
}

func newArticleDTO(id, parentID snowflake.ID) ArticleDTO {
    // String 只负责表示 ID，不让前端承担 64 位整数的解析风险。
    return ArticleDTO{
        ID:       id.String(),
        ParentID: parentID.String(),
    }
}

func encodeArticle(dto ArticleDTO) ([]byte, error) {
    // DTO 字段是字符串，encoding/json 会生成带引号的 JSON 值。
    return json.Marshal(dto)
}

字符串方案还有一个实际好处：日志、缓存键、URL 路径和前端状态管理可以使用同一种表示。需要注意的是，字符串不是把 ID 变得“可计算”；它的职责是保持身份稳定。

前端需要数值能力时，显式使用 BigInt

大多数前端场景只需要展示、比较或再次传回 ID，字符串已经足够。如果确实要做差值、排序或范围运算，可以在明确的位置转成 BigInt：

function compareSnowflakeIds(left, right) {
  // 输入必须来自字符串字段，避免先经过 Number 再转 BigInt。
  const leftID = BigInt(left);
  const rightID = BigInt(right);
  return leftID  rightID ? 1 : 0;
}

function toRequestParam(id) {
  // URL 和 JSON 出站仍使用十进制字符串，避免 BigInt 不能直接 JSON.stringify。
  return id.toString();
}

不要写成 BigInt(Number(id))：一旦中间经过 Number，丢掉的位数无法恢复。也不要直接对含 BigInt 的对象调用默认 JSON.stringify()，出站接口仍应明确转回字符串。

最小回归检查：只盯住表示类型和边界值

这类问题的回归用例不需要跑完整业务链路，关键是覆盖安全上限附近的 ID，并分别检查字符串字段和数字字段的 JSON 形态：

func TestIDContract(t *testing.T) {
    id := snowflake.ID(9007199254740993)
    dto := ArticleDTO{ID: id.String()}

    body, err := json.Marshal(dto)
    if err != nil {
        t.Fatal(err)
    }
    // 断言接口输出带引号，防止未来有人把 DTO 改回 int64。
    if string(body) != `{"id":"9007199254740993"}` {
        t.Fatalf("unexpected json: %s", body)
    }
}

我的结论：把雪花 ID 当标识，而不是金额一样的数值

这次踩坑让我把接口里的 ID 和真正参与加减的业务数字分开看：雪花 ID 的主要语义是身份，默认应该走字符串；数据库仍可用整数，前端需要运算时再显式使用 BigInt。这样改动很小，却能同时覆盖详情、列表、分页和缓存键，避免某个入口悄悄把同一 ID 变成另一种类型。

相关问题

• snowflake.ID 直接作为 JSON 字段一定安全吗？应以当前使用的包实现为准；若其 MarshalJSON 输出字符串，通常比手动 Int64 更适合跨 JavaScript 边界，但仍建议在 DTO 测试中固定契约。
• 能不能把前端 ID 改成 Number 方便排序？不建议。按字符串比较通常已足够；需要数值排序时把两端值转成 BigInt。
• 字符串 ID 会不会影响 Go 后端查询？不会。可以在进入仓储层时解析回 snowflake.ID 或 int64，出站 DTO 再转为字符串。