Go log/slog 怎样让日志字段保持稳定顺序

在排查接口日志时，最容易被忽略的一点是：字段值没变，字段顺序却可能变得难以比较。Go 的 log/slog 不会替业务属性自动按字母排序；想让输出稳定，应把固定字段按约定顺序组成 []slog.Attr，把动态字段先整理成确定顺序，再交给 Logger.LogAttrs。内置 TextHandler 和 JSONHandler 会沿着属性进入记录的顺序格式化。

官方资料：https://pkg.go.dev/log/slog

稳定顺序的责任在属性构造层：固定字段显式排列，动态字段先排序；不要指望 Handler 替你猜业务优先级。

先把“顺序不稳定”拆成三个来源

一次 slog 输出可以看成“属性进入记录—Handler 格式化”两段。直接在日志调用里交替传入键值对时，调用顺序就是最直观的顺序；使用 slog.Attr 时，属性切片的顺序同样重要。Logger.With 加入的公共属性会作为 Handler 的已有属性，再接上后续属性。

真正容易出问题的是动态字段：如果把 map[string]any 直接转换成日志参数，map 的遍历顺序不能当作业务契约。另一个误区是把“字段顺序稳定”理解成“按时间排序”，而 slog 的 Handler 只负责处理当前记录，不会替你重排已经写入的多条日志。

固定核心字段时，先把属性切片当成契约

把每类日志都需要的字段放在同一个构造函数里，后续调用只负责追加事件专属字段。这样字段优先级一眼可见，也方便代码评审时发现顺序变化。

package main

import (
    "context"
    "log/slog"
    "os"
)

// stableAttrs 统一放置每条订单日志都需要的固定字段。
func stableAttrs(requestID, service, event string) []slog.Attr {
    return []slog.Attr{
        // 先放请求关联字段，便于检索和串联上下文。
        slog.String("request_id", requestID),
        // 再放服务身份，保证跨服务日志的前缀一致。
        slog.String("service", service),
        // 最后放事件名，作为这类日志的语义入口。
        slog.String("event", event),
    }
}

func main() {
    logger := slog.New(slog.NewJSONHandler(os.Stdout, nil))
    attrs := stableAttrs("req-42", "billing", "invoice.created")
    attrs = append(attrs,
        // 事件字段放在固定前缀之后，顺序仍由 append 明确控制。
        slog.String("invoice_id", "inv-1001"),
        slog.Int("amount_cents", 1299),
    )
    // LogAttrs 只接收 Attr，避免交替参数把字段顺序写散。
    logger.LogAttrs(context.Background(), slog.LevelInfo, "invoice created", attrs...)
}

这里的重点不是把每一个字段都写进全局规范，而是让“固定前缀”只有一个构造入口。若某个事件确实需要不同字段，可以在固定前缀后追加；不要在多个调用点各自复制一份公共字段列表。

动态字段先排序，再追加到固定前缀后面

动态字段适合使用 map 保存，但不适合直接承担日志输出顺序。可以先收集键并排序，再按排序后的键读取值。下面的示例将动态字段限定为字符串值，遇到未知键时跳过；生产代码也可以把值改成 any，再按自己的类型策略构造 slog.Any。

package main

import (
    "log/slog"
    "sort"
)

// appendStableMap 把动态 map 转成确定顺序的 Attr，避免依赖 map 遍历顺序。
func appendStableMap(attrs []slog.Attr, fields map[string]string) []slog.Attr {
    keys := make([]string, 0, len(fields))
    for key := range fields {
        // 只收集键；值在排序后再读取，保证键和值不会错配。
        keys = append(keys, key)
    }
    sort.Strings(keys)
    for _, key := range keys {
        // 排序后的键决定动态字段的稳定顺序。
        attrs = append(attrs, slog.String(key, fields[key]))
    }
    return attrs
}

调用时先得到固定前缀，再调用这个函数追加动态字段：

attrs := stableAttrs("req-42", "billing", "invoice.created")
attrs = appendStableMap(attrs, map[string]string{
    "region": "cn-east",
    "tenant": "demo",
    "source": "api",
})
// 中文说明：固定字段先输出，动态字段按键名排序后接在后面。
logger.LogAttrs(ctx, slog.LevelInfo, "invoice created", attrs...)

With、Group 和 JSON 输出的边界

With 适合公共字段，使用时要把它视为“基础前缀”而不是排序器。例如先 logger.With("service", "billing")，再在调用处传入 event 和业务字段，输出会保留公共属性在前、调用属性在后的关系。

slog.Group 或 slog.GroupAttrs 解决的是命名空间，不是跨记录排序。Text 输出通常把组展开成点号路径，JSON 输出则把组表现为嵌套对象；组内属性依旧应按你希望的顺序构造。若要让多个 Handler 都稳定，应该在进入 Handler 之前统一构造属性，而不是为每种输出格式写一套排序逻辑。

回归检查只锁顺序契约，不锁死所有文本

日志通常还包含时间、级别和消息，测试不必比较整行字符串。更稳妥的做法是通过自定义 Handler 读取 slog.Record.Attrs 的键序列，检查固定前缀和动态字段的排序结果；再单独测试 JSON 是否保留了组层级。这样时间格式、空值显示等无关变化不会让测试频繁抖动。

迁移清单

1. 找出直接从 map 拼接日志参数的调用点，改为“固定属性 + 排序后的动态属性”。
2. 为每类日志定义固定前缀，明确 request_id、service、event 等字段的先后。
3. 公共字段使用 With，多层业务字段使用 Group，不要把两者混成排序逻辑。
4. 用自定义 Handler 或记录键序列检查顺序，避免用包含时间的整行字符串做脆弱断言。

相关问题

slog 会自动按字段名排序吗？

不会。要稳定排序，应在构造 []slog.Attr 时明确顺序；动态键则先提取并排序。

TextHandler 和 JSONHandler 的字段顺序会不一样吗？

它们的呈现形式不同，但都接收同一条记录的属性序列。若业务字段在进入记录前已稳定构造，两种输出就能保持相同的字段先后语义。

为什么不直接在自定义 Handler 里排序？

Handler 通常还要处理公共属性、分组和不同输出后端。在属性源头建立顺序契约更容易复用，也不会把业务优先级隐藏在某个输出实现中。