oapi-codegen生成失败主因是OpenAPI未正确声明为3.0格式或$ref路径非法：须在main.go首行非空注释写// @openapi 3.0.0，且$ref路径需相对主文件、缩进统一用2空格；生成客户端字段缺失则多因responses.content.schema定义不完整或嵌套数组未显式展开。
oapi-codegen 生成失败：检查 openapi 版本声明和 $ref 路径是否合法
生成直接报错或生成的客户端缺少字段，大概率是 OpenAPI 文档没被识别为 3.0 格式，或 $ref 指向了不可达路径。
-
swag init默认不输出 OpenAPI 3.0 —— 必须在main.go顶部第一行非空注释写// @openapi 3.0.0，不能缩进、不能有空格、不能放在函数里 - 检查生成的
docs/swagger.json开头是否为"openapi": "3.0.0"，不是就说明注释未生效 -
$ref: "./schemas/User.yaml"中路径必须相对于 OpenAPI 主文件所在目录；若引用远程 URL（如https://...），默认不支持，需加-parse-components或提前用openapi-cli合并 - YAML 缩进不一致（混用 tab 和 space）会导致 kin-openapi 解析失败，报
failed to resolve reference，建议统一用 2 空格缩进
生成客户端代码时，oapi-codegen 的 -config 配置关键项
不用配置文件也能跑，但一涉及多文件、自定义包名或框架适配，就必须靠 cfg.yaml 控制行为，否则生成的 import 路径错乱、类型重复、HTTP 客户端无法编译。
-
package：生成代码的包名，不能和项目主包同名，否则go build会报import cycle -
generate.client: true是显式开关，仅写client: true不生效；同理chi-server、gin-server是独立开关，不是server: true的子项 -
import-mapping必须用绝对路径或相对于当前配置文件的路径映射到 Go 包路径，例如：./common.yaml: github.com/your/app/common - 如果 OpenAPI 里用了
oneOf或cookie认证，确保用的是oapi-codegen/v2，旧版deepmap/oapi-codegen对 3.0.2+ 特性支持不全，会 panic
生成后调用 Client.GetUsers 报错：检查返回结构与 responses.content 是否匹配
生成的客户端方法签名看似正常，但运行时反序列化失败（如 json: cannot unmarshal object into Go struct），通常是因为 OpenAPI 中 responses.200.content.application/json.schema 没正确定义，或指向了错误组件。
Golang Uber Dig
下载
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
- 确认
responses.200.content.application/json.schema是一个完整 schema（type: object或$ref到components/schemas/XXX），而不是裸字段列表 - 避免把
required写在properties外层——kin-openapi 校验会通过，但 oapi-codegen 生成的 struct tag 会漏掉json:",required"，导致解码时忽略缺失字段而不报错 - 如果响应是数组，schema 必须是
type: array; items: { $ref: ... }，不能直接$ref: "#/components/schemas/UserList"且该UserList定义为type: array—— oapi-codegen 目前不自动展开嵌套数组定义 - 用
oapi-codegen -debug -config cfg.yaml api.yaml查看中间解析结果，确认生成的 Go struct 字段名和 JSON key 是否一致（注意name和x-go-name扩展字段的影响）
多人协作中 OpenAPI 变更后，如何安全更新生成代码
直接 oapi-codegen 覆盖重写会丢掉手改的适配逻辑（比如自定义 HTTP header 注入、error wrap），也不能自动检测 breaking change。
立即学习“go语言免费学习笔记（深入）”；
- 把生成文件（如
client.gen.go）加入.gitignore，改用go:generate命令管理：在client/client.go顶部加//go:generate oapi-codegen -config cfg.yaml ../api.yaml - 每次更新前先运行
kin-openapi校验：go run github.com/getkin/kin-openapi/openapi3 -validate api.yaml，它比 oapi-codegen 自带校验更早暴露required位置错误、content缺失等规范级问题 - 对关键变更（如删除字段、改
required、调整oneOf分支）做 diff：生成前后分别git add -N新文件，再git diff --no-index old/client.gen.go new/client.gen.go，人工确认破坏性改动 - 不要信任“生成即可用”——生成的
Client默认用http.DefaultClient，生产环境务必传入带 timeout 和 retry 的自定义 client
$ref 路径拼错 + openapi: "3.0.0" 注释位置不对，这两个点一错，后面所有生成都白忙。 
