公共组件库不能放 internal 目录下，因为 internal 包受 Go 编译器强制限制：仅父目录及同级子目录可导入，外部模块引用会报错“use of internal package not allowed”；公共组件应置于 pkg/ 或独立模块路径（如 github.com/yourorg/pkg/shared），并配 go.mod 文件以支持外部 import 和版本管理。
为什么公共组件库不能直接放 internal 目录下
internal 包的可见性规则是编译期强制的：只有其父目录及同级子目录中的代码能 import 它。如果你把公共组件库（比如 github.com/yourorg/shared）放在 internal/shared 下，那其他模块（如 service/user 或 pkg/auth）根本无法引用它——Go 会直接报错 use of internal package not allowed。
真正适合公共组件的位置是 pkg/ 或根目录平级的独立模块路径，例如 github.com/yourorg/pkg/shared，并确保它有自己的 go.mod 文件，声明为独立模块。
- 不要把可复用的逻辑塞进
internal/——那是给“当前模块私有实现”留的 - 如果多个服务都要用同一套错误码、常量或工具函数，就把它抽成一个公开模块，走标准
import+go get流程 - 抽离后，各业务模块通过语义化版本（如
@v0.3.1）引用，而非相对路径
如何让主模块正确引用本地开发中的公共组件库
开发阶段，你还没发布新版本到 Git 远端，但又需要主项目立即使用 pkg/shared 的最新改动。这时不能靠 go get，得用 replace 指令临时映射。
在主模块的 go.mod 中添加：
立即学习“go语言免费学习笔记（深入）”；
replace github.com/yourorg/pkg/shared => ./pkg/shared
注意三点：
初始化并管理阿里云SDK Go 客户端，涵盖 sync.Once 单例、goroutine 安全、endpoint 与 region 配置、VPC 端点及调试。
-
./pkg/shared必须是一个合法模块目录，含自己的go.mod（module 声明必须与 replace 左侧完全一致） - 执行
go mod tidy后，go list -m all应显示该模块后缀带=> ./pkg/shared - CI 构建前必须删掉这行
replace，否则远程构建会失败；建议在 CI 脚本开头加grep -q "replace.*shared" go.mod && exit 1提前拦截
公共组件库升级后，为何其他模块不自动更新依赖
Go Modules 默认不会“主动传播”子依赖变更。即使 pkg/shared 升级了 golang.org/x/text 到 v0.14.0，主模块的 go.mod 里仍锁着旧版本（比如 v0.12.0），除非你显式触发同步。
根本原因是 Go 使用最小版本选择（MVS）算法：它只在必要时才升级间接依赖，而多数情况下旧版本仍满足约束。
- 手动同步：在主模块运行
go get github.com/yourorg/pkg/shared@latest，再跟go mod tidy - 自动化方案：在 CI 中对每个依赖模块跑
go list -u -m all检查可升级项，配合go get -u+go mod tidy自动提交 PR - 别依赖
go mod graph直接看版本——它显示的是当前解析结果，不是“最新可用”
go.sum 不一致导致构建失败怎么快速定位
CI 报错 verifying github.com/yourorg/pkg/shared@v0.2.5: checksum mismatch，通常不是代码被篡改，而是：某人本地没运行 go mod tidy 就提交了新代码，或不同 Go 版本生成了不同伪版本（v0.0.0-20250701...）的校验和。
关键动作是比对两份 go.sum：
- 用
go mod download -json github.com/yourorg/pkg/shared@v0.2.5查看该版本实际下载地址和预期哈希 - 检查
pkg/shared模块自身的go.sum是否已提交，且内容与主模块中记录的一致 - 运行
go mod verify在本地验证所有模块完整性，比等go build失败更早发现问题
最易被忽略的一点：每个模块都必须维护自己的 go.sum，不能只靠主模块生成一份然后复制过去——Go 不认这个。
