4.3 OpenAPI 契约优先与版本化
到 4.2 为止，TaskHub 的接口行为已经完整：资源层级、状态码、分页、幂等。但这些约定只存在于两处——服务端的 Go 代码和我们脑子里的默契。客户端团队拿不到类型定义，前端只能照着 Postman 猜；文档手写在 Wiki 里，改一个字段名就过期；更糟的是没人知道谁在依赖哪个字段，于是谁也不敢删。
本节把 TaskHub 推进到：接口契约从「代码里的约定」升级为「先写、可生成、可校验、可检查漂移」的 OpenAPI 文件，并定下版本化与废弃规则。
4.3.1 契约优先到底改了什么
两种工作流对比：
| 维度 | 代码优先（现状） | 契约优先（本节） |
|---|---|---|
| 真相来源 | Go 结构体 | openapi.yaml |
| 客户端类型 | 手写或复制粘贴 | 从同一份 spec 生成 |
| 文档 | 手写，会过期 | 从 spec 渲染，不会过期 |
| 前后端并行 | 阻塞在接口实现 | 约定 spec 后即可并行 |
| 字段改动 | 改代码，客户端不知道 | 改 spec，CI 能拦住破坏性变更 |
「先写 spec」最大的收益不是生成代码，而是把接口讨论提前到写代码之前。当产品和前端坐下来把 POST /tasks 的请求体字段逐个敲定时，很多歧义（title 能不能为空、due_date 是不是必填、状态有哪些取值）会在写第一行 Go 代码之前就暴露。
代价也要说清楚：spec 会多一份维护成本，且生成代码的风格不一定合你意。如果团队只有一个人、接口只服务一个客户端，契约优先的收益可能小于成本——这种情况用注释生成 spec（代码优先的镜像）反而更划算。TaskHub 是多人多端的工程系统，所以走契约优先。
4.3.2 spec 的形状
TaskHub 的 api/openapi.yaml 片段（openapi: 3.0.3）：
paths:
/projects/{projectID}/tasks:
parameters:
- $ref: '#/components/parameters/ProjectID'
get:
operationId: listTasks
parameters:
- name: limit
in: query
schema: { type: integer, minimum: 1, maximum: 100, default: 20 }
- name: cursor
in: query
schema: { type: string }
responses:
'200':
description: 任务分页列表
content:
application/json:
schema: { $ref: '#/components/schemas/TaskPage' }
post:
operationId: createTask
parameters:
- name: Idempotency-Key
in: header
schema: { type: string }
requestBody:
required: true
content:
application/json:
schema: { $ref: '#/components/schemas/TaskCreate' }
responses:
'201':
description: 已创建
headers:
Location:
schema: { type: string }
content:
application/json:
schema: { $ref: '#/components/schemas/Task' }
'409':
$ref: '#/components/responses/Conflict'
'422':
$ref: '#/components/responses/ValidationError'
两条纪律：每个 operation 必须有 operationId（生成器靠它命名方法，缺了就没法生成）；公共响应抽到 components/responses，避免同一段错误体复制十遍。
operationId 的命名也要统一，TaskHub 用 资源 + 动作 的驼峰：listTasks、createTask、getTask、deleteTask。它一旦被客户端 SDK 用上就是公开契约，改名等于破坏性变更。
4.3.3 实测：用 oapi-codegen 生成骨架
生成器选 oapi-codegen。本机实测可以从 goproxy.cn 装上（proxy.golang.org 不可达，必须显式指定代理）：
GOTOOLCHAIN=go1.27.0 GOPROXY=https://goproxy.cn,direct GOBIN=/tmp/gbpractice/bin \
go install github.com/oapi-codegen/oapi-codegen/v2/cmd/oapi-codegen@v2.4.1
配置文件 api/cfg.yaml：
package: api
output: api/gen.go
generate:
models: true
std-http-server: true
strict-server: true
生成：
/tmp/gbpractice/bin/oapi-codegen -config api/cfg.yaml api/openapi.yaml
实测：从上面那份 spec（3 条路径、4 个操作）生成了 698 行 Go 代码，包含模型、路由注册、参数绑定、严格处理器接口。依赖只多了一个运行时包 github.com/oapi-codegen/runtime v1.7.0。
值得注意的生成产物有三个：
std-http-server生成的是 Go 1.22+ 原生模式，路由注册形如mux.HandleFunc("GET /api/v1/projects/{projectID}/tasks", ...)，路径参数用r.PathValue("projectID")读取——和 4.1 手写的模式完全一致，不需要第三方路由库。- 模型带
jsontag 与指针可选字段。TaskCreate.Status是*TaskCreateStatus，因为 spec 里它default: todo且非 required；指针让「未提供」和「提供了零值」可区分。 strict-server生成一套「返回响应对象」的接口，handler 不直接写http.ResponseWriter，而是返回CreateTask201JSONResponse这类值，由生成代码负责序列化与设置状态码。
4.3.4 生成的严格接口
strict-server 的接口签名如下（真实生成物）：
type StrictServerInterface interface {
ListTasks(ctx context.Context, request ListTasksRequestObject) (ListTasksResponseObject, error)
CreateTask(ctx context.Context, request CreateTaskRequestObject) (CreateTaskResponseObject, error)
DeleteTask(ctx context.Context, request DeleteTaskRequestObject) (DeleteTaskResponseObject, error)
GetTask(ctx context.Context, request GetTaskRequestObject) (GetTaskResponseObject, error)
}
请求与响应都是对象。请求对象把路径参数、查询参数、请求体打包：
type CreateTaskRequestObject struct {
ProjectID ProjectID `json:"projectID"`
Params CreateTaskParams
Body *CreateTaskJSONRequestBody
}
响应是「每种状态码一个类型」的联合体，Location 头这类响应头也有对应字段：
type CreateTask201JSONResponse struct {
Body Task
Headers CreateTask201ResponseHeaders
}
type CreateTask201ResponseHeaders struct {
Location string
}
这个设计的好处是类型层面无法回错状态码：你没法从这个 handler 返回 200，因为 spec 里只声明了 201/409/422。缺点是 handler 里会出现大量 switch 或类型断言，代码略显啰嗦。
4.3.5 实测：把 handler 接上骨架
实现 StrictServerInterface 并挂到 mux 上：
mux := http.NewServeMux()
h := api.HandlerFromMuxWithBaseURL(api.NewStrictHandler(handler{}, nil), mux, "/api/v1")
HandlerFromMuxWithBaseURL 会自动按 spec 的 paths 注册路由并加上 /api/v1 前缀。实测一轮请求，输出如下：
[server] ListTasks projectID=prj_7 limit=5 cursor=<nil> sort=-created_at
GET /api/v1/projects/prj_7/tasks?limit=5&sort=-created_at -> 200 body={"items":[{"created_at":"2026-09-25T11:00:00Z","id":"tsk_01h2","project_id":"prj_7","status":"todo","title":"写卷二第 4 章"}]}
POST /api/v1/projects/prj_7/tasks -> 201 Location="/api/v1/projects/prj_7/tasks/tsk_01h2" body={...}
POST /api/v1/projects/prj_7/tasks -> 422 body={"code":"validation_failed","message":"title is required"}
POST /api/v1/projects/prj_7/tasks -> 409 body={"code":"idempotency_conflict","message":"key reused with different body"}
GET /api/v1/projects/prj_7/tasks/tsk_01h2 -> 200 body={...}
GET /api/v1/projects/prj_7/tasks/tsk_99 -> 404 body={"code":"not_found","message":"task not found"}
DELETE /api/v1/projects/prj_7/tasks/tsk_01h2 -> 204 body=
三个细节值得注意：
- 查询参数被正确绑定：
limit=5变成了*int的 5，sort=-created_at原样传进来，路径参数prj_7进了req.ProjectID。 201的Location来自响应对象的Headers字段，不是 handler 里手写的——spec 声明了它，生成代码负责写。204没有响应体，因为 spec 里只写了description: 已删除，没有content。生成器严格照契约办事，不给你「顺手返回点东西」的机会。
4.3.6 生成器不管什么：三个真实反例
这是本节最该记住的一段。生成器只保证结构正确，不保证语义合法。实测四个畸形请求：
body={"title":"x","status":"weird"} -> 201 {"status":"todo","title":"x",...}
body={"title":123} -> 400 can't decode JSON body: json: cannot unmarshal number into Go struct field TaskCreate.title of type string
body={"title":"x"} trailing -> 201 {"status":"todo","title":"x",...}
body=not-json -> 400 can't decode JSON body: invalid character 'o' in literal null (expecting 'u')
逐条解读，都是真实行为：
| 请求 | 结果 | 说明 |
|---|---|---|
status 传了枚举外的值 | 201，被静默接受 | enum 约束不会自动校验，生成的 Go 类型是 string 别名 |
title 传数字 | 400 | 类型不匹配，JSON 解码阶段就失败 |
| JSON 后有多余内容 | 201，被接受 | 解码器读到第一个完整对象就停了，不检查尾部 |
| 完全不是 JSON | 400 | 语法错误 |
所以：enum、minLength、maxLength、pattern、minimum、maximum 这些约束，生成器一个都不校验。它们只是文档。要真正拦住，得自己加一层校验（用 validator 或手写），并且——这是关键——把校验失败映射回 spec 里声明的 422，否则你回了 400，契约又漂移了。
第二个反例（尾部多余内容）在生产里影响不大，但如果 spec 要求严格，可以在解码后用 dec.Decode(&struct{}{}) 探测是否还有残余 token。TaskHub 选择不严格，因为宽容解析对客户端更友好。
4.3.7 契约漂移检查
spec 和代码是两份东西，就会漂移：有人加了路由忘了改 spec，或者改了 spec 没改代码。把「路由集合必须一一对应」做成可执行的检查，比靠 code review 靠谱：
// 代码里实际注册的路由（与 HandlerFromMuxWithBaseURL 生成的模式一致）
registered := map[string]string{
"GET /api/v1/projects/{projectID}/tasks": "listTasks",
"POST /api/v1/projects/{projectID}/tasks": "createTask",
"GET /api/v1/projects/{projectID}/tasks/{taskID}": "getTask",
"DELETE /api/v1/projects/{projectID}/tasks/{taskID}": "deleteTask",
}
检查逻辑是双向的：代码有、spec 无 → 报「多出来的路由」；spec 有、代码无 → 报「没实现的操作」；同一路径 operationId 不一致 → 报「语义漂移」。用 gopkg.in/yaml.v3 解析 spec 即可，不需要重量级依赖。实测：
openapi=3.0.3 spec 路由数=4 代码注册路由数=4
契约漂移检查: 通过（spec 与代码路由一一对应）
为验证检查器真的有效，我故意往代码侧塞了一条 spec 里没有的路由 GET .../tasks/{taskID}/comments：
openapi=3.0.3 spec 路由数=4 代码注册路由数=5
漂移: 代码有、spec 无: GET /api/v1/projects/{projectID}/tasks/{taskID}/comments
检查器立刻抓住。这个脚本放进 CI（第 16 章）就是一道免费的护栏。更进一步，还可以校验请求体字段的集合是否与 spec 一致，但那需要更复杂的 schema 比对，收益递减——先守住路由这一层，成本最低、抓到的问题最多。
4.3.8 版本化与废弃
版本号怎么放，主流有三种：
| 方案 | 形态 | 优点 | 缺点 |
|---|---|---|---|
| URL 路径 | /api/v1/tasks | 直观、网关/CDN 易分流、日志可读 | URL 变长、同一资源多份 URL |
| 查询参数 | /api/tasks?v=1 | 改动小 | 缓存键碎片化、易被忽略 |
| 请求头 | Accept: application/vnd.taskhub.v1+json | URL 干净、REST 纯正 | 调试不便、网关难分流 |
TaskHub 选 URL 路径版本化，理由是运维友好：Nginx 按 /api/v1/ 与 /api/v2/ 分流是一行配置，日志里一眼能看出客户端用的哪个版本（第 10 章的可观测性受益）。REST 纯正性在这里不值钱。
比选方案更重要的是兼容性规则。TaskHub 的约定：
| 变更 | 是否破坏兼容 | 处理 |
|---|---|---|
| 新增可选请求字段 | 否 | 直接发 |
| 新增响应字段 | 否 | 直接发，客户端须容忍未知字段 |
| 新增枚举值 | 是 | 客户端 switch 会漏分支，须新版本或提前约定 |
| 删除/重命名字段 | 是 | 走废弃流程 |
收紧校验（如 maxLength 变小） | 是 | 新版本 |
注意「新增枚举值」被标成破坏性——这一点常被误判为兼容。如果客户端写了 switch status { case todo, doing, done } 且没有 default 分支，服务端新增 archived 就会让客户端行为未定义。
废弃流程用标准响应头表达，不靠口头通知：
Deprecation: @1798761599
Sunset: Thu, 31 Dec 2026 23:59:59 GMT
Link: <https://docs.taskhub.example.com/migrate-v2>; rel="deprecation"
Sunset 给出明确下线时间，Link 指向迁移文档。三个头都是标准（RFC 9745 / RFC 8594 / RFC 8288），网关和客户端 SDK 可以自动识别并告警。没有 Sunset 日期的「废弃」等于没有废弃——它会永远留在那里。
4.3.9 小结
- 契约优先把接口讨论提前，收益是「客户端类型 + 不过期的文档 + CI 可拦的破坏性变更」；单人项目可退回代码优先。
oapi-codegen v2.4.1实测可从 goproxy.cn 安装，从 3 条路径生成 698 行代码，路由走 Go 1.22 原生ServeMux模式。strict-server让 handler 返回响应对象，类型层面阻止回错状态码，Location头也由 spec 驱动。- 生成器不校验
enum/minLength/pattern，实测status:"weird"被201接受；语义校验要自己补，且失败要映射回422。 - 契约漂移检查（路由集合双向比对）成本最低、抓得最多，实测能抓住故意注入的多余路由。
- 版本化用 URL 路径；废弃必须给
Deprecation/Sunset/Link三个头。
接口的骨架、行为、契约都齐了。但此刻任何人只要拿到 URL 就能读写所有租户的数据——下一章补上认证与授权。
阅读导航：上一节：4.2 分页、过滤、排序与幂等 · 下一节：5.1 JWT 与会话管理 。
继续阅读
探索更多技术文章
浏览归档，发现更多关于系统设计、工具链和工程实践的内容。