3. Go 模块化工程实践：Go Module 管理、项目目录结构设计、内部包与外部包隔离、依赖注入基础

在 BFF 架构中，模块化是保障代码可维护性、可测试性与团队协作效率的基石。本章聚焦 Go 语言模块化工程的核心实践，涵盖模块管理、目录结构设计、包隔离策略以及依赖注入基础，帮助你在 GoBFF 项目中建立清晰的领域边界。

3.1 Go Module 管理：从单仓库到多模块

Go Module 是 Go 1.11 引入的官方依赖管理方案，通过 go.mod 文件定义模块路径与依赖版本。在 BFF 项目中，合理的模块划分直接影响编译速度与团队解耦。

3.1.1 单模块 vs 多模块策略

3.1.2 go.mod 核心指令

// 初始化模块
go mod init github.com/yourteam/gobff

// 添加依赖
go get github.com/gin-gonic/gin@v1.9.1

// 本地替换（多模块开发关键）
replace github.com/yourteam/gobff/pkg/common => ./pkg/common

// 整理依赖
go mod tidy

3.2 项目目录结构设计：领域驱动分层

基于 DDD 思想，GoBFF 项目采用四层架构：接口层（handler）、应用层（service）、领域层（domain）、基础设施层（infra）。以下为推荐目录结构：

gobff/
├── cmd/                    # 入口
│   └── server/
│       └── main.go
├── internal/               # 内部包（外部不可导入）
│   ├── handler/            # HTTP/gRPC 处理器
│   │   ├── user_handler.go
│   │   └── order_handler.go
│   ├── service/            # 应用服务（编排领域逻辑）
│   │   ├── user_service.go
│   │   └── order_service.go
│   ├── domain/             # 领域层（核心业务逻辑）
│   │   ├── user/
│   │   │   ├── entity.go
│   │   │   ├── repository.go
│   │   │   └── service.go
│   │   └── order/
│   │       ├── entity.go
│   │       ├── repository.go
│   │       └── service.go
│   └── infra/              # 基础设施（DB、缓存、RPC）
│       ├── mysql/
│       ├── redis/
│       └── rpc/
├── pkg/                    # 公共工具包（可被外部引用）
│   ├── config/
│   ├── logger/
│   └── middleware/
├── go.mod
└── go.sum

3.3 内部包与外部包隔离：编译级安全边界

Go 的 internal 包机制是模块化隔离的第一道防线。任何位于 internal 目录下的包，其导入路径只能以该模块的根路径为前缀。

3.3.1 隔离规则示例

// 模块路径：github.com/yourteam/gobff

// ✅ 合法：模块内部引用
import "github.com/yourteam/gobff/internal/domain/user"

// ❌ 非法：外部模块无法导入 internal 包
// import "github.com/otherteam/otherproject/internal/domain/user"

3.3.2 包依赖方向

3.4 依赖注入基础：解耦与可测试性

依赖注入（DI）是模块化工程的核心实践，通过将依赖的创建与使用分离，实现松耦合和单元测试友好。Go 社区常用的 DI 方式包括：构造函数注入、接口注入 和 DI 容器。

3.4.1 构造函数注入（推荐方式）

// domain/user/repository.go
type UserRepository interface {
    FindByID(id int64) (*User, error)
}

// service/user_service.go
type UserService struct {
    repo UserRepository
}

// 构造函数注入：依赖通过参数传入
func NewUserService(repo UserRepository) *UserService {
    return &UserService{repo: repo}
}

func (s *UserService) GetUser(id int64) (*User, error) {
    return s.repo.FindByID(id)
}

3.4.2 手动组装（无框架 DI）

// cmd/server/main.go
func main() {
    // 1. 初始化基础设施
    db := infra.NewMySQLConnection(config.DB)
    userRepo := infra.NewMySQLUserRepository(db)

    // 2. 初始化领域服务
    userDomainSvc := domain.NewUserService(userRepo)

    // 3. 初始化应用服务
    userAppSvc := service.NewUserService(userDomainSvc)

    // 4. 初始化处理器
    userHandler := handler.NewUserHandler(userAppSvc)

    // 5. 启动 HTTP 服务
    r := gin.Default()
    userHandler.RegisterRoutes(r)
    r.Run()
}

3.4.3 DI 容器（可选，适合大型项目）

// 使用 wire 或 dig 等 DI 容器
// 以下为 wire 示例
// wire.go
func InitializeUserHandler() handler.UserHandler {
    wire.Build(
        infra.NewMySQLConnection,
        infra.NewMySQLUserRepository,
        domain.NewUserService,
        service.NewUserService,
        handler.NewUserHandler,
    )
    return handler.UserHandler{}
}

3.5 模块化工程实践清单