模型应放在独立的 shared 或 proto 仓库（推荐后者），仅包含接口契约（纯 Go 类型或 .proto 文件），禁用业务逻辑方法，确保向后兼容、无循环依赖、无运行时依赖，并通过版本分支与严格 CI 控制发布。
模型定义该放在哪个仓库？
微服务间共享模型，本质是共享类型定义和序列化契约。把 model 放在某个业务服务的私有仓库里，其他服务用 go get 拉依赖，会立刻陷入“谁改谁负责、改了谁测、版本怎么对齐”的泥潭。正确的做法是：单独建一个 shared 或 proto 仓库（推荐后者），只放接口契约——要么是纯 Go 类型（struct + json tag），要么是 .proto 文件。
- 如果用 Go 模型，必须禁用直接导出业务逻辑方法（比如
User.CalculateScore()），只保留字段和基础校验（Validate()可以有，但不能依赖 DB 或 config） - 如果用 Protobuf，用
protoc-gen-go生成 Go 代码，天然隔离实现，且支持多语言；注意统一使用go_package选项，避免生成路径错乱 - 所有模型变更必须向后兼容：不删字段、不改类型、新增字段加
optional（v3）或设默认值
如何避免循环依赖和构建失败？
常见错误是 A 服务 import B 的 model，B 又 import A 的 config 或 utils，形成隐式循环。Go 编译器不会报循环 import 错误（因为只检查直接 import），但会导致测试失败、CI 构建卡住、go list -deps 输出混乱。
- 公共模型仓库 不能依赖任何业务服务，也不能引入
database/sql、gin.Context、redis.Client这类运行时依赖 - 若需复用校验逻辑，把
Validate()方法写在模型包内，用纯函数式风格（只读字段、不调外部接口） - CI 中加一道检查：
go list -f '{{.ImportPath}}: {{.Deps}}' ./... | grep your-service-name，确保模型包输出里不含业务包路径
Protobuf vs 纯 Go 模型，怎么选？
不是技术优劣问题，而是协作成本问题。团队里如果只有 Go，且服务数量 v1.2.0）够用；一旦涉及前端、Python 调用方、或服务超 8 个，Protobuf 是事实标准。
- Protobuf 强制你思考字段是否可选、是否废弃、是否需要 JSON 映射（
json_name），这些恰恰是跨服务通信最易出错的地方 - Go 模型容易“悄悄”加方法或嵌套 struct，导致下游反序列化失败却不报错（比如
time.Time字段没设json:tag，变成空对象） - 注意：Protobuf 默认不生成
jsontag，要加option go_json_tags = true;或用插件处理，否则 HTTP API 返回字段名是user_name而不是userName
版本管理与发布节奏怎么控？
模型是契约，不是库。一次 git push 就可能让三个服务炸掉。别用 main 分支直推，也别学 npm 那套 ^1.0.0 自动升级。
立即学习“go语言免费学习笔记（深入）”；
- 模型仓库只维护
main（开发中）、v1、v2等长周期分支，每个分支对应一个稳定的 protobuf package path（如example.com/proto/v2） - 每次 breaking change 必须升主版本，并同步更新所有已知消费者的服务 README 和 CI 脚本
- 在模型仓库的
Makefile里固化生成命令：make gen跑protoc，make lint跑buf check，不让任何人绕过规范
真正难的从来不是怎么写模型，而是让所有人遵守“模型即 API”的意识——它不能为某一个服务方便而妥协，也不能靠口头约定来维护。每次想给 User 加个 CreatedAtMs int64 字段前，先问一句：这个字段现在有多少服务在用？它们解析时会不会 panic？
