go不支持反射自动生成api文档，因字段注释丢失、http方法/路径不可知、嵌套结构语义模糊，需人工补全元信息；reflect.structtag解析脆弱，应使用structtag.parse健壮解析；非导出字段、嵌套未导出类型、接口类型导致反射中断；路由信息无法通过反射提取，需封装注册函数；跨包类型等使类型名不可读，需按kind分类处理；swag静态解析注释才是可靠方案。
Go 本身不支持基于反射的自动化 API 文档生成——这不是能力问题，而是设计取舍。所有号称“用反射自动生成文档”的方案，实际都卡在字段注释丢失、HTTP 方法/路径不可知、嵌套结构语义模糊这三道坎上，最终仍要靠人工补全元信息。
reflect.StructField.Tag.Get("doc") 返回空 ≠ 没写 tag
很多人以为 Tag.Get("doc") 返回空字符串就是没写 tag，其实更可能是解析失败：tag 值里有未闭合引号、换行符、多余空格，或者用了中文引号。Go 的 reflect.StructTag 解析器非常脆弱，一出错就静默返回空字符串，不会报错也不会警告。
- 别用
if tag := f.Tag.Get("doc"); tag != ""判定是否存在——它无法区分“真没写”和“写错了” - 改用
structtag.Parse（来自golang.org/x/tools/go/ast/structtag）做健壮解析，或至少加一层strings.TrimSpace+ 正则校验 - 字段没写
doctag 时，留空比硬填 “无描述” 更安全；前端渲染可 fallback 到字段名
非导出字段、嵌套结构、接口类型都会导致反射中断
反射能拿到 User.Profile.Address.Street，但文档里只显示到 Profile，Address 及以下全空——这不是递归没写好，而是类型系统断层了。
- 非导出字段（小写开头）即使写了
doc:"xxx"，reflect也根本拿不到该字段：Field(i).Name为空，IsExported()为false - 嵌套字段类型是未导出 struct（如
type address struct { Street string }），反射无法访问其内部，递归直接终止 - 嵌套字段是接口类型（如
Info interface{}），reflect.TypeOf只能拿到interface{}，无法推导具体实现 - 字段带
json:"-"或swaggerignore:"true"，但你的反射逻辑没检查这些 tag，就会跳过本应展示的字段
http.HandlerFunc 和路由绑定关系无法通过反射提取
http.ServeMux 内部的 mu.m 是 unexported map，反射读不到；runtime.FuncForPC(reflect.ValueOf(h).Pointer()) 在编译优化或内联后常返回 unknown，不可靠。
- 硬扫源码或 patch 标准库都不现实
- 自己封装一层路由注册：写个
RegisterHandler(pattern string, h http.HandlerFunc, method string)，把pattern、method、handler名存进全局 slice - 避免用
http.HandleFunc直接调用，否则信息就断了 - 注意：
FuncForPC在内联函数或编译优化后可能不准，开发环境够用，生产建议配合注释标记，比如在 handler 函数上方加// @summary 用户登录
跨包类型、指针、切片会让生成的类型名变得不可读
反射拿到的 reflect.Type.String() 对命名类型只返回本地包名下的短名（如 User），但一旦是嵌套、指针、切片或跨包类型，就会带完整路径，比如 *main.User 或 []github.com/x/y.Z。直接塞进文档，可读性崩塌。
- 用
t.Kind()分类处理：对reflect.Ptr、reflect.Slice、reflect.Map递归展开 - 只对
reflect.Struct和reflect.Interface看PkgPath() - 若
t.PkgPath() == "main" || t.PkgPath() == ""，取t.Name()；否则用path.Base(t.PkgPath()) + "." + t.Name() - 对内建类型（
string、int64）单独处理，避免误加包前缀
真正落地的方案不是靠反射猜，而是用 swag 静态解析源码注释——它不依赖运行时，不碰 reflect，也不试图从 http.ServeMux 里挖路由。你写的每行 // @Param 和 // @Success，都是对反射无力处的显式补全。那些“自动”二字背后的空白，终究得靠人来填。
大量免费API接口：立即使用
涵盖生活服务API、金融科技API、企业工商API、等相关的API接口服务。免费API接口可安全、合规地连接上下游，为数据API应用能力赋能！
