Go项目模块拆分需人工划定边界并用go mod管理，满足复用、封装、独立CI等条件时才应拆分；创建新module须初始化独立仓库、声明路径、打语义化tag；主项目应视其为第三方依赖，避免replace滥用；错误处理与日志归属权是边界设计关键。
Go 项目模块拆分不是靠 go mod 自动完成的，而是由你明确划定边界、控制依赖流向后，再用 go mod 管理各子模块的版本与引用关系。
什么时候该拆出一个新 module？
当某组代码满足以下任一条件时，就该独立为 module：
- 被多个主项目（如
backend、cli、worker）复用，且更新节奏不一致 - 需要独立发布语义化版本（如
v1.2.0），供外部团队或开源用户导入 - 内部有强封装需求：只暴露少数接口，隐藏实现细节和依赖（比如把数据库驱动、加密逻辑全封在内部）
- CI/CD 要求单独测试、构建、打镜像（例如
pkg/auth拆成github.com/org/auth后可独立跑单元测试 + fuzz）
反例：仅为了“看起来整洁”把 internal/handler 和 internal/service 拆成两个 module —— 这会引入不必要的 replace 和版本同步负担。
如何创建并发布一个可复用的 Go module？
关键动作是：初始化独立仓库、声明模块路径、打 tag。不是在原项目里建个文件夹就完事。
立即学习“go语言免费学习笔记（深入）”；
- 新建 Git 仓库（如
github.com/yourname/go-utils），克隆到本地 - 运行
go mod init github.com/yourname/go-utils—— 模块路径必须和最终导入路径完全一致 - 写好代码，确保
go test ./...通过 - 提交后打语义化 tag：
git tag v0.1.0 && git push origin v0.1.0 - 其他项目即可用
import "github.com/yourname/go-utils/encoding"，go get会自动拉取 tag 版本
注意：不要用 go mod edit -replace 长期绕过真实发布 —— 这会让协作方无法复现构建，也掩盖了 API 兼容性问题。
module github.com/yourname/go-utils
go 1.21
require (
golang.org/x/crypto v0.21.0
)
// 不要在这里写 replace —— 这是临时调试手段，不是模块设计方式
主项目如何安全引用多个内部 module？
主项目（如 github.com/yourname/backend）应视每个内部 module 为第三方依赖，而非本地路径别名。
- 所有内部 module 必须有公开可访问的 Git 地址（私有 GitLab/GitHub Enterprise 也可，只要
go get能 fetch） - 主项目中直接 import 完整路径：
"github.com/yourname/go-utils/encoding"，而不是"./pkg/encoding" - 用
go get github.com/yourname/go-utils@v0.1.0锁定版本，避免main分支漂移导致构建失败 - 若需临时调试未发布的变更，用
go mod edit -replace github.com/yourname/go-utils=../go-utils，但上线前必须删掉并重新go get
常见坑：在 CI 中忘记配置 SSH key 或 GOPRIVATE，导致 go get 因权限失败；或者 module 的 go.mod 里用了本地 replace，导致别人 go mod download 时找不到路径。
module 边界设计最容易被忽略的一点
不是目录结构，也不是 go.mod 文件位置，而是错误处理与日志的归属权。
如果 github.com/yourname/auth module 返回了 errors.New("invalid token")，而主项目又用 fmt.Errorf("auth failed: %w", err) 包裹，那堆栈里就会混入两层无关上下文。更糟的是，若该 module 内部打了日志（比如 log.Printf），主项目就失去了日志统一采集能力。
正确做法：module 只返回带类型、可判断的 error（如 auth.ErrInvalidToken），不打日志、不包裹、不 panic；日志和错误包装全部交给调用方。这比接口定义还难守住，但决定了模块能否真正解耦。
