go项目重构核心是按功能域组织代码、用go modules渐进拆分、主干开发配合语义化版本控制，并坚持小步提交与可运行纪律。
Go 项目重构不是重写，而是让代码更易读、可维护、可扩展。核心在于理清依赖、收敛职责、明确边界——组织方式决定长期迭代成本，模块化支撑团队协作，版本控制保障演进安全。
按功能域组织代码，而非技术分层
避免经典的 controllers/、services/、repositories/ 顶层目录结构。Go 更适合以业务能力（domain）为单位组织，每个子目录代表一个内聚的功能模块。
- 每个模块自包含：接口定义、实现、单元测试、必要配置，不跨模块直接引用内部实现（如
user/internal/） - 公共基础能力（如日志、HTTP 工具、数据库连接池）抽成
internal/pkg/xxx，仅被显式导入，不暴露给外部模块 - 主入口（
cmd/）只负责初始化和启动，不放业务逻辑；例如cmd/api和cmd/worker分开构建不同二进制 - 示例结构：
├── cmd/<br>│ ├── api/<br>│ └── worker/<br>├── internal/<br>│ ├── pkg/<br>│ └── domain/<br>│ ├── user/<br>│ │ ├── user.go // 接口与模型<br>│ │ ├── handler.go // HTTP handler（只依赖 user.Interface）<br>│ │ ├── service.go // 核心业务逻辑<br>│ │ └── repository.go // 数据访问契约（interface）<br>│ └── order/<br>├── api/<br>│ └── v1/ // OpenAPI 定义、DTO、错误码<br>└── go.mod
用 Go Modules 实现渐进式模块拆分
单体项目初期不必急于拆 repo，优先通过 go.mod 内部模块化管理依赖关系和发布节奏。
- 在根目录
go.mod中为高内聚子模块声明伪模块路径，例如：
module example.com/project<br>replace example.com/project/user => ./internal/domain/user<br>replace example.com/project/order => ./internal/domain/order
这样其他模块可 import"example.com/project/user"，且能独立go test和go vet - 当某模块需独立部署或由多团队维护时，再将其迁出为独立 Git 仓库，并升级为真实 module（含语义化版本 tag）
- 所有模块共用统一的
tools.go管理开发依赖（如golangci-lint、swag），避免go install全局污染
版本控制策略：主干开发 + 语义化标签 + 变更日志驱动
放弃长期维护 develop 分支。Go 生态更适配简洁、可追溯的发布流程。
立即学习“go语言免费学习笔记（深入）”；
- 默认使用
main分支：所有 PR 合并前必须通过 CI（含测试、lint、生成文档、镜像构建） - 发布时打轻量 tag（如
v1.2.0），不建 release 分支；补丁修复走 hotfix PR 直合main，立即打v1.2.1 - 每次合并到
main都触发 changelog 自动更新（推荐 git-chglog），基于 conventional commits 提取 feat/fix/docs 等类别 - 私有模块（如
internal/pkg/auth）不对外发布，但其 API 变更仍需记录在项目级 changelog 中，便于评估重构影响面
重构过程中的关键纪律
避免“重构即停步”。每次改动都应保持可运行、可测试、可部署。
- 小步提交：一次 PR 只做一件事（如“将 user repository 抽为 interface”或“把 email validation 移入 user domain”），附带对应测试覆盖
- 禁止删除旧代码前未验证新路径完整接管——可用 feature flag 或双写过渡，尤其涉及数据库迁移或第三方调用
- 所有公开 API（HTTP、gRPC、导出函数）变更必须同步更新文档（Swagger/OpenAPI）、示例代码和客户端 SDK（如有）
- 定期运行
go mod graph | grep -i broken检查循环依赖；用go list -f '{{.Deps}}' ./... | grep internal审计越界引用
