Go模块是微服务代码组织的强制基础，每个服务须为独立模块且路径体现业务边界；共用逻辑应拆为版本化独立模块，禁用replace和go.work于构建流程。
Go模块（go.mod）是微服务代码组织的强制基础
没有 go.mod，就谈不上服务间依赖管理、版本隔离或可复现构建。微服务中每个独立部署单元（如 auth-service、order-service）必须是一个 Go 模块，且模块路径（module 声明）应体现组织域和业务边界，例如 github.com/yourorg/auth-service，而非泛泛的 auth 或 service。
常见错误是把多个服务塞进同一个模块，或用本地相对路径（replace ./common => ../common）绕过版本控制——这会导致 CI 构建失败、无法发布私有包、依赖图混乱。
- 模块名必须是可解析的 URL 形式，即使不实际托管在该地址，也需保持唯一性和语义清晰
- 跨服务复用的逻辑（如通用错误码、HTTP 中间件）应拆为独立模块（如
github.com/yourorg/go-common），通过go get引入，而非拷贝或 symlink -
go mod tidy要在每个服务目录下单独执行，避免因根目录误操作污染子服务依赖
包（package）划分应围绕“部署单元”而非“功能类型”
别按 controller、service、repository 分包——这种分层在单体里常见，但在微服务中会制造虚假耦合。Go 的包本质是编译单元，一个服务内合理的包结构应反映运行时职责边界：
- 主入口（
cmd/auth-service）只含main.go，负责初始化配置、启动 HTTP/gRPC 服务器 - 领域逻辑包（如
internal/auth）封装完整业务能力，对外仅暴露接口（Authenticator）和 DTO（SignInReq） - 基础设施包（如
internal/storage）隐藏数据库驱动细节，只提供抽象接口；具体实现（storage/pg）放在子包里，由主程序选择注入 -
internal是关键：所有非导出包都应置于internal/xxx下，防止被其他模块意外 import
典型错误是把 pkg/validator 这类通用工具直接暴露在模块顶层——它会被其他服务 import，导致修改时牵一发而动全身。
多服务共用代码必须通过模块版本化，而非 Git Submodule 或 vendor
当 auth-service 和 user-service 都需要 JWT 解析逻辑时，正确做法是发布一个带语义化版本的模块（如 v1.2.0），并在各自 go.mod 中声明：
require github.com/yourorg/go-jwt v1.2.0
Git Submodule 会让构建依赖本地路径，vendor 目录在 Go 1.16+ 已被弃用且无法解决版本冲突。更隐蔽的问题是：若两个服务分别依赖 go-jwt v1.1.0 和 v1.2.0，而你本地改了 go-jwt 却忘了 git push，CI 就会拉取旧版，行为不一致。
- 共用模块必须有 CI 流水线，每次 PR 合并后自动打 tag（如
v1.2.1）并推送至私有 proxy（如 Athens） - 服务模块的
go.mod中禁止使用replace指向本地路径，仅限临时调试；上线前必须删掉 - 共用模块的 API 变更需严格遵循 Go 的兼容性规则：只增不删、字段加 tag 保留旧名、接口扩展用新方法名
go.work 仅用于本地开发联调，不可进入 CI 或容器镜像
当需要同时改 auth-service 和 go-common 时，go.work 确实方便：
go work use ./auth-service ./go-common，但它只是开发期的符号链接机制，对构建无实质影响。CI 构建、Docker 构建、生产部署必须基于每个服务独立的
go.mod 和远程模块仓库。
常见陷阱是把 go.work 提交到 Git，并在 Dockerfile 中执行 go work use——这会导致镜像构建失败，因为 go.work 无法跨环境解析本地路径，且 Go 官方明确不支持在构建流程中使用它。
真正需要的是：本地开发用 go.work 快速验证，CI 中每个服务走标准 go build -mod=readonly，确保所用模块版本与 go.sum 严格一致。
