2. Go 项目结构基础：标准布局与模块化设计

在构建业务模块与领域边界之前，必须先建立一套稳定、可扩展的项目骨架。Go 社区经过多年实践，形成了以 cmd/internal/pkg 为核心的标准项目布局，配合模块化设计原则，能够有效支撑 DDD 战术设计落地。本章将拆解这套骨架的职责边界与设计规则。

2.1 标准 Go 项目布局总览

标准布局并非官方强制规范，而是社区共识的最佳实践。它通过目录命名与层级关系，清晰表达了“入口-内部实现-可复用库”的三层结构。下图展示了最常用的布局形态：

2.2 三大核心目录职责对比

2.3 cmd 目录：薄入口与依赖组装

cmd 目录下的每个子目录对应一个独立的二进制程序。每个 cmd 子目录只包含一个 main.go 文件，职责仅限于：

• 读取配置（环境变量、配置文件）
• 初始化基础设施连接（数据库、消息队列、缓存）
• 组装依赖并启动应用服务
• 注册信号处理实现优雅关闭

// cmd/api/main.go
package main

import (
    "context"
    "log"
    "net/http"
    "os"
    "os/signal"
    "syscall"
    "time"

    "your-project/internal/handler"
    "your-project/internal/repository"
    "your-project/internal/service"
    "your-project/pkg/logger"
    "your-project/pkg/middleware"
)

func main() {
    // 1. 加载配置
    cfg := loadConfig()

    // 2. 初始化基础设施
    db := initDatabase(cfg.DSN)
    log := logger.New(cfg.LogLevel)

    // 3. 组装依赖
    userRepo := repository.NewUserRepo(db)
    userSvc := service.NewUserService(userRepo, log)
    userHandler := handler.NewUserHandler(userSvc)

    // 4. 注册路由
    mux := http.NewServeMux()
    mux.HandleFunc("POST /users", userHandler.CreateUser)
    mux.HandleFunc("GET /users/{id}", userHandler.GetUser)

    // 5. 启动 HTTP 服务器
    srv := &http.Server{
        Addr:    ":" + cfg.Port,
        Handler: middleware.Chain(mux, middleware.Recovery(log), middleware.RequestID),
    }

    // 6. 优雅关闭
    go func() {
        sigCh := make(chan os.Signal, 1)
        signal.Notify(sigCh, syscall.SIGINT, syscall.SIGTERM)
        <-sigCh
        ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
        defer cancel()
        srv.Shutdown(ctx)
    }()

    log.Info("server starting", "port", cfg.Port)
    if err := srv.ListenAndServe(); err != http.ErrServerClosed {
        log.Fatal("server error", "error", err)
    }
}

2.4 internal 目录：领域核心的保护区

internal 目录是 Go 语言提供的编译级隔离机制。任何外部项目都无法导入 internal 包及其子包，这为领域模型提供了天然的封装边界。在 DDD 实践中，internal 通常按业务领域或架构层次组织：

2.5 pkg 目录：可复用公共库

pkg 目录存放与具体业务无关的通用组件。这些组件可以被当前项目和其他项目直接导入。典型内容包括：

• 日志库：封装统一的日志接口，支持结构化输出
• 验证器：通用的请求参数校验工具
• 错误处理：自定义错误类型与错误码规范
• HTTP 中间件：跨域、限流、鉴权、请求追踪
• 数据库工具：连接池管理、事务辅助函数

// pkg/errors/errors.go
package errors

import "fmt"

type AppError struct {
    Code    int    `json:"code"`
    Message string `json:"message"`
    Err     error  `json:"-"`
}

func (e *AppError) Error() string {
    if e.Err != nil {
        return fmt.Sprintf("code=%d, message=%s, err=%v", e.Code, e.Message, e.Err)
    }
    return fmt.Sprintf("code=%d, message=%s", e.Code, e.Message)
}

func New(code int, message string) *AppError {
    return &AppError{Code: code, Message: message}
}

func Wrap(code int, message string, err error) *AppError {
    return &AppError{Code: code, Message: message, Err: err}
}

2.6 模块化设计原则

Go 项目的模块化设计遵循以下核心原则，这些原则与 DDD 的限界上下文思想高度一致：

2.7 模块化设计实战：用户注册流程

以下代码展示了模块化原则在用户注册场景中的完整应用：

// internal/user/entity.go — 领域实体
package user

import "your-project/pkg/errors"

type User struct {
    ID       string
    Email    string
    Password string
    Nickname string
}

// internal/user/repository.go — 仓储接口（依赖反转）
type Repository interface {
    Save(ctx context.Context, user *User) error
    FindByEmail(ctx context.Context, email string) (*User, error)
}

// internal/user/service.go — 应用服务
type Service struct {
    repo Repository
    log  Logger
}

func NewService(repo Repository, log Logger) *Service {
    return &Service{repo: repo, log: log}
}

func (s *Service) Register(ctx context.Context, email, password, nickname string) (*User, error) {
    // 1. 检查邮箱是否已注册
    existing, _ := s.repo.FindByEmail(ctx, email)
    if existing != nil {
        return nil, errors.New(409, "email already registered")
    }

    // 2. 创建用户实体
    user := &User{
        ID:       generateID(),
        Email:    email,
        Password: hashPassword(password),
        Nickname: nickname,
    }

    // 3. 持久化
    if err := s.repo.Save(ctx, user); err != nil {
        s.log.Error("failed to save user", "error", err)
        return nil, errors.Wrap(500, "internal server error", err)
    }

    return user, nil
}

// internal/user/repository/mysql.go — 仓储实现（基础设施层）
package repository

import (
    "context"
    "database/sql"
    "your-project/internal/user"
)

type MySQLUserRepo struct {
    db *sql.DB
}

func NewMySQLUserRepo(db *sql.DB) *MySQLUserRepo {
    return &MySQLUserRepo{db: db}
}

func (r *MySQLUserRepo) Save(ctx context.Context, u *user.User) error {
    _, err := r.db.ExecContext(ctx,
        "INSERT INTO users (id, email, password, nickname) VALUES (?, ?, ?, ?)",
        u.ID, u.Email, u.Password, u.Nickname)
    return err
}

func (r *MySQLUserRepo) FindByEmail(ctx context.Context, email string) (*user.User, error) {
    row := r.db.QueryRowContext(ctx, "SELECT id, email, password, nickname FROM users WHERE email = ?", email)
    u := &user.User{}
    err := row.Scan(&u.ID, &u.Email, &u.Password, &u.Nickname)
    if err == sql.ErrNoRows {
        return nil, nil
    }
    return u, err
}

2.8 本章小结

标准 Go 项目布局通过 cmd/internal/pkg 三层结构，为业务模块提供了清晰的物理边界：

• cmd：薄入口，只做依赖组装与启动
• internal：领域核心保护区，按业务或层次组织
• pkg：可复用公共库，无业务语义

模块化设计原则（高内聚、低耦合、依赖反转、显式依赖）与 DDD 的限界上下文思想一脉相承，是后续章节中领域建模与边界设计的基石。下一章将深入探讨如何利用 Go 的接口机制实现领域层的依赖反转与仓储模式。