Go 日志slog JSON Handler 输出字段顺序变化怎么办

遇到 slog.NewJSONHandler 输出字段顺序变化时，先不要把它当成日志内容丢失。JSON 对象的字段顺序不改变字段的键和值，很多“变化”只是测试在比较整行字符串，或者下游界面按自己的顺序展示。正确处理方式是先按 JSON 解码比较语义；只有当接收方明确把字节顺序当作协议的一部分时，才需要额外设计规范化输出。

先把“顺序变化”拆成三个问题

在高并发服务里，我通常先保存同一条日志在升级前后的原始行，然后分别检查键集合、嵌套路径和值类型。若两行只是 service、request_id 的位置不同，它们表达的是同一份 JSON 数据；如果出现字段缺失、键名变化或字符串与数字类型变化，才是需要修复的 schema 问题。

package main

import (
    "encoding/json"
    "fmt"
)

func sameFields(before, after []byte) error {
    var left, right map[string]any
    // 解码到 map，比较键和值，避免把 JSON 对象的文字顺序误当成业务差异。
    if err := json.Unmarshal(before, &left); err != nil {
        return fmt.Errorf("解析旧日志失败: %w", err)
    }
    if err := json.Unmarshal(after, &right); err != nil {
        return fmt.Errorf("解析新日志失败: %w", err)
    }
    // 这里比较的是字段语义；若要区分整数精度，可改用 Decoder.UseNumber。
    if !mapsEqual(left, right) {
        return fmt.Errorf("字段或值发生变化")
    }
    return nil
}

func mapsEqual(left, right map[string]any) bool {
    // 只保留一个小型递归比较器，生产代码也可以使用 reflect.DeepEqual。
    if len(left) != len(right) {
        return false
    }
    for key, value := range left {
        other, ok := right[key]
        if !ok || fmt.Sprint(value) != fmt.Sprint(other) {
            return false
        }
    }
    return true
}

上面的比较器只适合作为文章中的排查示意：真实契约测试应递归区分数组、对象和数字类型，不能用字符串化掩盖类型差异。关键点是不要直接比较两条 JSON 文本。

slog 为什么会让字段看起来换了位置

JSONHandler 输出的是单行 JSON 对象。记录中的时间、级别、消息以及属性会被 handler 组合；通过 logger.With 绑定的属性属于 logger 的上下文，调用时传入的属性属于当前 record。代码从单一 logger 改成带上下文 logger，或把属性从 With 移到单次调用，就可能让日志行的文字排列不同。

package main

import (
    "log/slog"
    "os"
)

func writeLog(requestID string) {
    handler := slog.NewJSONHandler(os.Stdout, nil)
    logger := slog.New(handler).With(
        slog.String("service", "billing"),
    )

    // With 放稳定上下文，调用参数放当前请求字段；两类属性的来源不同。
    logger.Info("charge accepted",
        slog.String("request_id", requestID),
        slog.Int("amount", 99),
    )
}

这个输出可以包含 time、level、msg、service、request_id 和 amount，但不应把它们的当前排列当成 JSON 协议。若使用 WithGroup，键还会进入嵌套对象；若使用 HandlerOptions.ReplaceAttr，键名、值或部分标准字段也可能被替换或移除。

把测试从“整行相等”改成字段契约

最常见的故障来自 golden 文件或单元测试直接断言整行日志。可以保留原始文本用于人工阅读，但断言应先解码，再逐个检查真正重要的字段。下面的示例只检查 schema 关心的键，不关心 JSON 对象的排列。

func assertLog(line []byte) error {
    var got map[string]any
    // JSONHandler 每次 Handle 写一行，测试先取出这一行对应的对象。
    if err := json.Unmarshal(line, &got); err != nil {
        return fmt.Errorf("日志不是有效 JSON: %w", err)
    }
    // 只断言消费者依赖的字段，避免实现层顺序变化造成无意义失败。
    for _, key := range []string{"level", "msg", "request_id"} {
        if _, ok := got[key]; !ok {
            return fmt.Errorf("缺少字段 %q", key)
        }
    }
    return nil
}

如果测试确实需要 golden 文本，例如要检查日志采集器的转义格式，也要先定义“规范化”：统一字段集合、数字表示、时间格式和排序规则，再比较规范化结果。否则测试会把日志库升级、属性移动或展示层变化误报成业务回归。

什么时候才需要固定字节顺序

只有签名输入、哈希输入、严格的文本协议或脆弱的老系统把整行字节交给下游时，字段顺序才可能成为兼容边界。此时不要口头约定“当前 slog 正好这样输出”，而应把顺序写进自有格式：先定义字段列表和版本，再由专门的编码层按列表生成内容，或让接收方改成解析 JSON。

对于普通日志平台，优先固定字段名、分组路径、值类型和脱敏规则。把 request_id 放在哪个位置通常没有运营价值；把它是否存在、是否为字符串、是否能被检索，才是长期契约。多 handler 场景也要分别检查每个输出目标，不要用文本 handler 的视觉顺序推断 JSON handler 的行为。

常见问题

JSON 字段顺序变化会影响日志检索吗？

正常的 JSON 解析器不应受影响。真正可能受影响的是把整行当普通字符串做正则、哈希或快照比较的系统。

能不能通过调整 slog 参数强行固定顺序？

可以控制属性的组织方式，但不建议把默认 handler 当前的文字排列当成长期协议。需要稳定字节时应建立自己的规范化编码边界。

为什么升级 Go 后 golden 测试突然失败？

先确认是字段排列、转义、时间格式还是键和值真的变化。若只是排列，改为结构化断言；若是 schema 改动，再评估兼容迁移。