Go结构体字段必须首字母大写且类型严格匹配：小写字段被忽略，字符串与int/bool等类型不匹配时静默失败；time.Time、切片、嵌套结构体、map[string]struct{}需正确声明；推荐toml.Unmarshal+os.ReadFile（需strip BOM），写入用toml.MarshalIndent。
结构体字段必须首字母大写，且类型严格匹配
Go 的反射机制只处理导出字段，小写字段（如 port int）会被 toml.DecodeFile 完全忽略，解析后值为零值，也不报错——这是最常被忽视的静默失败点。
类型不匹配同样危险：TOML 写了 port = "8080"（字符串），而结构体定义 Port int，解析会跳过该字段，Port 保持 0；布尔值写成 enabled = "true" 也会失败，必须是裸写 enabled = true。
-
time.Time字段才能自动解析2026-05-25T12:00:00Z，用string会原样保留 - 数组（如
ports = [8080, 8081]）必须映射为切片Ports []int，不能是数组或[]interface{} - 嵌套表（如
[database]）必须用嵌套结构体，不能用map[string]interface{}—— 否则字段为空且无提示
动态键（如 [datatitle.users."12345"]）必须用 map[string]struct{}
标准结构体映射只支持静态字段名，遇到 key 是变量（比如用户 ID、插件名、环境标识）时，硬编码字段会失效。例如 TOML 中的：
[datatitle] enable = true userids = ["12345", "67890"] [datatitle.users."12345"] prop1 = 30 prop2 = 10 [datatitle.users."67890"] prop1 = 42 prop2 = 7
正确做法是定义 Users map[string]UserConfig 字段，其中 UserConfig 是导出结构体：
立即学习“go语言免费学习笔记（深入）”；
- 不要试图用
toml:"users"tag 绑定到 slice 或单个 struct -
map的 key 类型必须是string，value 类型必须是导出结构体（首字母大写字段） - 若需校验 key 是否在
userids列表中，得额外写逻辑，库本身不提供约束
优先用 toml.Unmarshal + os.ReadFile，而非 DecodeFile
toml.DecodeFile 看似方便，但它内部打开文件后直接调用 Decode，无法控制错误上下文，且对 BOM 处理不友好；更关键的是，它掩盖了“读取失败”和“解析失败”的区别。
推荐组合：os.ReadFile 显式读取字节，再传给 toml.Unmarshal：
- 便于单元测试：直接传入
[]byte模拟不同配置内容 - 可统一处理读取错误（如文件不存在、权限不足）与解析错误（格式非法、类型不匹配）
- 若文件带 UTF-8 BOM（常见于 Windows 编辑器保存），
os.ReadFile返回的 bytes 开头含\xef\xbb\xbf，需提前 strip，否则Unmarshal报invalid character 'ï' looking for beginning of value
写入 TOML 时务必用 toml.MarshalIndent 和 os.WriteFile
toml.Marshal 输出紧凑格式（无缩进、无空行），人类几乎不可读；生产环境生成或更新配置文件，必须用 toml.MarshalIndent(v, " ")。
写入操作本身也容易出错：
- 永远用
os.WriteFile(filename, data, 0644)—— 原子写入，避免崩溃导致配置文件损坏 - 不要用
os.OpenFile+Write，尤其不能先Truncate再写，中间失败就只剩半截文件 - 结构体中指针字段为
nil时，MarshalIndent会跳过该字段，不是 bug，但容易误判为“字段丢失”
复杂点在于动态键和嵌套表混合场景——比如既要支持 [users."12345"]，又要允许运行时新增用户配置并写回文件，这时 map 的 key 排序、字段顺序、注释保留都不可控，建议只读配置用 TOML，写回场景改用 JSON 或数据库。
