API接口定义应单独建api子模块（如github.com/yourorg/project/api），避免与业务逻辑混在main包；Protobuf需规范字段命名、json_name及go_package；OpenAPI应由.proto自动生成；模块路径含/v1体现语义版本，兼容变更发小版本，不兼容则升v2。
API接口定义该放在哪里？别塞进main包
Go模块里API定义不能和业务逻辑混在main包里，否则无法被其他服务复用或生成客户端SDK。正确做法是单独建一个api子模块（比如github.com/yourorg/project/api），用go mod init初始化为独立模块，再通过replace或发布版本供内部引用。
常见错误：把protobuf文件或OpenAPI YAML直接扔进cmd/或internal/下——这会导致生成的Go结构体无法导出，第三方调用时字段全变成小写、不可见。
-
api/v1目录下放service.proto和openapi.yaml，确保package声明为v1且所有message名首字母大写 - 在
api/go.mod中显式require依赖项（如google.golang.org/protobuf），避免下游模块因版本不一致导致protoc-gen-go生成失败 - 如果用
gin或echo做HTTP路由，路由绑定代码必须在cmd/或internal/handler里，而非api/模块内
Protobuf定义怎么写才不踩坑？重点看字段命名和option
Protobuf不是单纯描述结构，它直接影响Go生成代码的可读性和兼容性。字段名用snake_case，但Go结构体字段会自动转成PascalCase；真正要控制的是json_name和go_tag。
典型问题：前端传user_id，后端收不到——因为没加json_name，生成的结构体字段是UserId，默认JSON tag却是json:"user_id"，但gRPC gateway默认不启用该tag解析。
立即学习“go语言免费学习笔记（深入）”；
- 所有
message字段必须加json_name，例如string user_id = 1 [ (json_name) = "user_id" ]; - 需要支持gRPC-Gateway时，在
.proto顶部加option go_package = "github.com/yourorg/project/api/v1;v1";，路径必须和实际模块路径一致 - 枚举类型务必定义
0值并命名为XXX_UNSPECIFIED，否则反序列化失败时不会报错，而是静默设为0
OpenAPI和Protobuf怎么保持同步？别靠人工对齐
Protobuf生成gRPC服务，OpenAPI描述HTTP接口，两者语义必须严格一致。手动改一个、漏改另一个，上线后就会出现字段缺失或类型错配——尤其是嵌套对象、重复字段、时间格式这些地方。
推荐用protoc-gen-openapi从.proto自动生成openapi.yaml，而不是反过来。这样能保证HTTP路径、参数位置（query/path/body）、响应结构全部源自同一份定义。
- 运行命令：
protoc -I . --openapi_out=. --openapi_opt=mode=grpc+http api/v1/service.proto - 生成的
openapi.yaml里components.schemas会包含所有message，但需检查format: date-time是否被正确注入（Protobuf的google.protobuf.Timestamp需额外加(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = { ... }） - CI里加校验步骤：用
swagger-cli validate验证YAML有效性，并diff上一版，防止无意识修改
模块版本怎么打？/v1不是路径而是语义版本
Go模块的/v1后缀不是目录名，而是模块路径的一部分，代表语义化版本。一旦发布v1.0.0，后续所有兼容变更都必须维持该路径不变，否则导入路径失效，下游编译直接报错。
容易忽略的点：升级API时，如果只是加字段、改注释，属于兼容变更，应发v1.1.0；但如果删字段、改类型，就必须升v2，新建模块路径github.com/yourorg/project/api/v2，老路径继续维护。
- 模块路径写成
github.com/yourorg/project/api/v1，不是github.com/yourorg/project/api再靠go.mod里module github.com/yourorg/project/api/v1补救 - 发布前用
go list -m all | grep api确认所有依赖都指向同一版本，避免本地replace没清理干净导致测试通过、线上失败 - HTTP API的
Accept头或gRPC的Service-Name头不能替代版本控制——它们只影响运行时行为，不解决编译期契约断裂
最麻烦的从来不是定义本身，而是跨团队协作时对“兼容”的理解偏差。比如有人觉得“加个可选字段不算breaking”，但前端SDK没更新，就可能因空指针崩溃。所以版本边界、字段可选性、生成工具链统一，比语法漂亮重要得多。
