Go反射无法可靠生成API文档，因缺失HTTP方法、路径等元信息且易静默失效；struct tag解析脆弱，需用structtag.Parse替代Tag.Get；非导出字段和跨包嵌套类型不可见；路由关联须靠源码注释而非反射。
Go 反射不能直接用于生成可用的 API 文档——它缺关键元信息，且极易静默失效。所有依赖 reflect 的“自动生成”方案，最终都得靠人工补全 HTTP 方法、路径、字段语义等核心信息，否则产出的文档要么字段全空，要么类型错乱、路径丢失。
为什么 reflect.StructField.Tag.Get("doc") 常返回空？
这不是你没写 tag，而是 Go 的 struct tag 解析器太脆弱：中文引号、换行、多余空格、未闭合引号都会导致 Tag.Get("doc") 静默返回空字符串，不报错也不警告。
- 别用
if tag := f.Tag.Get("doc"); tag != ""判定是否存在——它无法区分“真没写”和“写错了” - 改用
structtag.Parse（来自golang.org/x/tools/go/ast/structtag）做健壮解析，能明确报出语法错误位置 - 字段没写
doctag 时，留空比硬填 “无描述” 更安全；前端渲染可 fallback 到字段名
非导出字段和嵌套结构体为何在文档里消失？
反射根本访问不到小写开头的字段：Field(i).Name 为空，IsExported() 返回 false；嵌套结构体若含未导出类型（如 type address struct）、接口（Info interface{}）或跨包类型（*github.com/org/pkg.Model），递归会直接中断。
Golang Uber Dig
下载
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
- 确保所有需入文档的字段首字母大写，哪怕 JSON 键要小写，也用
json:"name"单独控制 - 对嵌套字段，必须显式检查
t.Kind()和t.PkgPath()：未导出类型无法展开，跨包类型需截取path.Base(t.PkgPath()) - 遇到
interface{}或泛型字段，反射只能拿到interface{}，无法推导实际类型——必须靠// @Model注释或自定义 tag 显式声明
http.HandlerFunc 和路由路径怎么通过反射关联？
http.ServeMux 内部的 mu.m 是 unexported map，反射读不到；runtime.FuncForPC(reflect.ValueOf(h).Pointer()) 在编译优化或内联后常返回 unknown，不可靠。
立即学习“go语言免费学习笔记（深入）”；
- 别试图从标准库 mux 中“抽出路由”，这是死路
- 自己封装注册函数，例如
RegisterHandler(pattern, h, method)，把路径、方法、handler 名存进全局 slice - handler 函数上方加
// @method POST /api/users注释，再配合go/parser解析源码，比纯反射靠谱得多
真正落地的文档生成（如 swag）完全绕开了运行时反射，转而静态解析源码注释——因为反射拿不到的信息，代码注释里可以明确定义。想靠 reflect 省事，最后花在 debug 字段空、路径丢、类型崩上的时间，远超手写几行注释。
