swag init 找不到 handler 函数是因为默认只扫描当前模块内文件，需用 -d 指定多目录、-g 指定入口文件，且 handler 文件须为非 main 包、无语法错误、注释紧贴函数并含 @summary/@success/@router，结构体字段须导出并带 json tag。
swag init 找不到 handler 函数？检查扫描路径和入口文件
swag init 默认只扫描当前目录及子目录下属于同一 Go module 的 .go 文件，如果 handler 分散在 internal/handler、pkg/api 等路径，它根本不会去读——结果就是 docs/swagger.json 里 "paths":{}，Swagger UI 空白。
- 用
-d显式指定多个扫描目录：swag init -d internal/handler -d pkg/api - 入口文件（如
cmd/app/main.go）必须用-g指定：swag init -g cmd/app/main.go，否则跨包注册的路由逻辑会被漏掉 - 被扫描的文件不能是
package main（除非它真写了r.GET()），推荐把路由逻辑单独放在package router或package api - 所有 handler 文件必须有合法
package xxx声明，且不能含语法错误，否则整文件静默跳过
注释写错导致字段不显示或类型报错？别依赖 Go 类型系统
swag 不做运行时反射，它的类型解析器和 Go 编译器不一致：它只认基础类型名（string、int、bool、float64）和已用 // @Model 显式声明过的 struct。写错就直接报 cannot find type definition for "uuid.UUID" 或字段全空。
Golang Spf13 Viper
下载
Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。
-
@Param id path string true "用户ID"✅ —— 路径/查询/请求头参数只能用基础类型，别写int64或uuid.UUID -
@Param user body UserReq true "用户信息"✅ —— 请求体必须指向一个已定义 struct，且该 struct 上方需有// @Model注释 -
@Success 200 {object} UserResponse✅ —— 结构体字段必须导出（首字母大写），且带json:"xxx"tag；json:"-"或小写字段名不会出现在 schema 中 - 数组参数不能简写为
type: []string，得写成：@Param ids query array true "ID列表" collectionFormat:multi items.type:string
Swagger UI 访问 404 或页面空白？静态资源没挂对
/swagger/index.html 报 404 不是路由没注册，而是 Gin/Echo 没正确托管前端资源。Swagger UI 是单页应用，依赖 History API 回退，不能用 router.Static() 挂载普通静态目录。
- 确认
swag init成功后，项目下存在docs/docs.go和docs/swagger.json - Gin 用户加这行：
router.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))—— 注意*any不能省，否则/swagger/swagger-ui.css这类子路径全 404 - Echo 用户用
echoSwagger.WrapHandler，net/http 用户得用http.FileServer配合路径重写，不是简单http.Handle("/swagger/", ...) - 上线前务必移除或条件编译掉 Swagger 路由注册代码；
docs/swagger.json包含所有接口细节，包括敏感路径和内部错误码
中文乱码、响应体显示 “object”、字段全空？三个硬性条件缺一不可
文档加载后中文变 \u4f60\u597d，或点开 schema 全是空对象，大概率不是配置问题，而是代码层面没满足 swag 的硬性要求。
- 所有 handler 函数上方的注释块必须紧贴函数声明，中间不能有空行
- 每个 handler 至少要含
// @Summary、// @Success、// @Router三类基础注释 - 结构体字段必须导出（首字母大写）+ 带
json:"xxx"tag + 不是json:"-"；哪怕只差一个jsontag，字段就不会出现在文档中 - 全局注释（如
// @title、// @version）必须写在main.go或其他被-g指定的入口文件里，不能分散
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
