跨团队共享模型包必须发布为独立模块，正确做法是在Git仓库根目录初始化带域名的模块（如github.com/yourorg/models），打v1.0.0标签，其他团队通过go get github.com/yourorg/models@v1.0.0安全拉取；需配置GOPRIVATE和GOPROXY支持私有仓库，模型变更须遵循语义化版本与/v2路径规范，并提交更新后的go.sum以确保校验一致。
跨团队共享模型包必须发布为独立模块
直接把模型代码扔进主项目或用 replace 指向本地路径，短期能跑，长期必崩。模型包本质是契约——它被多个团队消费，就必须有明确版本、可寻址路径和稳定语义。没 go.mod 的目录不是模块，go get 无法引用，CI 构建会失败。
正确做法：在 Git 仓库根目录初始化模块，路径需带域名（如 github.com/yourorg/models），打 v1.0.0 标签后，其他团队才能用 go get github.com/yourorg/models@v1.0.0 安全拉取。
- 模块路径不能随意改，否则所有下游
import语句全部失效 - 发布前必须运行
go mod tidy，确保go.sum完整且提交到仓库 - 模型包自身不应依赖业务逻辑代码，只允许引入
encoding/json、time等标准库或通用工具包（如github.com/google/uuid）
主项目如何安全引用并锁定模型版本
不是加个 require 就完事。模型包常被多个子模块间接引用，Go 的最小版本选择（MVS）可能自动升级它，导致字段不兼容、序列化失败等静默错误。
必须在主项目的 go.mod 中显式 require 并锁定版本：
立即学习“go语言免费学习笔记（深入）”；
require github.com/yourorg/models v1.2.3
然后立即执行 go mod tidy。这会强制整个依赖树收敛到 v1.2.3，哪怕某个中间包声明了 github.com/yourorg/models v1.1.0。
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
- 别用
@latest，它绕过语义化约束，模型字段增删改都可能触发 panic - 升级模型包前，先跑
go list -m all | grep models，确认所有引用点都准备就绪 - 如果发现某旧服务仍依赖
v1.0.x，不要强行统一，应保留双版本共存，靠 Go 的 MVS 自动选最小满足版本
私有模型仓库的认证与代理配置
团队间模型包若托管在私有 Git（如内部 Gitea 或 GitLab），go get 默认走公共 proxy，会 404 或 401。
必须配置 GOPRIVATE 和 GOPROXY：
go env -w GOPRIVATE=git.internal.company.com go env -w GOPROXY=https://goproxy.cn,direct
GOPRIVATE 告诉 Go：匹配该前缀的模块跳过 proxy，直连 Git；direct 在 proxy 列表末尾表示对私有域名回退到直连。
- SSH 协议比 HTTPS 更可靠（免输密码/Token），建议模型仓库 URL 统一用
git@git.internal.company.com:org/models.git - CI 环境要预装 SSH key，并确保
~/.ssh/config正确指向私有 Git 主机 - 别在
go.mod里写死replace指向私有地址——它只在你本地生效，别人拉代码就报unknown revision
模型变更如何协同发布与兼容
字段删除、类型变更、JSON tag 修改都是破坏性操作。光靠版本号不够，得靠机制兜底。
推荐三步走：
- 新增字段用指针或
omitempty，避免反序列化失败 - 重大变更前，在模型包发
v2.0.0，路径同步改为github.com/yourorg/models/v2（Go Modules 要求 v2+ 必须带 /v2 后缀） - 主项目升级时，先改
import路径，再逐个替换使用点，go build报错就是最准的兼容性检查
最易被忽略的是：模型包的 go.sum 必须随每次发布更新并提交。不同团队拉同一标签，若 go.sum 不一致，go build 会校验失败——这不是 bug，是 Go 在防止依赖被篡改。
