Go slog.Level.UnmarshalText 怎样解析配置日志级别

如果日志级别来自环境变量、配置文件或命令行，建议把文本解析集中交给 slog.Level.UnmarshalText。它按 slog.Level 的文本格式识别级别，大小写不敏感；遇到无法识别的值时返回错误，而不是悄悄把配置改成 INFO。

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

实用做法是先准备一个明确的默认级别，再调用 UnmarshalText；解析失败就返回带字段名的错误。这样配置问题会在启动阶段暴露，日志系统本身仍保持类型安全。

先弄清它能解析什么

slog 的四个常用命名级别是 DEBUG、INFO、WARN 和 ERROR。官方文档说明，UnmarshalText 接受 MarshalText 能生成的文本，并忽略大小写；级别之间的数值偏移也可以写成类似 INFO+2 或 ERROR-8 的形式。

所以不要自己写一串 switch 去复制标准库的格式规则。自定义代码只负责取值、调用方法和决定错误策略。

封装一个带默认值的解析函数

解析函数最好接收字段名，错误信息中直接指出哪个配置项不合法。默认值由调用方传入，避免把“默认 INFO”和“用户明确配置 INFO”混在一起。

package main

import (
    "fmt"
    "log/slog"
    "strings"
)

// parseLogLevel 把配置文本转换为 slog.Level；空文本使用调用方给出的默认值。
func parseLogLevel(field, raw string, fallback slog.Level) (slog.Level, error) {
    raw = strings.TrimSpace(raw)
    if raw == "" {
        // 空配置不是非法输入，直接采用显式默认值。
        return fallback, nil
    }

    var level slog.Level
    if err := level.UnmarshalText([]byte(raw)); err != nil {
        // 保留原始输入，启动日志能直接定位配置项和错误值。
        return 0, fmt.Errorf("配置 %s 的日志级别 %q 无效: %w", field, raw, err)
    }
    return level, nil
}

这里的关键点有两个：一是先 TrimSpace，避免配置文件中的首尾空白制造误报；二是错误返回时不要返回默认级别。调用方可以决定退出启动流程，或者在明确记录告警后回退。

空值和非法值要分开处理

空值通常表示“没有配置”，非法值表示“配置存在但写错了”，两者的运维含义不同。可以在应用配置加载处区分这两种情况：

func loadConfiguredLevel(raw string) (slog.Level, error) {
    // 默认使用 INFO；只有完全没有填写配置时才走这里。
    return parseLogLevel("LOG_LEVEL", raw, slog.LevelInfo)
}

// 典型调用：错误继续向上返回，由启动入口统一决定是否退出。
level, err := loadConfiguredLevel(os.Getenv("LOG_LEVEL"))
if err != nil {
    return fmt.Errorf("加载日志配置失败: %w", err)
}

示例中的 os.Getenv 只是展示配置来源；如果来源是 JSON、TOML 或 YAML，仍然建议把最终得到的字符串交给同一个解析函数，避免不同入口出现不同规则。

数值偏移只在确有需要时使用

slog.Level 本质上是整数级别，标准命名级别之间间隔为 4，因此可以表达比 INFO 更细的中间级别。配置里使用偏移时，建议保留加减号并在文档中约定格式，例如 INFO+2。

func parseOffsetExample(raw string) (slog.Level, error) {
    var level slog.Level
    // UnmarshalText 负责解释命名级别和偏移，不要在这里手工拆分字符串。
    if err := level.UnmarshalText([]byte(raw)); err != nil {
        return 0, fmt.Errorf("日志级别格式错误: %w", err)
    }
    return level, nil
}

偏移并不等于“随意输入一个整数”。它仍然要符合 slog.Level 的文本表示；对于团队配置，命名级别更容易读，偏移只适合确实需要细分等级的场景。

把解析结果交给配置对象

一个小型配置对象可以把读取和解析放在一起，但不要让配置对象替 Handler 做日志过滤。本文只负责得到一个类型化的 slog.Level，后续是否用 LevelVar 或 HandlerOptions.Level 属于另一层决策。

type AppConfig struct {
    LogLevel slog.Level
}

func loadConfig(raw string) (AppConfig, error) {
    level, err := parseLogLevel("LOG_LEVEL", raw, slog.LevelInfo)
    if err != nil {
        return AppConfig{}, err
    }
    // 解析完成后保存类型值，后续代码不再重复解释字符串。
    return AppConfig{LogLevel: level}, nil
}

常见问题速查

结语

配置日志级别时，把“取字符串”“处理空值”“解析类型”“决定错误策略”分成四件事，代码会比手写字符串映射更稳定。slog.Level.UnmarshalText 已经覆盖大小写不敏感的标准级别和数值偏移；你的代码只需要明确默认值，并把错误连同字段名返回到启动入口。

延伸问题

• 为什么配置写成 warning 仍然失败？ 因为标准命名是 WARN，忽略大小写不等于接受同义词。
• 什么时候适合使用 slog.LevelVar？ 当级别需要在运行期间安全改变时，再考虑把解析结果写入 LevelVar。
• 能否把任意数字直接当作日志级别？ 只有符合 slog.Level 文本表示的偏移才应进入配置，不要自行约定无说明的整数格式。