3. 项目目录结构设计：标准Go项目布局、pkg/internal/cmd/config分层、目录命名规范

在微服务与高并发场景下，一个清晰、可扩展的项目目录结构是工程落地的基石。本章将基于 Standard Go Project Layout 的最佳实践，结合限流熔断骨架工程的具体需求，设计一套分层明确、命名规范的项目骨架。好的目录结构不仅能降低团队沟通成本，还能在后续的持续集成、部署和运维中发挥关键作用。

3.1 标准Go项目布局的核心原则

Go官方并未强制规定项目结构，但社区经过多年实践，形成了广泛认可的布局模式。我们的骨架工程遵循以下核心原则：

• 可导出与不可导出分离：通过 internal 目录强制隔离内部实现，避免外部包意外依赖。
• 按职责分层：将应用入口、业务逻辑、基础设施、配置管理清晰分层，降低耦合。
• 领域驱动：在业务层内按领域（domain）或模块组织代码，而非按技术角色（如controllers、models）。
• 避免循环依赖：通过依赖倒置和接口抽象，确保依赖方向从外层指向内层。

3.2 骨架工程目录结构总览

下表展示了限流熔断骨架工程的顶层目录结构及其职责：

3.3 核心分层详解：cmd / internal / pkg / config

这四个目录构成了骨架工程的核心骨架。下面逐一深入分析其设计意图和内部结构。

3.3.1 cmd：应用入口层

cmd/ 目录下每个子目录都是一个独立的 main 包，负责初始化依赖、启动服务、处理信号。它应该非常薄，只做“组装”工作，不包含业务逻辑。

cmd/
├── server/                 # HTTP/gRPC 服务主进程
│   └── main.go
├── migrate/                # 数据库迁移工具
│   └── main.go
└── worker/                 # 后台任务消费者
    └── main.go

3.3.2 internal：私有应用逻辑层

internal/ 是 Go 编译器强制保护的目录，外部包无法导入其子包。这是存放核心业务逻辑、领域模型、数据仓库实现的最佳位置。我们按领域模块进行二级分包：

internal/
├── domain/                 # 领域层：实体、值对象、仓储接口
│   ├── user/
│   │   ├── entity.go
│   │   └── repository.go
│   └── rate_limit/
│       ├── rule.go
│       └── storage.go
├── service/                # 应用服务层：编排领域对象，实现用例
│   ├── user_service.go
│   └── rate_limit_service.go
├── middleware/             # HTTP/gRPC 中间件（限流、熔断、日志）
│   ├── rate_limiter.go
│   └── circuit_breaker.go
├── repository/             # 仓储实现层（MySQL、Redis、内存）
│   ├── mysql/
│   └── redis/
└── handler/                # 传输层：处理请求/响应，调用 service
    ├── http/
    └── grpc/

3.3.3 pkg：可复用的公共库层

pkg/ 存放可以被外部项目直接引用的通用库。这些库应该是与业务无关的、高度内聚的工具或组件。对于限流熔断骨架，我们在此封装核心算法和基础设施抽象。

pkg/
├── ratelimit/              # 限流器实现（令牌桶、漏桶、滑动窗口）
│   ├── token_bucket.go
│   ├── sliding_window.go
│   └── limiter.go          # 统一接口
├── circuitbreaker/         # 熔断器实现（状态机、半开探测）
│   ├── state.go
│   └── breaker.go
├── logger/                 # 日志封装（基于 zap / zerolog）
├── retry/                  # 重试策略
└── errors/                 # 统一错误码与错误处理

3.3.4 config：配置管理层

config/ 目录负责定义配置结构体、加载配置文件（YAML/TOML/JSON）、提供默认值以及配置热更新能力。我们采用 Viper + 结构体标签 的方式管理配置。

config/
├── config.go               # 全局配置结构体定义
├── config.yaml             # 默认配置文件（可选）
├── loader.go               # 配置加载逻辑（文件、环境变量、远程配置中心）
└── watcher.go              # 配置热更新监听器

配置结构体示例：

// config/config.go
package config

type Config struct {
    Server   ServerConfig   `mapstructure:"server"`
    Redis    RedisConfig    `mapstructure:"redis"`
    RateLimit RateLimitConfig `mapstructure:"rate_limit"`
    CircuitBreaker CircuitBreakerConfig `mapstructure:"circuit_breaker"`
}

type RateLimitConfig struct {
    Strategy string `mapstructure:"strategy"` // token_bucket | sliding_window
    Rate     int    `mapstructure:"rate"`
    Burst    int    `mapstructure:"burst"`
}

3.4 目录命名规范

统一的命名规范能提升代码的可读性和可维护性。以下是本骨架工程遵循的命名规则：

• 全部小写：Go 包名必须小写，目录名与包名保持一致。
• 使用下划线：当名称由多个单词组成时，使用下划线分隔（如 rate_limit、circuit_breaker）。
• 避免复数：目录名使用单数形式（如 handler 而非 handlers，service 而非 services）。
• 缩写统一：常见缩写保持全小写（如 http、grpc、mysql、redis）。
• 层级深度控制：建议不超过 4 层，过深的结构会增加认知负担。

3.5 依赖方向与架构约束

下图展示了骨架工程中各层之间的依赖关系，确保依赖方向始终从外层指向内层，避免循环依赖。

3.6 完整目录结构示例

综合以上设计，限流熔断骨架工程的完整目录结构如下：

rate-limit-circuit-breaker-skeleton/
├── cmd/
│   ├── server/
│   │   └── main.go
│   └── migrate/
│       └── main.go
├── internal/
│   ├── domain/
│   │   ├── rate_limit/
│   │   │   ├── rule.go
│   │   │   └── storage.go
│   │   └── user/
│   │       ├── entity.go
│   │       └── repository.go
│   ├── service/
│   │   ├── rate_limit_service.go
│   │   └── user_service.go
│   ├── repository/
│   │   ├── mysql/
│   │   │   ├── rate_limit_repo.go
│   │   │   └── user_repo.go
│   │   └── redis/
│   │       └── rate_limit_cache.go
│   ├── middleware/
│   │   ├── rate_limiter.go
│   │   └── circuit_breaker.go
│   └── handler/
│       ├── http/
│       │   ├── user_handler.go
│       │   └── rate_limit_handler.go
│       └── grpc/
│           └── rate_limit_service_impl.go
├── pkg/
│   ├── ratelimit/
│   │   ├── limiter.go
│   │   ├── token_bucket.go
│   │   └── sliding_window.go
│   ├── circuitbreaker/
│   │   ├── breaker.go
│   │   └── state.go
│   ├── logger/
│   │   └── logger.go
│   └── errors/
│       └── errors.go
├── config/
│   ├── config.go
│   ├── config.yaml
│   ├── loader.go
│   └── watcher.go
├── api/
│   ├── proto/
│   │   └── rate_limit.proto
│   └── openapi/
│       └── spec.yaml
├── scripts/
│   ├── build.sh
│   └── migrate.sh
├── test/
│   ├── integration/
│   └── benchmark/
├── go.mod
├── go.sum
├── Makefile
└── README.md

3.7 常见问题与避坑指南