用反射生成接口文档易出错，因go反射不保留字段注释且无法识别非json标签的语义，需通过自定义doc tag（如doc:"name=用户id;required=true"）显式补充元信息，并注意嵌套处理、导出字段限制、默认值标注及markdown转义等问题。
为什么用反射生成接口文档容易出错
Go 的反射（reflect）本身不保留结构体字段的原始注释，也不自动识别 json 标签以外的语义（比如 description 或 required）。直接遍历 struct 字段只能拿到类型、名字和基础标签，但无法知道“这个字段在 API 里叫什么”“是否必填”“示例值是多少”。很多团队踩坑后才发现：生成的文档字段名对不上请求体、必填标识全空、嵌套结构直接丢弃。
关键问题不在反射能力弱，而在信息源缺失——Go 没有像 Java 的 Swagger 注解那样的标准元数据机制。你得自己约定并补全这些信息。
用 struct tag 补齐文档所需元信息
必须主动在结构体字段上添加自定义 tag，否则反射拿不到业务语义。推荐统一使用 doc tag，格式为键值对，例如：doc:"name=用户ID;required=true;desc=唯一标识符;example=usr_12345"。这样反射时能解析出字段映射名、校验规则和说明。
实操建议：
- 不要混用多个 tag（如同时用
swagger、openapi），Go 生态没标准，维护成本高 -
jsontag 和doctag 分开：前者控制序列化，后者专供文档生成，避免耦合 - 嵌套结构体字段需递归处理，但注意循环引用——加个已访问 map 防止栈溢出
- 导出字段（首字母大写）才可通过
reflect访问；非导出字段会被跳过，别指望反射能“偷看”私有字段
用 reflect.Value 而不是 reflect.Type 做字段值推导
只读 reflect.Type 只能拿到字段名、类型、tag，但没法知道默认值或空值行为。而文档常需标注“缺省为空字符串”或“未传时服务端设为 false”。这时需要一个带默认值的实例（哪怕零值），用 reflect.Value 获取字段当前值，再结合类型判断语义。
例如：int 字段值为 0，不能直接标“默认 0”，得看它是否是业务上的有效值（比如年龄为 0 合理，但订单 ID 为 0 就不合理）。所以更稳妥的做法是：允许在 doc tag 里显式写 default=1，反射时优先取它。
常见错误现象：生成文档显示所有 string 字段默认值都是空字符串，所有 bool 都是 false，实际接口逻辑根本不是这样。
生成 Markdown 表格时小心 HTML 转义和缩进
反射提取完字段信息后，拼接 Markdown 表格字符串时，字段描述（desc）若含下划线、星号或反引号，会破坏表格格式。别手写拼接，用 fmt.Sprintf + 转义函数处理：
func escapeMD(s string) string {
s = strings.ReplaceAll(s, "|", "\|")
s = strings.ReplaceAll(s, "_", "\_")
return strings.ReplaceAll(s, "*", "\*")
}
另外，嵌套结构体生成子表格时，缩进要用 4 个空格（不是 tab），否则 GitHub/GitLab 渲染会错位。如果字段类型是切片（[]User），文档里要注明“数组，元素为 User 结构”，而不是只写 []main.User——后者对前端毫无意义。
真正难的不是反射怎么调，而是让每个字段的 doc tag 写得一致、可解析、不漏项。一旦团队没对齐 tag 规范，生成的文档就变成“看起来很全，其实没法用”。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
