不能直接用 vendor 目录同步实体定义，因会导致版本不一致、protobuf 解析失败、升级遗漏三类隐患；应发布为独立 Go 模块，显式声明 go.mod、稳定模块路径、字段带完整 tag，并通过 require 锁定版本、服务层封装隔离、新增字段优先用指针类型保障兼容性。
为什么不能直接用 vendor 目录同步实体定义
微服务之间共享 struct 定义，最常见错误是把公共模型代码拷进各服务的 vendor/ 或 internal/ 目录。这看似简单，实则埋下三类隐患：版本不一致导致 JSON 序列化字段名错位、protobuf 生成代码因 tag 差异解析失败、升级时需手动同步多处且极易遗漏。Go 的模块机制本意就是解决这类复用问题，但必须按模块语义正确发布和引用。
如何发布可被多个微服务 import 的实体模块
实体模块本质是一个最小可行 Go 模块，不需要 main 函数，也不依赖具体框架。关键在于：模块路径要稳定、go.mod 要显式声明、导出类型要带完整 tag。
- 模块根目录执行
go mod init github.com/yourorg/entities，路径必须全局唯一且长期可用（别用localhost或临时域名） - 所有
struct字段必须显式标注json、protobuf、db等 tag，例如CreatedAt time.Time `json:"created_at" db:"created_at"` - 避免在实体中嵌入非导出字段或方法——它只负责数据契约，不承担业务逻辑
- 打 tag 发布：如
v1.2.0，后续任何字段增删都需升版本（哪怕只是加个json:",omitempty"）
微服务中如何安全 import 并约束使用范围
直接 import "github.com/yourorg/entities" 是可行的，但容易引发隐式耦合。更稳妥的做法是：
- 在每个微服务的
go.mod中用require显式锁定版本，例如github.com/yourorg/entities v1.2.0 - 禁止在 handler 层直接返回
entities.User；应在 service 层做一次薄封装，比如转成api.UserResponse，隔离外部契约变更影响 - 若用 gRPC，实体模块可同时提供
.proto文件和生成的 Go 代码，但注意：生成代码应由 CI 自动更新并提交，不可手动生成后混入实体模块源码 - 本地开发调试时，可用
replace github.com/yourorg/entities => ../entities指向本地路径，但上线前必须删掉该行
遇到 “invalid indirect” 或字段零值问题怎么办
这是实体模块使用中最典型的运行时陷阱：当微服务 A 使用 v1.1.0，B 使用 v1.2.0，而新版本新增了非指针字段（如 Status string），旧服务反序列化时该字段为 ""，可能被误判为“未设置”。根本原因不是 Go 模块本身，而是 JSON/protobuf 的默认行为。
立即学习“go语言免费学习笔记（深入）”；
- 所有新增字段优先定义为指针类型（
*string、*int64），这样零值可明确区分“未传”和“传了空字符串” - JSON tag 统一加
omitempty，但注意：指针类型即使为nil也会被 omitempty 掉，符合预期 - 测试时务必用真实 wire 格式（HTTP body / protobuf binary）验证跨版本兼容性，不能只靠单元测试 mock struct
- CI 流程中加入
go list -m -f '{{.Dir}}' github.com/yourorg/entities检查各服务是否引用同一 commit hash，而非仅看版本号
实体模块不是越通用越好，字段粒度和生命周期必须由领域边界决定。一个订单服务的 Order 和支付服务的 Order 表面相同，实际契约含义可能不同——这时候宁可复制一份，也不要强行复用。
