docs(memory): 记录 ini 键名静默失效的根因与配置约定

2026-10-21 13:41:49 +08:00
parent d300167a30
commit bfdc5089c5
2 changed files with 56 additions and 0 deletions
@@ -37,3 +37,18 @@
  `grep | cat -A` 不显示 `^M` 极易误判 → Python 替换用 `\r\n` 锚点，写后统计 `b'\r\n'` 复核。
 - ⚠️ Go 里 `time.Duration(60)` = 60 **纳秒**，测试写裸数字会让封禁/冷却瞬间过期 → 一律 `60 * time.Minute`。
 - ⚠️ 测 `IsBanned` → 403 必须注册中间件（`f.Use(autobanMiddleware(ab, hp))`），只注册路由+NotFound 会被绕过。
+
+## 配置（ini）相关约定
+
+- ⚠️ **ini 对未知键静默忽略** → 键名写错 = 配置不生效且无任何现场线索。
+  已加两道防线（`internal/conf/keynorm.go` + `unknown.go`）：
+  键名归一化（自动纠正常见误拼）+ 未知键启动告警（附最接近的合法键名）。
+- ⚠️ **键名必须与代码逐字一致**，包括警告文案里提到的键名 —— 写错等于误导运维。
+- ⚠️ `MapTo` 在**键缺失/值非法时不覆盖**目标字段 → 可安全预置缺省值。
+- ⚠️ **bool 的 ini 解析是「有键才赋值」** → 「未配置」与「显式 false」无法用零值区分，
+  必须用 `HasKey` 判定。缺省为 true 的开关尤其要小心（否则未配置 = 关闭）。
+- 归一化必须在 `MapTo` **之前**执行，否则错拼的键已被丢弃。
+- 合法键名白名单由**反射从结构体 ini tag 得出**，是单一事实来源；新增配置项自动纳入。
+- `TestSampleIniHasNoUnknownKeys` 回归检测：官方样例配置零误报。
+  改结构体字段名时必须同步 `conf/app.sample.ini`，否则这个测试会失败。
+- app.sample.ini 里不要留「代码中从未读取」的死配置（`title` / `xsrf_expire` 已清理）。