API changelog 必须自动化生成，因人工维护易漏改、滞后、格式不一致；应基于 swaggo/swag 解析 Go 注释生成 OpenAPI，再结构化比对两版本文档，重点识别路径、参数、响应三类变更，并结合 AST 处理语义等价问题。
API changelog 为什么不能靠人工维护
人工写 changelog 容易漏改、滞后、格式不一致，尤其在多人协作或 CI/CD 频繁发布时，git log 或 PR 描述根本没法直接映射到 API 变更（比如新增 /v2/users、删除 DeprecatedXField 字段）。真正要自动化的不是“版本日志”，而是“接口契约变更”——这必须从代码定义出发，而非提交信息。
用 swaggo/swag 解析 Go 注释生成 OpenAPI，再 diff
Go 生态里最靠谱的起点是 swaggo/swag：它能把 // @Summary、// @Param、// @Success 这类注释编译成标准 openapi.json。changelog 的差异源就来自两个版本的 OpenAPI 文档比对。
实操建议：
- 确保所有 handler 函数都带完整注释，特别是
@Param（含in: path/query/body）和@Success（含schema引用） - CI 中为每个 tag 自动生成
docs/swagger.json，例如：swag init -g cmd/server/main.go -o docs/ - 用
openapiv3库（如github.com/getkin/kin-openapi/openapi3）加载两个版本的 JSON，逐项比对Paths、Components.Schemas、Components.Responses - 注意：
swag默认不解析 struct tag（如json:"user_id,omitempty"），字段增删需靠go/parser扫描 struct 定义补充校验
diff 时重点抓三类变更，别被 schema 字段顺序骗了
OpenAPI 的 json.Marshal 输出字段顺序不稳定，直接字符串 diff 会误报。必须结构化比对：
Golang Spf13 Viper
下载
Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。
立即学习“go语言免费学习笔记（深入）”；
-
路径级变更：新增/删除
GET /api/v1/orders算重大变更；PUT /api/v1/orders/{id}方法从200改成204算行为变更 -
请求参数变更：path 参数变 query、query 参数加
required: true、body schema 中字段类型从string改integer -
响应结构变更：schema 中字段名删除（
User.Name→User.FullName）、嵌套层级变化（data.user→user）、nullable: true改为false
示例：判断字段是否被删除，不能只看 key 是否缺失，要检查旧 schema 中该字段是否存在且新 schema 中无等价字段（考虑 json tag 别名）。
生成 human-readable changelog 的关键取舍
机器能识别变更，但“是否向用户暴露”得靠规则过滤。比如：
- 忽略
v1alpha1、debug/路径下的变更 - 把
CreatedAt *time.Time `json:"created_at"`→CreatedAt time.Time `json:"created_at"`（指针变非指针）标为breaking，因客户端可能依赖空值语义 - 对
swagger.json中x-changelog-ignore: true扩展字段做白名单跳过 - 输出格式推荐 Markdown 表格 + emoji 前缀：
⚠️ Breaking、➕ Added、➖ Removed
真正难的是语义等价判断——比如 type UserID int64 和 type UserId int64 在 OpenAPI 里都是 integer，但 Go 层面是不同命名。这类必须结合 AST 分析源码，仅靠 OpenAPI 无法覆盖。
