Go 模块与包管理：Go Module 基础、go.mod 与 go.sum、包命名规范、内部包（internal）的访问控制

在 Go 语言中，模块（Module）是源代码版本管理与依赖治理的基本单元。从 Go 1.11 引入、1.13 成为默认以来，Go Module 已经取代了旧的 GOPATH 模式，成为官方推荐的依赖管理方案。本章将围绕模块的声明文件、依赖锁定、包命名规则以及访问控制边界展开，帮助你在领域驱动设计的项目中建立清晰的模块边界。

1. Go Module 基础

一个模块由 go.mod 文件定义，通常对应一个 Git 仓库的根目录。模块路径（module path）既是该模块的唯一标识，也是其内部包导入路径的前缀。

1.1 初始化模块

使用 go mod init 命令创建 go.mod 文件：

# 初始化模块，模块路径建议与仓库地址一致
go mod init github.com/your-org/your-project

# 输出示例（go.mod 内容）
module github.com/your-org/your-project

go 1.21

require (
    github.com/google/uuid v1.3.0
    github.com/stretchr/testify v1.8.4
)

1.2 模块路径命名策略

场景	推荐模块路径	说明
公开仓库	github.com/org/repo	与托管平台地址一致，便于 go get 直接拉取
私有仓库	gitlab.internal.com/team/project	配合 GOPRIVATE 环境变量跳过代理
领域驱动设计项目	github.com/org/domain-name	模块名反映业务领域，如 order-service、payment-domain
单体仓库（monorepo）	github.com/org/monorepo	子模块通过目录层级区分，如 github.com/org/monorepo/services/order

2. go.mod 与 go.sum：依赖声明与完整性校验

2.1 go.mod 文件结构

go.mod 采用类 INI 格式，包含以下关键指令：

module github.com/your-org/your-project   // 模块路径

go 1.21                                   // Go 语言版本

require (                                 // 直接依赖
    github.com/google/uuid v1.3.0
    github.com/gorilla/mux v1.8.0
)

require (                                 // 间接依赖（自动管理）
    golang.org/x/text v0.3.7 // indirect
)

exclude (                                 // 排除特定版本
    github.com/google/uuid v1.2.0
)

replace (                                 // 替换依赖来源（本地开发或 fork）
    github.com/google/uuid => ../local-uuid
)

retract (                                 // 撤回已发布的错误版本
    v1.0.0 // 发布时包含未完成的 API
)

指令	用途	DDD 项目中的典型场景
require	声明依赖模块及其版本	引入领域事件库、持久化框架
replace	本地替换依赖路径	在单体仓库中引用相邻限界上下文的本地版本
exclude	禁止使用特定版本	跳过已知有 bug 的依赖版本
retract	标记已发布版本为撤回	领域模块发布后发现 API 设计错误

2.2 go.sum 文件：依赖完整性校验

go.sum 是一个自动维护的校验和清单，记录每个依赖模块版本的哈希值。它确保后续构建时下载的代码与首次使用时完全一致，防止中间人攻击或依赖篡改。

# go.sum 条目格式：模块路径 版本 h1:哈希值
github.com/google/uuid v1.3.0 h1:t6JiXgmwXMjEs8VusXIJk2BXHsn+wx8BZdTaoZ5fu7I=
github.com/google/uuid v1.3.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=

3. 包命名规范

Go 语言没有强制性的包命名层级，但社区和官方文档形成了一套约定。在 DDD 项目中，包名应直接反映领域概念。

3.1 核心命名规则

• 全小写：包名必须使用小写字母，多单词时不要使用下划线或驼峰，如 order、payment、userprofile。
• 简短且自描述：包名通常为 1~3 个单词，如 entity、valueobject、repository。
• 避免通用名称：不要使用 util、common、base 等无业务含义的包名。
• 目录名与包名一致：包所在的目录名必须与包声明名相同。

3.2 DDD 项目中的包命名示例

DDD 概念	推荐包名	说明
领域实体	entity	包含 Order、Customer 等核心实体
值对象	valueobject	包含 Money、Address、Email
领域服务	service	包含 OrderService、PaymentService
仓储接口	repository	定义 OrderRepository 接口
领域事件	event	包含 OrderCreated、PaymentReceived
应用服务	application	编排用例流程，如 CreateOrderUseCase
基础设施实现	infrastructure	数据库实现、消息队列适配器

3.3 包导入路径与模块路径的关系

// 模块路径：github.com/your-org/order-service
// 目录结构：
// order-service/
//   go.mod
//   internal/
//     entity/
//       order.go          // package entity
//     repository/
//       order_repo.go     // package repository
//   cmd/
//     server/
//       main.go

// 导入方式：
import "github.com/your-org/order-service/internal/entity"
import "github.com/your-org/order-service/internal/repository"

4. 内部包（internal）的访问控制

Go 的 internal 包机制提供了一种编译时强制访问控制：任何以 internal 命名的目录，其下的包只能被该目录的父级模块及其子模块导入。这是构建模块边界、隐藏内部实现细节的关键工具。

4.1 internal 的访问规则

规则可以概括为：导入路径中包含 internal 的包，只能被 internal 目录的父级模块树中的代码导入。

// 目录结构示例：
// project/
//   go.mod          // module github.com/example/project
//   internal/
//     repository/
//       user_repo.go    // package repository
//   cmd/
//     server/
//       main.go         // 可以导入 internal/repository
//   pkg/
//     api/
//       handler.go      // 可以导入 internal/repository
//
// 外部模块（如 github.com/other/project）无法导入：
//   github.com/example/project/internal/repository
//   // 编译错误：use of internal package not allowed

4.2 多层 internal 嵌套

internal 可以嵌套在任意层级，每一层都会增加一层访问限制：

// 模块路径：github.com/example/monorepo
// 目录结构：
// monorepo/
//   go.mod
//   services/
//     order/
//       internal/
//         domain/          // 只能被 services/order 及其子目录导入
//       cmd/
//         main.go          // 可以导入 services/order/internal/domain
//   pkg/
//     shared/
//       internal/
//         util/            // 只能被 pkg/shared 及其子目录导入

4.3 DDD 项目中的 internal 使用策略

层级	推荐使用 internal	不推荐使用 internal
领域层	实体、值对象、领域服务	仓储接口（需要被应用层引用）
应用层	用例编排、DTO、应用服务实现	应用服务接口（如果被其他模块依赖）
基础设施层	数据库实现、消息队列适配器	基础设施接口定义（应放在领域层）
接口层	HTTP 处理器、中间件	API 契约定义（如果被外部客户端使用）

5. 模块边界与 internal 访问控制示意图

下图展示了一个典型的 DDD 项目中，模块边界与 internal 访问控制的关系：

6. 依赖管理与版本选择

Go Module 使用最小版本选择（Minimal Version Selection, MVS）算法来决定依赖版本。MVS 的核心原则是：使用所有依赖声明的最大兼容版本。

6.1 常用命令速查

命令	用途	DDD 项目中的典型用法
go mod init	初始化新模块	为每个限界上下文创建独立模块
go mod tidy	清理未使用的依赖，添加缺失的依赖	重构领域模型后执行，保持依赖清单干净
go mod vendor	将依赖复制到 vendor 目录	CI/CD 环境需要离线构建时使用
go mod graph	打印模块依赖图	分析跨限界上下文的依赖关系
go mod verify	验证本地依赖与 go.sum 匹配	安全审计时确保依赖未被篡改
go list -m all	列出所有依赖模块及其版本	查看当前模块的完整依赖树

6.2 依赖版本管理策略

• 语义化版本（SemVer）：Go Module 要求依赖版本遵循 vMAJOR.MINOR.PATCH 格式。主版本号变更表示不兼容的 API 修改。
• 主版本升级：当依赖的主版本号变化时，Go 会在模块路径后添加 /v2、/v3 等后缀，允许同一模块的不同主版本共存。
• 间接依赖管理：使用 go mod tidy 自动处理间接依赖，避免手动维护 // indirect 注释。

7. 模块边界设计原则

结合 DDD 的限界上下文概念，Go Module 的边界设计应遵循以下原则：

1. 一个限界上下文 = 一个 Go Module：每个限界上下文拥有独立的 go.mod，独立的版本演进周期。
2. 内部实现全部放入 internal：领域实体、值对象、领域服务、仓储实现等细节对外部不可见。
3. 公开接口最小化：只暴露必要的接口（如仓储接口、事件定义、API 契约），其余全部隐藏。
4. 依赖方向从应用层指向领域层：基础设施层依赖领域层接口，领域层不依赖任何外部框架。
5. 避免循环依赖：模块 A 不能依赖模块 B，同时模块 B 又依赖模块 A。通过引入共享内核（Shared Kernel）或事件驱动机制解耦。