Golang怎么用OpenAPI规范设计接口_Golang如何先写API文档再用oapi-codegen生成代码【指南】-Golang-PHP中文网

oapi-codegen生成Go服务端代码需显式指定-generate=types,server,client，否则缺失RegisterHandlers和ServerInterface实现；路径参数须用chi.URLParam提取，字段映射需x-go-name扩展，安全机制需手动实现。

golang怎么用openapi规范设计接口_golang如何先写api文档再用oapi-codegen生成代码【指南】

OpenAPI YAML 写完后，`oapi-codegen` 生成的 Go 代码跑不起来？

常见现象是 go run main.go 报错：找不到 RegisterHandlers、ServerInterface 方法未实现、或 HTTP 路由 404。根本原因不是 YAML 写错了，而是生成时没分层——oapi-codegen 默认只生成类型定义，不生成服务端骨架。

必须显式用 -generate=types,server,client（缺一不可），只写 types 或漏掉 server 就没有 handler 注册逻辑
server 模式生成的接口名是 ServerInterface，但实际要实现的是它的嵌套方法（如 CreateUser），不是重写整个接口
生成的 RegisterHandlers 函数依赖 chi 或 gorilla/mux，但 oapi-codegen 不自动引入这些包——你得自己 go get 并在 main.go 中手动调用它
如果 OpenAPI 中路径带参数（如 /users/{id}），生成的 Go 方法签名里对应参数叫 Id（首字母大写），但传入时得从 chi.URLParam(r, "id") 提取，别直接用 r.URL.Query().Get("id")

用 `oapi-codegen` 时，`components.schemas` 和 `requestBody` 的字段名大小写总对不上

Go struct 字段导出规则和 OpenAPI 的 camelCase / snake_case 映射不是自动的——oapi-codegen 默认按 OpenAPI 字段名原样转成 PascalCase，但 JSON 序列化时若没加 tag，就会用字段名当 key，导致 POST body 解析失败。

在 OpenAPI YAML 里给字段加 x-go-name 扩展（如 x-go-name: UserID），否则 user_id 会变成 UserId，但 JSON tag 还是 "user_id"
更稳妥的做法是统一用 x-go-type + 自定义 type（比如 type UserID string），避免所有字段都靠命名猜测
如果用了 allOf 组合 schema，生成的 struct 会嵌套匿名字段，但 JSON unmarshal 不支持跨层解析——建议改用 oneOf 或拆成独立 schema

`oapi-codegen` 生成的 client 为什么发请求老是 400？

不是 URL 拼错了，大概率是请求头或 payload 格式不匹配 OpenAPI 定义的 content-type 和 schema。client 代码本身没错，但调用时没按契约填参。

Golang Uber Dig

使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等

下载

如果 OpenAPI 声明了 application/json，但你在调用 CreateUser(ctx, user) 时传了个没导出字段的 struct（比如字段全小写），JSON 序列化后是空对象 {}
路径参数（path）和查询参数（query）必须严格区分：路径参数走函数参数，查询参数走结构体字段——别把 limit 放进 path 参数里传
生成的 client 默认不设超时，线上调用可能卡死；得自己 wrap context.WithTimeout，不能依赖 client 方法自带
错误处理容易忽略：err 是 Go error，但具体 HTTP 状态码藏在 *http.Response 里，需断言为 *ClientError 并读 StatusCode

OpenAPI 文档里写了 `security`，但 `oapi-codegen` 生成的 server/client 完全没处理鉴权逻辑

对。oapi-codegen 把 security 当作文档注释，不生成任何中间件或 header 校验代码——它只负责“契约即代码”，不负责“契约即安全”。

server 端得自己写 middleware 拦截 Authorization header，再调 strings.HasPrefix(auth, "Bearer ") 提 token，这部分完全不在生成范围内
client 端虽然生成了 WithRequestEditorFn 参数，但默认是空函数；你要传一个闭包去塞 header：WithRequestEditorFn(func(ctx context.Context, req *http.Request) error { req.Header.Set("Authorization", "Bearer "+token); return nil })
如果 OpenAPI 里用了多个 security scheme（如 ApiKey + OAuth2），生成的 client 方法不会自动选哪个，你得自己控制 editor 函数的执行逻辑

最常被跳过的一步：OpenAPI 的 info.version 变了，但没同步更新生成代码的 go:generate 指令里的输出路径或 checksum。结果改了文档，却还在跑旧版 struct，字段多删少都没报错，直到 runtime panic。