1. Go 项目结构基础：标准布局的设计原则与最佳实践

在构建可测试、可维护的 gRPC 服务时，项目结构是第一道防线。Go 社区经过多年实践，形成了以 cmd、internal、pkg、api 为核心的目录布局规范。本章从压测闭环的视角，拆解每一层的职责与边界。

1.1 标准布局总览

以下 SVG 展示了标准 Go 项目在压测闭环中的核心目录结构及其数据流向：

1.2 核心目录设计原则

目录	职责	压测闭环中的角色	是否可被外部导入
cmd/	应用入口，main 函数	压测目标进程的启动点	否
internal/	私有业务逻辑与核心领域	压测覆盖的主要代码路径	否（Go 编译器强制）
pkg/	可对外共享的通用库	压测工具依赖的公共组件	是
api/	协议定义（proto、OpenAPI）	压测请求/响应的契约来源	是（生成代码后）

1.3 各目录最佳实践

cmd/ — 薄入口，厚业务

• 每个可执行文件对应 cmd/<binary-name>/main.go，例如 cmd/server/main.go、cmd/client/main.go。
• main 函数只做三件事：解析配置、初始化依赖、启动服务。业务逻辑零容忍。
• 压测时，通过 cmd/server 启动真实进程，避免 mock 污染。

internal/ — 强制隔离，安全重构

• Go 编译器禁止外部包导入 internal 及其子包，这是语言级别的封装保障。
• 按业务域划分子目录：internal/service/、internal/repository/、internal/middleware/。
• 压测时，internal 是性能瓶颈的高发区，应优先编写针对 internal/service 的基准测试。

// internal/service/user_service.go
package service

type UserService struct {
    repo UserRepository
}

func (s *UserService) GetUser(ctx context.Context, id string) (*User, error) {
    // 压测重点关注此方法的 CPU 和内存分配
    return s.repo.FindByID(ctx, id)
}

pkg/ — 可复用，可独立测试

• 存放与业务无关的通用能力：日志、重试、限流、加解密、类型转换。
• 每个包应有独立的 _test.go，且压测时可直接复用，无需启动完整服务。
• 避免在 pkg/ 中引入业务模型，否则会破坏复用性。

pkg 子包	典型功能	压测关注点
pkg/retry	指数退避重试	重试次数、延迟分布
pkg/ratelimit	令牌桶限流	吞吐量与拒绝率
pkg/logger	结构化日志	写入性能与内存分配

api/ — 契约优先，代码生成

• 存放 .proto 文件（gRPC）或 openapi.yaml（RESTful）。
• 目录结构建议：api/proto/v1/、api/proto/v2/，版本化管理。
• 压测时，直接从 api/proto 生成客户端桩代码，保证请求结构与线上一致。

// api/proto/v1/user.proto
syntax = "proto3";
package user.v1;

service UserService {
    rpc GetUser (GetUserRequest) returns (GetUserResponse);
}

message GetUserRequest {
    string user_id = 1;
}
message GetUserResponse {
    string name = 1;
    int32 age = 2;
}

1.4 压测闭环中的目录协作

以下 SVG 展示了从压测脚本到目标代码的完整调用链路：

1.5 常见误区与避坑

1.6 小结