4. Go 项目结构设计原则：标准布局、模块化、接口隔离、依赖注入

在构建 gRPC 服务契约压测工具时，项目结构直接决定了代码的可维护性、可测试性以及团队协作效率。本章围绕四个核心设计原则展开：标准布局（Standard Layout）、模块化、接口隔离、依赖注入。这些原则并非孤立存在，而是相互支撑，共同构成一个高内聚、低耦合的 Go 项目骨架。

4.1 标准布局：项目骨架的“公约数”

Go 社区推荐的 Standard Go Project Layout 并非官方强制规范，但已成为多数开源项目的默认选择。对于 gRPC 压测项目，我们采用以下目录结构：

grpc-benchmark/
├── cmd/                    # 可执行入口
│   └── bench/              # 压测主程序
│       └── main.go
├── internal/               # 私有应用逻辑
│   ├── contract/           # 契约解析与校验
│   ├── runner/             # 压测执行引擎
│   ├── reporter/           # 报告生成
│   └── config/             # 配置管理
├── pkg/                    # 可复用的公开库
│   ├── proto/              # 生成的 protobuf 代码
│   └── metrics/            # 指标采集工具
├── api/                    # 对外 API 定义（gRPC/HTTP）
├── configs/                # 配置文件模板
├── scripts/                # 构建与部署脚本
├── test/                   # 集成测试与压测数据
├── go.mod
└── go.sum

4.2 模块化：按职责切分，而非按层切分

模块化的核心是业务职责而非技术分层。在压测项目中，我们按以下维度划分模块：

• 契约模块（contract）：负责加载、解析、校验 gRPC 服务定义（protobuf 描述符或反射服务）。
• 执行模块（runner）：管理并发 goroutine、连接池、请求调度与超时控制。
• 指标模块（metrics）：采集延迟分布、吞吐量、错误率，支持实时聚合。
• 报告模块（reporter）：将原始指标转换为可读的表格、直方图或 JSON 输出。
• 配置模块（config）：统一管理 CLI 参数、配置文件、环境变量。

4.3 接口隔离：面向契约编程，而非面向实现

Go 的接口是隐式满足的，这为接口隔离提供了天然优势。在压测引擎中，我们定义以下核心接口：

// contract.go — 契约解析器接口
type ContractResolver interface {
    Resolve(ctx context.Context, target string) (*ServiceDescriptor, error)
}

// runner.go — 压测执行器接口
type BenchmarkRunner interface {
    Run(ctx context.Context, plan *BenchPlan) (*BenchResult, error)
}

// reporter.go — 报告输出接口
type Reporter interface {
    Report(result *BenchResult) error
}

接口隔离原则（ISP）要求：客户端不应依赖它不需要的方法。上述每个接口只包含一个方法，粒度极细。这样做的好处：

• 易于 mock：单元测试时只需实现一个方法即可注入。
• 易于组合：通过接口组合构建更复杂的行为。
• 易于替换：例如从文件解析契约切换到 gRPC 反射解析，只需提供新的 ContractResolver 实现。

4.4 依赖注入：显式声明，隐式满足

依赖注入（DI）在 Go 中通常通过构造函数显式传参实现，而非依赖框架。以下是一个典型的 DI 示例：

// 在 cmd/bench/main.go 中组装依赖
func main() {
    cfg := config.Load()

    // 注入契约解析器
    var resolver contract.ContractResolver
    if cfg.UseReflection {
        resolver = contract.NewReflectionResolver(cfg.Target)
    } else {
        resolver = contract.NewFileResolver(cfg.ProtoPath)
    }

    // 注入执行器
    runner := runner.NewConcurrentRunner(
        resolver,
        runner.WithConcurrency(cfg.Concurrency),
        runner.WithTimeout(cfg.Timeout),
    )

    // 注入报告器
    reporter := reporter.NewConsoleReporter(os.Stdout)

    // 执行压测
    result, err := runner.Run(context.Background(), cfg.BenchPlan)
    if err != nil {
        log.Fatal(err)
    }
    reporter.Report(result)
}

4.5 原则协同：从结构到行为的闭环

四个原则在压测项目中形成闭环：

1. 标准布局 提供了物理目录的隔离边界（internal/ vs pkg/）。
2. 模块化 在边界内按业务职责组织代码，避免跨职责耦合。
3. 接口隔离 定义了模块之间的通信契约，每个接口只暴露一个能力。
4. 依赖注入 在组合根（main() 或测试函数）将具体实现注入到接口中，实现控制反转。