Go不支持基于反射的自动化API文档生成，因字段注释丢失、HTTP方法/路径不可知、嵌套结构语义模糊三大问题需人工补全元信息；reflect.StructField.Tag.Get("doc")返回空可能是解析失败而非未写tag；非导出字段、未导出嵌套结构、接口类型、跨包类型、路由绑定、time.Time及泛型等场景均存在反射局限，必须依赖健壮解析、显式tag或源码注释补全业务语义。
Go 本身不支持基于反射的自动化 API 文档生成——这不是能力问题，而是设计取舍。所有号称“用反射自动生成文档”的方案，实际都卡在字段注释丢失、HTTP 方法/路径不可知、嵌套结构语义模糊这三道坎上，最终仍要靠人工补全元信息。
reflect.StructField.Tag.Get("doc") 返回空字符串的真正原因
很多人以为 Tag.Get("doc") 返回空就是没写 tag，其实更可能是解析失败：tag 值里有未闭合引号、换行符、多余空格，或者用了中文引号。Go 的 reflect.StructTag 解析器非常脆弱，一出错就静默返回空字符串，不会报错也不会警告。
- 别用
if tag := f.Tag.Get("doc"); tag != ""判定是否存在——它无法区分“真没写”和“写错了” - 改用
structtag.Parse（来自golang.org/x/tools/go/packages）做健壮解析，或至少加一层 trim + 正则校验 - 字段没写
doctag 时，留空比硬填 “无描述” 更安全；前端渲染可 fallback 到字段名 - 注意：非导出字段（小写开头）即使写了
doc:"xxx"，reflect也根本拿不到该字段，Field(i).Name为空，IsExported()为 false
嵌套结构体字段在文档中消失的常见场景
反射能拿到 User.Profile.Address.Street，但生成的文档里只显示到 Profile，Address 及以下全空——这不是递归没写好，而是类型系统断层了。
- 嵌套字段类型是未导出 struct（如
type address struct { Street string }），反射无法访问其内部，递归直接终止 - 嵌套字段是接口类型（如
Info interface{}），reflect.TypeOf只能拿到interface{}，无法推导具体实现 - 字段带
json:"-"或swaggerignore:"true"，但你的反射逻辑没检查这些 tag，导致跳过本应展示的字段 - 跨包类型（如
*github.com/org/pkg.Model）在文档中显示为完整路径，可读性差；需用t.PkgPath()+path.Base()截取包名，且对内建类型（string、int64）单独处理
http.HandlerFunc 和路由绑定关系无法通过反射提取
http.ServeMux 内部的 mu.m 是 unexported map，反射读不到；runtime.FuncForPC(reflect.ValueOf(h).Pointer()) 在编译优化或内联后常返回 unknown，不可靠。
立即学习“go语言免费学习笔记（深入）”；
- 别试图扫描标准库 mux 实例——它不提供公开遍历接口，硬来只能 patch 源码或依赖 debug build
- 自己封装注册函数，把
pattern、method、handler名、summary注释存进全局 slice，再统一导出 - 若 handler 是闭包或方法值（如
u.CreateUser），FuncForPC失效概率极高，必须配合源码注释标记（如// @method POST /api/users）+ AST 解析补全 - Gin/Echo 用户更简单：它们的
Router对象支持Walk()方法，可真实遍历已注册路由，这才是反射可用的边界
time.Time 和泛型类型在反射文档中显示异常
time.Time 字段在文档里变成 number 或 string 不一致，泛型结构如 Result[T] 直接退化为 object——反射看到的是运行时擦除后的原始类型，不是你写的源码语义。
-
time.Time必须显式加json:"created_at" time_format:"2006-01-02T15:04:05Z"，否则 swag 或反射工具按底层int64处理，文档类型失真 - 泛型实例（如
Result[User]）在反射中是reflect.Struct，但字段类型是interface{}，无法还原T；必须靠注释手动指定：// @Success 200 {object} model.Result{data=model.User} - 别指望
reflect.Value.Interface()能取出泛型实参——Go 运行时没有保留泛型类型参数，这是语言限制，不是工具缺陷 - 如果结构体字段类型是
any或interface{}，文档里只能标为object，除非你用自定义 tag 显式声明：doc:"schema=User"
真正难的不是写反射代码，而是决定哪些信息必须人工标注、哪些可以自动推导。字段是否必填、默认值是什么、时间格式怎么序列化——这些业务语义，反射永远拿不到，只能靠约定好的 tag 或注释补全。一旦漏掉，生成的文档就和实际接口行为脱节，比没有文档还危险。
