2. Go 模块化基础：Go Module 详解、包设计原则与可见性控制

在构建具备清晰领域边界的 API 系统时，模块化是首要基石。Go 语言通过 Go Module 管理依赖与版本，通过 包（package） 组织代码单元，并通过 内部包（internal） 机制实施严格的可见性控制。本章将深入这三层结构，为后续的领域驱动设计实践奠定工程基础。

2.1 Go Module：从 GOPATH 到现代依赖管理

Go Module 自 Go 1.11 引入，1.16 起成为默认行为。它彻底取代了 GOPATH 模式，使得项目可以独立于全局工作区进行版本化构建。

2.1.1 核心概念与文件结构

一个模块由 go.mod 文件定义，该文件位于项目根目录。它声明了模块路径、Go 版本以及所有外部依赖。

2.1.2 语义化导入与版本兼容性

Go Module 强制遵循语义化版本（SemVer）。当主版本号大于等于 2 时，模块路径必须附加 /v2 后缀，以避免版本冲突。

// go.mod 示例：主版本 v2
module github.com/your-org/order-api/v2

go 1.22

require (
    github.com/gin-gonic/gin v1.9.1
    github.com/your-org/shared-kernel v2.1.0
)

这种设计使得同一个项目可以同时依赖同一个库的不同主版本，这在大型系统演进中至关重要。

2.2 包（Package）设计原则：高内聚与低耦合

包是 Go 中代码组织的基本单元。在 DDD 语境下，一个包通常对应一个限界上下文（Bounded Context）或一个聚合（Aggregate）。

2.2.1 包命名与职责

• 简洁且具描述性：包名应为小写单词，无需下划线或驼峰。例如 order、payment、user。
• 以领域概念命名：避免使用 utils、common、helpers 等泛化名称。每个包应代表一个明确的领域职责。
• 单一职责：一个包只做一件事。如果包名需要“and”连接（如 order_and_payment），说明职责过重，应拆分。

2.2.2 包内部结构最佳实践

2.3 内部包（internal）与可见性控制

Go 的可见性控制分为三个层级：包内私有（小写标识符）、包外公开（大写标识符）、以及 模块内公开（通过 internal 包实现）。

2.3.1 internal 包的机制

任何以 internal 命名的包，其导出的标识符只能被该 internal 包的父级模块树内的代码导入。外部模块无法导入 internal 包中的任何内容，无论标识符是否大写。

// 项目结构示例
my-project/
├── go.mod                  // module github.com/company/my-project
├── cmd/
│   └── api/
│       └── main.go         // 可以导入 internal/order
├── internal/
│   ├── order/
│   │   ├── order.go        // 导出 Order 结构体
│   │   └── repository.go   // 导出 Repository 接口
│   └── payment/
│       └── gateway.go      // 只能被 my-project 内部使用
└── pkg/
    └── public/
        └── helper.go       // 外部模块可以导入

2.3.2 可见性层级对比

2.4 模块化架构与领域边界映射

将 Go 的模块化机制与 DDD 的战术模式结合，可以构建出边界清晰、易于演进的系统。

2.5 实战：构建一个带领域边界的模块

以下示例展示如何将上述原则应用于一个订单管理模块。我们将创建一个包含 internal 包的模块，并演示可见性控制的效果。

2.5.1 项目初始化与结构

# 初始化模块
mkdir order-api && cd order-api
go mod init github.com/company/order-api

# 创建目录结构
mkdir -p cmd/api
mkdir -p internal/order
mkdir -p internal/payment
mkdir -p internal/shared
mkdir -p pkg/api

2.5.2 定义内部领域类型

// internal/order/order.go
package order

import "github.com/company/order-api/internal/shared"

// Order 是聚合根，大写导出但位于 internal 包，仅模块内可见
type Order struct {
    ID        string
    Amount    shared.Money
    Status    string
    items     []lineItem // 小写，包私有
}

// NewOrder 是构造函数，模块内公开
func NewOrder(id string, amount shared.Money) *Order {
    return &Order{
        ID:     id,
        Amount: amount,
        Status: "pending",
    }
}

// AddItem 是方法，模块内公开
func (o *Order) AddItem(name string, price shared.Money) {
    o.items = append(o.items, lineItem{Name: name, Price: price})
}

// internal/shared/money.go
package shared

// Money 是值对象，模块内公开
type Money struct {
    Amount   float64
    Currency string
}

func NewMoney(amount float64, currency string) Money {
    return Money{Amount: amount, Currency: currency}
}

2.5.3 定义全局公开的 API 契约

// pkg/api/order_dto.go
package api

// CreateOrderRequest 是全局公开的 DTO，外部模块可以导入
type CreateOrderRequest struct {
    UserID   string  `json:"user_id"`
    Amount   float64 `json:"amount"`
    Currency string  `json:"currency"`
}

// OrderResponse 是全局公开的响应结构
type OrderResponse struct {
    OrderID string `json:"order_id"`
    Status  string `json:"status"`
}

2.5.4 在 cmd 中组合使用

// cmd/api/main.go
package main

import (
    "github.com/company/order-api/internal/order"
    "github.com/company/order-api/internal/shared"
    "github.com/company/order-api/pkg/api"
)

func main() {
    // 使用内部包（允许，因为同模块）
    money := shared.NewMoney(99.99, "USD")
    o := order.NewOrder("ORD-001", money)
    o.AddItem("Widget", money)

    // 使用全局公开包
    req := api.CreateOrderRequest{
        UserID:   "user-123",
        Amount:   99.99,
        Currency: "USD",
    }
    _ = req
    _ = o
}

2.6 常见陷阱与避坑指南

• 陷阱：internal 包层级过深 — 将 internal 放在模块根目录是最清晰的做法。嵌套多层 internal（如 internal/foo/internal/bar）会导致可见性规则混乱，应避免。
• 陷阱：滥用全局公开包 — 不要将所有类型都放在 pkg/ 下。只有真正需要被外部模块复用的 API 契约和工具才应全局公开。领域逻辑应始终放在 internal 中。
• 陷阱：循环导入 — 当两个领域包需要互相引用时，通过 internal/shared 包提取公共接口或值对象，或者引入依赖倒置（DIP）原则。
• 陷阱：忽略 go.mod 的 module 路径 — internal 的可见性基于文件路径，但导入路径基于 go.mod 中的 module 声明。确保两者一致，否则可能导致意外的可见性泄漏。