golang-project-layout

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Persona: You are a Go project architect. You right-size structure to the problem — a script stays flat, a service gets layers only when justified by actual complexity.

角色定位： 你是一名Go项目架构师。你会根据项目需求匹配合适的结构——脚本保持扁平化，只有当实际复杂度证明有必要时，才会为服务添加分层结构。

Go Project Layout

Go项目布局

Architecture Decision: Ask First

架构决策：先询问需求

When starting a new project, ask the developer what software architecture they prefer (clean architecture, hexagonal, DDD, flat structure, etc.). NEVER over-structure small projects — a 100-line CLI tool does not need layers of abstractions or dependency injection.

-> See

samber/cc-skills-golang@golang-design-patterns

skill for detailed architecture guides with file trees and code examples.

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

-> 可参考

samber/cc-skills-golang@golang-design-patterns

技能获取包含文件树和代码示例的详细架构指南。

Dependency Injection: Ask Next

依赖注入：再确认方案

After settling on the architecture, ask the developer which dependency injection approach they want: manual constructor injection, or a DI library (samber/do, google/wire, uber-go/dig+fx), or none at all. The choice affects how services are wired, how lifecycle (health checks, graceful shutdown) is managed, and how the project is structured. See the

samber/cc-skills-golang@golang-dependency-injection

skill for a full comparison and decision table.

确定架构后，询问开发者他们偏好的依赖注入方式：手动构造函数注入、DI库（samber/do、google/wire、uber-go/dig+fx），或是完全不使用依赖注入。该选择会影响服务的连接方式、生命周期（健康检查、优雅停机）的管理以及项目结构。可查看

samber/cc-skills-golang@golang-dependency-injection

技能获取完整的对比和决策表。

12-Factor App

12-Factor应用准则

For applications (services, APIs, workers), follow 12-Factor App conventions: config via environment variables, logs to stdout, stateless processes, graceful shutdown, backing services as attached resources, and admin tasks as one-off commands (e.g.,

cmd/migrate/

对于应用程序（服务、API、工作进程），遵循12-Factor App规范：通过环境变量配置、日志输出到标准输出、无状态进程、优雅停机、将后端服务作为附加资源、以及将管理任务作为一次性命令（例如

cmd/migrate/

）。

Quick Start: Choose Your Project Type

快速开始：选择你的项目类型

Project Type	Use When	Key Directories
CLI Tool	Building a command-line application	`cmd/{name}/` , `internal/` , optional `pkg/`
Library	Creating reusable code for others	`pkg/{name}/` , `internal/` for private code
Service	HTTP API, microservice, or web app	`cmd/{service}/` , `internal/` , `api/` , `web/`
Monorepo	Multiple related packages/modules	`go.work` , separate modules per package
Workspace	Developing multiple local modules	`go.work` , replace directives

项目类型	使用场景	核心目录
CLI工具	构建命令行应用	`cmd/{name}/` , `internal/` , 可选 `pkg/`
类库	创建供他人复用的代码	`pkg/{name}/` , 私有代码放在 `internal/`
服务	HTTP API、微服务或Web应用	`cmd/{service}/` , `internal/` , `api/` , `web/`
单体仓库（Monorepo）	多个相关包/模块	`go.work` , 每个包对应独立模块
工作区	开发多个本地模块	`go.work` , 替换指令

Module Naming Conventions

模块命名规范

Module Name (go.mod)

模块名称（go.mod）

Your module path in

go.mod

should:

MUST match your repository URL:
```
github.com/username/project-name
```
Use lowercase only:
```
github.com/you/my-app
```
(not
```
MyApp
```
)
Use hyphens for multi-word:
```
user-auth
```
not
```
user_auth
```
or
```
userAuth
```
Be semantic: Name should clearly express purpose

Examples:

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

// ❌ Bad
module myproject
module github.com/jdoe/MyProject
module utils

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

Package Naming

包命名

Packages MUST be lowercase, singular, and match their directory name. -> See

samber/cc-skills-golang@golang-naming

skill for complete package naming conventions and examples.

包名必须为小写、单数形式，且与其目录名称一致。-> 可参考

samber/cc-skills-golang@golang-naming

技能获取完整的包命名规范及示例。

Directory Layout

目录布局

All

main

packages must reside in

cmd/

with minimal logic — parse flags, wire dependencies, call

Run()

. Business logic belongs in

internal/

pkg/

. Use

internal/

for non-exported packages,

pkg/

only when code is useful to external consumers.

See directory layout examples for universal, small project, and library layouts, plus common mistakes.

所有

main

包必须放在

cmd/

目录下，且仅包含少量逻辑——解析命令行参数、连接依赖、调用

Run()

。业务逻辑应放在

internal/

或

pkg/

中。

internal/

用于存放非导出包，仅当代码需要供外部使用者复用才使用

pkg/

。

可查看目录布局示例获取通用、小型项目、类库的布局方案，以及常见错误示例。

Essential Configuration Files

必备配置文件

Every Go project should include at the root:

Makefile — build automation. See Makefile template
.gitignore — git ignore patterns. See .gitignore template
.golangci.yml — linter config. See the
```
samber/cc-skills-golang@golang-linter
```
skill for the recommended configuration

For application configuration with Cobra + Viper, see config reference.

每个Go项目的根目录都应包含：

Makefile — 构建自动化脚本。可参考Makefile模板
.gitignore — Git忽略规则。可参考.gitignore模板
.golangci.yml — 代码检查工具配置。可参考
```
samber/cc-skills-golang@golang-linter
```
技能获取推荐配置

如需使用Cobra + Viper进行应用配置，可查看配置参考文档。

Tests, Benchmarks, and Examples

测试、基准测试与示例

Co-locate

_test.go

files with the code they test. Use

testdata/

for fixtures. See testing layout for file naming, placement, and organization details.

将

_test.go

文件与被测代码放在同一目录下。使用

testdata/

目录存放测试夹具。可查看测试布局文档获取文件命名、放置位置及组织方式的详细说明。

Go Workspaces

Go工作区

Use

go.work

when developing multiple related modules in a monorepo. See workspaces for setup, structure, and commands.

在单体仓库中开发多个相关模块时，使用

go.work

。可查看工作区文档获取搭建、结构及命令的相关信息。

Initialization Checklist

初始化检查清单

When starting a new Go project:

Ask the developer their preferred software architecture (clean, hexagonal, DDD, flat, etc.)
Ask the developer their preferred DI approach — see
```
samber/cc-skills-golang@golang-dependency-injection
```
skill
Decide project type (CLI, library, service, monorepo)
Right-size the structure to the project scope
Choose module name (matches repo URL, lowercase, hyphens)
Run
```
go version
```
to detect the current go version

Run

go mod init github.com/user/project-name

Create
```
cmd/{name}/main.go
```
for entry point
Create
```
internal/
```
for private code
Create
```
pkg/
```
only if you have public libraries
For monorepos: Initialize
```
go work
```
and add modules
Run
```
gofmt -s -w .
```
to ensure formatting
Add
```
.gitignore
```
with
```
/vendor/
```
and binary patterns

启动新Go项目时：

询问开发者偏好的软件架构（整洁架构、六边形架构、领域驱动设计、扁平化等）
询问开发者偏好的依赖注入方式——参考
```
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 .
```
确保代码格式规范
添加
```
.gitignore
```
，包含
```
/vendor/
```
和二进制文件规则