fmt.Warnidf
从模板记录一条可抑制的 WARNING 日志。
这一页解决什么问题
用 fmt.Warnf 时,警告一旦给出就没法关掉——同一句话在每次构建里都会出现,久了就被无视。warnidf 给警告一个 ID,需要忽略它的人在配置里加一行 ignoreLogs 即可,日志重新变得「有问题才有噪音」。
什么时候用,什么时候别用
该用:
- 已知会被一部分使用者主动忽略的警告(可选字段、实验特性);
- 希望日志里自带抑制方法提示。
别用:
- 每条都必须看到的警告 → 用
fmt.Warnf; - 无法继续的问题 → 用
fmt.Errorf(可抑制的严重问题用fmt.Erroridf)。
用法
Go 的 fmt 包的文档描述了格式字符串的结构与内容。
warnidf 函数对格式字符串求值,然后把结果输出到 WARNING 日志。与 warnf 函数不同,你可以把消息 ID 加入项目配置的 ignoreLogs 数组,从而抑制 warnidf 函数记录的警告。
这段模板代码:
go-html-template
{{ warnidf "warning-42" "You should consider fixing this." }}产生如下控制台日志:
WARN You should consider fixing this.
You can suppress this warning by adding the following to your project configuration:
ignoreLogs = ['warning-42']要抑制这条消息:
toml
ignoreLogs = ["warning-42"]完整示例(实测)
layouts/_partials/deprecation.htmlgo-html-template
{{ warnidf "warning-42" "You should consider fixing this." }}okHugo 0.167.0 实测:构建成功(退出码 0),控制台输出
WARN You should consider fixing this.
You can suppress this warning by adding the following to your project configuration:
ignoreLogs = ['warning-42']页面产物是 ok。在 hugo.toml 里加上 ignoreLogs = ['warning-42'] 后,实测同一段模板运行时不再出现任何 WARN 行,构建依旧成功。
你应当看到什么:Hugo 自动附上「怎么抑制」的两行说明;抑制后日志干净,但构建结果完全相同——这正是它和 fmt.Warnf 的区别所在。
返回值边界(实测)
测量条件:Hugo 0.167.0 extended,单语言站点(locale = 'zh-CN'),Windows。
| 情况 | 结果 | 是否报错 |
|---|---|---|
未配置 ignoreLogs(实测) |
输出 WARN + 抑制提示两行 | 否(退出码 0) |
配置 ignoreLogs = ['warning-42'](实测) |
不出现在日志里 | 否(退出码 0) |
| ID 与配置里的字符串不一致 | 照常输出警告 | 否 |
| 同一消息多次调用 | 与 fmt.Warnf 相同,相同消息只输出一次 |
否 |
| 返回类型 | string;直接放在模板里不会输出可见内容 |
否 |
常见坑
| 类别 | 症状 | 真因 | 怎么修 |
|---|---|---|---|
| 没报错但结果不对 | 配了 ignoreLogs 警告还在 |
ID 写错(大小写、连字符) | 照抄控制台给出的 ignoreLogs = ['…'] 那一行 |
| 没报错但结果不对 | 调试时看不到重复警告 | 相同消息只输出一次(与 warnf 一致) |
用 math.Counter 让消息唯一 |
| 报错看不懂 | 构建被中止 | 误用了 fmt.Erroridf |
只想警告就用本函数 |
更多排查入口见故障排查。