📚 课程目录第2章 Go项目结构

2. Go项目结构：标准Go项目布局、模块化设计、proto文件目录规划、内部包与外部包隔离

在构建生产级 gRPC 服务时，项目结构直接决定了代码的可维护性、团队协作效率以及安全策略的落地成本。本章围绕 标准 Go 项目布局、模块化设计、proto 文件目录规划 和 内部包与外部包隔离 四个核心维度展开，为后续的权限验证与压测闭环奠定坚实的工程基础。

2.1 标准Go项目布局

Go 社区推荐的项目布局（golang-standards/project-layout）已成为业界事实标准。对于 gRPC 服务，我们采用以下核心目录结构：

grpc-security-demo/
├── api/                    # 对外暴露的 API 定义（proto 编译产物）
│   └── proto/
│       ├── v1/
│       │   ├── auth.pb.go
│       │   └── auth_grpc.pb.go
│       └── buf.yaml
├── cmd/                    # 可执行入口
│   └── server/
│       └── main.go
├── internal/               # 私有应用代码（禁止外部导入）
│   ├── config/
│   ├── middleware/
│   ├── service/
│   └── repository/
├── pkg/                    # 可被外部项目引用的公共库
│   ├── auth/
│   └── interceptor/
├── proto/                  # 原始 .proto 源文件
│   ├── v1/
│   │   └── auth.proto
│   └── buf.gen.yaml
├── configs/                # 配置文件模板
├── scripts/                # 构建/部署脚本
├── test/                   # 外部集成测试
├── go.mod
└── go.sum

关键原则：internal/ 目录是 Go 编译器强制的包隔离边界，外部项目无法导入其中的任何代码。这是实现安全权限验证模块“内部不可见”的第一道防线。

2.2 模块化设计

模块化设计的核心是 单一职责 与 依赖倒置。我们将 gRPC 服务拆解为以下独立模块：

模块	目录位置	职责	外部依赖
Config	`internal/config`	加载环境变量、配置文件，提供类型安全的配置结构	viper、os
Middleware	`internal/middleware`	gRPC 拦截器链：认证、鉴权、审计日志、限流	google.golang.org/grpc
Service	`internal/service`	业务逻辑实现，调用 Repository 层	internal/repository
Repository	`internal/repository`	数据持久化抽象，支持 MySQL/Redis/内存切换	database/sql、gorm
Auth	`pkg/auth`	JWT/RBAC 令牌生成与验证（可被外部复用）	golang-jwt
Interceptor	`pkg/interceptor`	通用 gRPC 拦截器（日志、恢复、元数据提取）	google.golang.org/grpc

  模块依赖规则： cmd → internal/service → internal/repository；internal/middleware 可调用 pkg/auth 和 pkg/interceptor；internal 之间禁止循环依赖。

2.3 proto文件目录规划

proto 文件是 gRPC 服务的契约核心。我们采用 源文件与编译产物分离 的策略，并引入 Buf 作为 lint/breaking change 检测工具：

proto/                          # 原始 .proto 源文件（版本控制）
├── v1/                         # API 版本号作为一级目录
│   ├── auth.proto              # 认证服务定义
│   ├── user.proto              # 用户服务定义
│   └── common/
│       └── types.proto         # 共享消息类型
├── buf.yaml                    # Buf 模块配置
├── buf.gen.yaml                # 代码生成配置
└── buf.lock                    # 依赖锁定文件

api/proto/                      # 编译后的 Go 代码（自动生成，不手动编辑）
├── v1/
│   ├── auth.pb.go
│   ├── auth_grpc.pb.go
│   ├── user.pb.go
│   └── user_grpc.pb.go
└── buf.yaml                    # 对外发布的 Buf 模块

重要规则：proto 源文件目录 proto/ 与编译产物目录 api/proto/ 必须严格分离。禁止在 api/proto/ 下手动修改任何文件；所有变更必须从 proto/ 源文件触发重新生成。

版本管理策略：

v1/：当前稳定版本，支持向后兼容
v2/（未来）：当 breaking change 不可避免时，创建新版本目录，旧版本继续维护
common/：存放跨版本共享的 message 类型（如 Timestamp、Pagination）

2.4 内部包与外部包隔离

Go 的 internal 包机制是项目安全的第一道物理屏障。结合 gRPC 服务的安全需求，我们制定以下隔离策略：

包路径	可见性	包含内容	安全敏感度
`internal/config`	仅本项目	数据库密码、JWT 密钥、TLS 证书路径	极高
`internal/middleware`	仅本项目	认证拦截器、权限校验逻辑、审计日志	高
`internal/service`	仅本项目	核心业务逻辑、数据校验	中
`internal/repository`	仅本项目	数据库操作、缓存访问	中
`pkg/auth`	公开	JWT 生成/验证、RBAC 角色定义	高（需谨慎设计接口）
`pkg/interceptor`	公开	通用日志、恢复、元数据拦截器	低

  隔离原则：
  所有敏感配置和认证逻辑必须放在 internal/ 下，外部项目无法直接导入
pkg/ 下的公共库只暴露接口（interface），不暴露实现细节
禁止 internal/ 中的包直接依赖 pkg/ 中的具体实现，应通过接口依赖
单元测试文件（*_test.go）与被测试包放在同一目录，遵守相同的可见性规则

通过以上结构设计，我们实现了：

编译期安全：internal 包强制隔离，防止外部恶意导入
运行时安全：敏感配置不暴露在公共 API 中
可测试性：模块间通过接口解耦，支持 mock 测试
可演进性：proto 版本目录支持平滑升级，不影响现有客户端