结构体标签仅提供元数据，不触发自动转换；不同协议（如json、bson、yaml）各自解析对应标签，互不干扰，需显式调用对应编解码器。
结构体标签本身不参与协议转换，只提供元数据
结构体标签（如 json:"name"、bson:"full_name"、yaml:"log_level"）不是运行时行为开关，也不触发任何自动转换逻辑。它只是字符串字面量，被反射读取后由对应库按约定解释。比如 encoding/json 只看 json 标签，mgo 或 mongo-go-driver 只认 bson 标签，二者互不干扰。
常见误解是“加了多个标签就能自动适配多协议”，实际必须显式调用对应编解码器：用 json.Marshal 时只生效 json 标签，用 bson.Marshal 时只生效 bson 标签。标签之间没有继承或 fallback 关系。
- 字段未加对应标签 → 该协议下字段被忽略（如没写
bson:"id"，MongoDB 插入时该字段为空） - 标签值拼写错误（如
json:"user_id"写成json:"user_id "带空格）→ 编解码器无法匹配，静默丢弃 - 字段未导出（首字母小写）→ 反射不可见 → 所有基于反射的协议库均无法访问该字段
避免在单个结构体上堆砌多套标签
把 json、bson、xml、mapstructure 全塞进一个结构体，短期看似省事，长期会带来三类问题：字段语义模糊、改名牵一发而动全身、测试难以隔离。
比如 MongoDB 字段重命名为 user_fullname，你得同步改 bson 标签；API 要求返回 fullName，又得调 json 标签；YAML 配置里想用 full_name，还得补 yaml 标签——所有变更都耦合在同一处。
立即学习“go语言免费学习笔记（深入）”；
- 推荐做法：为每层协议定义独立结构体，如
UserDB（带bson）、UserAPI（带json）、UserConfig（带mapstructure） - 转换逻辑写在 service 层，用普通字段赋值，不依赖反射或通用 mapper —— 可读、可 debug、可单元测试
- 若真需复用字段名映射逻辑，可提取公共常量，如
const FieldName = "full_name"，但不要靠标签自动对齐
mapstructure 是配置解析的事实标准，别硬套 json.Unmarshal
框架配置（YAML/JSON/TOML）几乎都用 snake_case，而 Go 结构体习惯 camelCase。用 json.Unmarshal 解析时，没写 json 标签的字段直接丢弃，字符串数字混用（如 "timeout": "30" → Timeout int）会 panic 或设为零值，且无提示。
mapstructure.Decode 默认启用大小写不敏感 + 下划线/驼峰双向匹配，LogLevel 自动匹配 log_level、LOG_LEVEL、logLevel，无需标签也能工作。
- 加
mapstructure标签仅用于强制指定键名，如Timeout int `mapstructure:"timeout_sec"` - 嵌套字段支持点号路径：
DBHost string `mapstructure:"database.host"` - 字符串转时间等自定义转换，必须配
DecodeHook，默认不处理time.Time或uuid.UUID - 字段必须导出（首字母大写），否则
mapstructure无法反射赋值
标签里的选项（如 omitempty）只对对应协议生效
json:"name,omitempty" 中的 omitempty 是 encoding/json 包识别的指令，表示零值字段不输出；但它对 bson 或 yaml 完全无效。同理，bson:",omitempty" 不影响 JSON 输出。
更隐蔽的问题是：不同协议对“零值”的定义可能不同。比如 string 在 JSON 中 "" 是零值，但在某些 YAML 解析器中 null 和 "" 被视为不同；int 的零值 0 在配置场景中可能有业务含义（如超时设为 0 表示禁用），此时 omitempty 反而造成信息丢失。
- 不要假设
omitempty在所有协议下行为一致 - 涉及业务语义的零值（如
RetryCount int设为 0 表示不重试），应避免用omitempty，改用指针或显式布尔标记字段是否设置 - 测试时务必覆盖空字符串、0、false 等边界值，确认各协议编解码结果符合预期
