2. 标准Go项目布局：核心目录职责与规范

在Go社区中，golang-standards/project-layout 已成为事实上的项目布局参考。本章将深入剖析 cmd、internal、pkg、api、configs、scripts 这六个核心目录的职责边界、使用规范及常见误区。理解这些目录的契约，是构建可维护、可扩展Go项目的基石。

2.1 目录全景图：职责与层级

下图展示了标准Go项目布局中核心目录的层级关系与数据流向。每个目录都有明确的边界，共同构成项目的骨架。

2.2 cmd/ 目录：应用程序入口

职责：存放项目的所有可执行文件入口。每个子目录对应一个独立的应用程序（如服务端、客户端、CLI工具）。

子目录	典型内容	说明
cmd/myapp/	main.go	主服务入口，通常只包含 main() 函数和依赖注入
cmd/cli/	main.go	命令行工具入口，解析参数并调用业务逻辑
cmd/worker/	main.go	后台任务/Worker入口

// cmd/myapp/main.go
package main

import (
    "myproject/internal/server"
)

func main() {
    srv := server.New()
    if err := srv.Run(); err != nil {
        panic(err)
    }
}

2.3 internal/ 目录：私有应用代码

职责：存放不希望被外部项目导入的私有代码。Go编译器会强制检查：任何导入路径包含 internal 的包，只能被该 internal 的父级目录及其子目录导入。

典型结构：

internal/
├── server/          # HTTP/gRPC 服务层
│   ├── handler.go
│   └── middleware.go
├── service/         # 业务逻辑层
│   ├── user.go
│   └── order.go
├── repository/      # 数据访问层
│   ├── user_repo.go
│   └── db.go
└── model/           # 内部数据模型
    └── entity.go

层级	职责	依赖方向
internal/server	处理HTTP请求、路由、中间件	依赖 service
internal/service	核心业务逻辑编排	依赖 repository
internal/repository	数据持久化操作	依赖 model
internal/model	内部实体定义	无依赖

2.4 pkg/ 目录：可对外导出的共享库

职责：存放可以被外部项目直接导入的公共库代码。与 internal/ 相反，pkg/ 中的包是项目对外暴露的“公共API”。

pkg/
├── auth/            # 认证鉴权工具
│   └── jwt.go
├── validator/       # 数据校验工具
│   └── validate.go
├── logger/          # 日志封装
│   └── log.go
└── httputil/        # HTTP工具函数
    └── response.go

对比维度	internal/	pkg/
访问范围	仅限项目内部	所有外部项目
稳定性要求	可随时重构	需保持向后兼容
文档要求	内部文档即可	需提供完整API文档
测试策略	单元测试为主	需包含集成测试示例

2.5 api/ 目录：接口契约定义

职责：存放所有与外部系统交互的接口定义文件。包括但不限于：Protocol Buffers（protobuf）、OpenAPI/Swagger 规范、Thrift IDL 等。

推荐结构：

api/
├── proto/           # protobuf 定义
│   ├── v1/
│   │   ├── user.proto
│   │   └── order.proto
│   └── buf.yaml     # Buf 配置（可选）
├── openapi/         # OpenAPI 规范
│   └── v1.yaml
└── graphql/         # GraphQL Schema
    └── schema.graphql

// api/proto/v1/user.proto
syntax = "proto3";
package user.v1;
option go_package = "myproject/internal/pb/user/v1";

message User {
  string id = 1;
  string name = 2;
  string email = 3;
}

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

2.6 configs/ 目录：配置文件模板

职责：存放项目的配置文件模板和默认配置。通常包含不同环境的配置示例。

文件	用途
configs/config.yaml	默认配置文件
configs/config.dev.yaml	开发环境配置示例
configs/config.prod.yaml	生产环境配置示例
configs/docker-compose.yaml	本地开发依赖（可选）

2.7 scripts/ 目录：辅助脚本

职责：存放构建、部署、测试、代码生成等辅助脚本。这些脚本通常由开发者或CI/CD系统调用。

scripts/
├── build.sh         # 构建脚本
├── deploy.sh        # 部署脚本
├── migrate.sh       # 数据库迁移脚本
├── gen_proto.sh     # protobuf 代码生成脚本
└── lint.sh          # 代码检查脚本

脚本类型	典型内容	调用时机
构建脚本	go build -o bin/ ./cmd/...	本地构建、CI
部署脚本	Docker构建、K8s apply	CD流水线
代码生成	protoc、buf generate	开发时、pre-commit
数据库迁移	go run cmd/migrate/	部署前、本地开发

2.8 目录职责对比总结

下表从多个维度对比六个核心目录，帮助你在实际项目中快速决策。

目录	主要语言	访问控制	变更频率	对外暴露	典型文件
cmd/	Go	无	低	否（二进制）	main.go
internal/	Go	Go编译器强制	高	否	handler.go, service.go
pkg/	Go	无	中	是	jwt.go, validate.go
api/	Proto/YAML	无	中	是（契约）	*.proto, *.yaml
configs/	YAML/JSON	无	低	否（模板）	config.yaml
scripts/	Shell	无	低	否	build.sh, deploy.sh