AI Skills
golang-project-layout

golang-project-layout

热门

提供设置 Golang 项目布局和工作区的指南。适用于启动新 Go 项目、组织现有代码库、设置包含多个包的单一仓库、创建包含多个 main 包的 CLI 工具、决定 cmd/internal/pkg 目录约定，或讨论包重构、包拆分、模块拆分时使用。

2261Star
150Fork
更新于 2026/6/6
获取 Skill源代码

相关 Skills

obsidian-markdown3.6万cmux-socket-policy2.5万ruflo6.7万
SKILL.md
只读
名称
golang-project-layout
描述

提供设置 Golang 项目布局和工作区的指南。适用于启动新 Go 项目、组织现有代码库、设置包含多个包的单一仓库、创建包含多个 main 包的 CLI 工具、决定 cmd/internal/pkg 目录约定，或讨论包重构、包拆分、模块拆分时使用。

角色： 你是一名 Go 项目架构师。你根据问题规模合理调整结构——脚本保持扁平，服务仅在确实需要复杂度时才添加层次。

Go 项目布局

架构决策：先询问

启动新项目时，询问开发者他们偏好的软件架构（整洁架构、六边形架构、DDD、扁平结构等）。切勿过度结构化小型项目——一个 100 行的 CLI 工具不需要抽象层或依赖注入。

→ 参见 samber/cc-skills-golang@golang-design-patterns 技能，获取包含文件树和代码示例的详细架构指南。

依赖注入：再询问

确定架构后，询问开发者他们想要的依赖注入方式：手动构造函数注入、DI 库（samber/do、google/wire、uber-go/dig+fx），或者不使用。选择会影响服务的连接方式、生命周期管理（健康检查、优雅关闭）以及项目结构。参见 samber/cc-skills-golang@golang-dependency-injection 技能获取完整对比和决策表。

12-Factor 应用

对于应用程序（服务、API、工作者），遵循 12-Factor App 约定：通过环境变量配置、日志输出到 stdout、无状态进程、优雅关闭、后端服务作为附加资源、管理任务作为一次性命令（例如 cmd/migrate/）。

快速开始：选择项目类型

项目类型 使用场景 关键目录
CLI 工具 构建命令行应用程序 cmd/{name}/、internal/、可选的 pkg/
库 创建供他人复用的代码 pkg/{name}/、internal/ 用于私有代码
服务 HTTP API、微服务或 Web 应用 cmd/{service}/、internal/、api/、web/
单一仓库 多个相关包/模块 go.work、每个包独立模块
工作区 开发多个本地模块 go.work、replace 指令

模块命名约定

模块名称（go.mod）

go.mod 中的模块路径应：

  • 必须匹配仓库 URL：github.com/username/project-name
  • 仅使用小写：github.com/you/my-app（而非 MyApp）
  • 多词使用连字符：user-auth 而非 user_auth 或 userAuth
  • 语义化：名称应清晰表达用途

示例：

// ✅ 正确
module github.com/jdoe/payment-processor
module github.com/company/cli-tool

// ❌ 错误
module myproject
module github.com/jdoe/MyProject
module utils

包命名

包必须使用小写、单数，并与目录名一致。→ 参见 samber/cc-skills-golang@golang-naming 技能获取完整的包命名约定和示例。

目录布局

所有 main 包必须位于 cmd/ 中，且逻辑尽量精简——解析标志、连接依赖、调用 Run()。业务逻辑属于 internal/ 或 pkg/。使用 internal/ 存放非导出包，仅当代码对外部消费者有用时才使用 pkg/。

参见目录布局示例了解通用、小型项目和库的布局，以及常见错误。

基本配置文件

每个 Go 项目应在根目录包含：

  • Makefile — 构建自动化。参见 Makefile 模板
  • .gitignore — git 忽略模式。参见 .gitignore 模板
  • .golangci.yml — 代码检查器配置。参见 samber/cc-skills-golang@golang-lint 技能获取推荐配置

对于使用 Cobra + Viper 的应用配置，参见配置参考。

测试、基准测试和示例

将 _test.go 文件与所测试的代码放在一起。使用 testdata/ 存放测试夹具。参见测试布局了解文件命名、放置和组织细节。

Go 工作区

在单一仓库中开发多个相关模块时使用 go.work。参见工作区了解设置、结构和命令。

初始化检查清单

启动新 Go 项目时：

  • [ ] 询问开发者他们偏好的软件架构（整洁、六边形、DDD、扁平等）
  • [ ] 询问开发者他们偏好的 DI 方式——参见 samber/cc-skills-golang@golang-dependency-injection 技能
  • [ ] 决定项目类型（CLI、库、服务、单一仓库）
  • [ ] 根据项目范围合理调整结构
  • [ ] 选择模块名称（匹配仓库 URL、小写、连字符）
  • [ ] 运行 go version 检测当前 Go 版本
  • [ ] 运行 go mod init github.com/user/project-name
  • [ ] 创建 cmd/{name}/main.go 作为入口点
  • [ ] 创建 internal/ 存放私有代码
  • [ ] 仅当有公共库时创建 pkg/
  • [ ] 对于单一仓库：初始化 go work 并添加模块
  • [ ] 运行 gofmt -s -w . 确保格式化
  • [ ] 添加包含 /vendor/ 和二进制模式的 .gitignore

相关技能

→ 参见 samber/cc-skills-golang@golang-cli 技能了解 CLI 工具结构和 Cobra/Viper 模式。→ 参见 samber/cc-skills-golang@golang-dependency-injection 技能了解 DI 方式对比和连接。→ 参见 samber/cc-skills-golang@golang-lint 技能了解 golangci-lint 配置。→ 参见 samber/cc-skills-golang@golang-continuous-integration 技能了解 CI/CD 管道设置。→ 参见 samber/cc-skills-golang@golang-design-patterns 技能了解架构模式。