Go slog.Leveler 自定义日志级别映射的实现方式

我在接入 log/slog 时遇到过一个很具体的问题：业务方习惯说“通知”“告警”“紧急”，而 Handler 只认识 slog.Level。比较稳妥的做法不是把业务字符串直接塞进日志，而是先把它们映射成有序的 slog.Level，再让 slog.HandlerOptions.Level 负责阈值过滤。

结论：自定义级别可以使用任意整数，数值越大代表事件越严重；slog.Leveler 只需要实现 Level() slog.Level。如果最低级别需要运行时调整，就传入 *slog.LevelVar，不要频繁重建 Handler。

官方文档：https://pkg.go.dev/log/slog#Leveler

先把业务级别排成一条可比较的数轴

slog.Level 的本质是整数。标准库预设 Debug=-4、Info=0、Warn=4、Error=8，中间的空档就是给 Notice 这类自定义级别留出的空间。Handler 判断一条记录是否输出时，比较的是事件级别和最低级别，而不是业务名称。

因此建议先写一份稳定的映射表。例如把 notice 放在 Info 和 Warn 之间，把 critical 放在 Error 之上。不要让不同模块各自选择数字，否则同一条日志在不同 Handler 下会产生相反的过滤结果。

用 Leveler 封装业务级别到标准级别的映射

实现 Leveler 只有一个方法。下面的类型同时适合两种位置：作为 HandlerOptions.Level 的最低阈值，或者在调用 Logger.Log 时转换出事件级别。

package main

import "log/slog"

// BusinessLevel 是业务日志级别，统一负责转换成 slog 的有序数值。
type BusinessLevel string

const (
	LevelNotice   BusinessLevel = "notice"
	LevelCritical BusinessLevel = "critical"
)

// Level 实现 slog.Leveler，返回值只表达严重程度和可比较关系。
func (l BusinessLevel) Level() slog.Level {
	switch l {
	case LevelNotice:
		return slog.Level(2) // 位于 Info(0) 与 Warn(4) 之间。
	case LevelCritical:
		return slog.Level(12) // 高于 Error(8)，用于需要立即关注的事件。
	default:
		return slog.LevelInfo // 未知业务值回退到安全的 Info。
	}
}

func main() {
	// 这个值既可以作为 Handler 的最低阈值，也可以作为事件级别来源。
	var minimum slog.Leveler = LevelNotice
	_ = minimum.Level()
}

这里的回退策略要结合业务风险选择。如果未知值可能意味着配置错误，宁可显式返回错误或拒绝启动；如果只是日志标签，则回退到 Info 更容易保持服务可用。关键是不要把未知字符串默默映射到 Debug，避免生产日志被意外放大。

把 Leveler 交给 HandlerOptions.Level

内置 TextHandler 和 JSONHandler 都读取 HandlerOptions.Level。传入固定的 BusinessLevel 后，Handler 会在处理阶段把它转换成 slog.Level，低于阈值的记录在进入昂贵参数处理前就可以被过滤。

package main

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

// BusinessLevel 保持与前文相同的 Level 方法，这里只演示接入 Handler。
type BusinessLevel string

const (
	LevelNotice   BusinessLevel = "notice"
	LevelCritical BusinessLevel = "critical"
)

func (l BusinessLevel) Level() slog.Level {
	switch l {
	case LevelNotice:
		return slog.Level(2) // Notice 会放行 Info 以上且低于 Warn 的事件。
	case LevelCritical:
		return slog.Level(12) // 只有更高的自定义事件才会被保留。
	default:
		return slog.LevelInfo // 未知值采用保守的默认阈值。
	}
}

func main() {
	// 用 notice 作为最低级别，debug 和 info 下面的事件会被过滤。
	h := slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{Level: LevelNotice})
	logger := slog.New(h)

	ctx := context.Background()
	logger.Log(ctx, LevelNotice.Level(), "库存接近阈值", "warehouse", "hz-01")
	logger.Log(ctx, LevelCritical.Level(), "库存服务不可用", "warehouse", "hz-01")
}

这里要区分两个概念：LevelNotice.Level() 是“这条事件的级别”，HandlerOptions.Level 是“最低输出级别”。如果 Handler 的最低级别是 Notice，Critical 自然会被保留；反过来把最低级别设成 Critical，Notice 就会被丢弃。

需要动态调节时使用 LevelVar

如果线上需要临时打开 Debug，固定的 BusinessLevel 不够用。slog.LevelVar 本身实现了 Leveler，并提供 Set 方法；官方文档说明它可以安全地被多个 goroutine 读写。Handler 只创建一次，调整时修改 LevelVar 即可。

package main

import (
	"log/slog"
	"os"
)

func main() {
	var programLevel slog.LevelVar // 零值是 Info，适合作为默认阈值。
	h := slog.NewTextHandler(os.Stdout, &slog.HandlerOptions{Level: &programLevel})
	logger := slog.New(h)

	// 临时降低阈值以排查问题，修改会被后续请求看到。
	programLevel.Set(slog.LevelDebug)
	logger.Debug("debug detail", "component", "billing")

	// 排查结束后恢复 Info，避免长期放大日志量。
	programLevel.Set(slog.LevelInfo)
}

动态阈值只解决“是否输出”，不负责把业务级别改名。把两件事混在一起，往往会导致运维开关改变了日志语义。建议把阈值开关和业务级别映射分别封装。

自定义级别的显示名称要单独处理

如果直接输出 slog.Level(2)，文本处理器会按标准规则显示为类似 INFO+2 的形式，而不是自动显示为 NOTICE。需要统一对接外部日志系统时，可以在 ReplaceAttr 中改写内置的 level 属性。

package main

import "log/slog"

// displayLevel 把数值级别转换成稳定的对外名称。
func displayLevel(level slog.Level) string {
	switch {
	case level 

显示层可以按外部系统的约定命名，但过滤层仍然依赖数值。尤其要保留级别之间的顺序，否则“只保留 Warn 以上”的配置会失去意义。

几个容易踩坑的边界

• 不要把 Leveler 当成字符串格式化接口。它只提供一个可比较的 slog.Level。
• 不要频繁重建 Handler。固定阈值用值类型实现，动态阈值用 LevelVar。
• 不要让自定义数字跨模块漂移。把映射表和显示名称集中到一个小包中。
• 不要把未知业务级别当成 Debug。错误配置应回退到明确的安全策略，必要时在启动阶段拒绝。

总结

把业务级别接入 slog 时，可以按“业务名称 → slog.Level → Leveler → Handler 阈值”的顺序设计。固定规则直接实现 Level() slog.Level；需要运行时调整就把 *slog.LevelVar 交给 HandlerOptions.Level；需要人读的名称再通过 ReplaceAttr 处理。这样过滤、动态开关和显示格式各自独立，后续接入 JSON 日志或外部采集系统时更容易保持一致。

相关问题

slog.Level 的数值越大就一定越重要吗？

在 slog 的比较语义里是这样设计的：更大的级别表示更严重，Handler 的最低级别会据此过滤。具体数字可以按系统约定映射，但顺序不能随意改变。

Leveler 和 LevelVar 有什么关系？

Leveler 是只有 Level() 的接口，LevelVar 是一种可动态修改并实现该接口的具体类型。固定阈值不需要 LevelVar。

为什么自定义级别输出成 INFO+2？

因为数值级别默认按 slog 的字符串规则展示。想输出 NOTICE、CRITICAL 等业务名称，需要在 ReplaceAttr 中根据数值改写 level 属性。