Go 项目结构入门：什么时候需要 cmd、internal 和分层目录

项目结构不是越复杂越专业

Go 新手很容易被各种项目模板吓到：cmd、internal、pkg、api、configs、deployments、scripts、services、repositories。有些结构来自大型项目，有些只是团队习惯。如果你刚写一个小服务，一开始就照搬复杂模板，反而会让代码分散、跳转困难。

Go 的项目结构应该随着需求自然长出来。一个命令行工具可以只有 main.go；一个小 Web 服务可以先有 main.go、handler.go、store.go；当可执行入口变多，再引入 cmd；当内部包不想被外部引用，再放进 internal；当业务边界复杂，再拆 handler、service、store。

这篇文章不提供万能模板，而是讲判断依据。你会看到一个小服务如何从简单结构逐步演进，什么时候拆目录，什么时候先别拆。

最小结构就够用

刚开始：

notes/
├── go.mod
├── main.go
├── handler.go
└── store.go

所有文件都属于 package main。这对几百行以内的小服务完全可以接受。main.go 启动服务，handler.go 处理 HTTP，store.go 管理数据。

不要因为看到别人有很多目录，就急着拆包。拆包会带来导出规则、依赖方向和命名成本。如果代码还很少，保持一个包反而更清楚。

当你发现 main 包里出现几类明显职责，并且文件之间关系开始混乱，再考虑拆。

引入 cmd：多个可执行入口

如果项目有多个命令，比如一个 Web 服务和一个迁移工具：

notes/
├── go.mod
├── cmd/
│   ├── notes-server/
│   │   └── main.go
│   └── notes-migrate/
│       └── main.go
└── internal/
    └── app/
        └── app.go

cmd 下面每个目录是一个可执行程序。构建：

go build ./cmd/notes-server
go build ./cmd/notes-migrate

cmd/notes-server/main.go 应该很薄：

package main

import (
	"log"

	"example.com/notes/internal/app"
)

func main() {
	if err := app.RunServer(); err != nil {
		log.Fatal(err)
	}
}

真正逻辑放在内部包里。这样多个入口可以复用配置、数据库和业务代码。

如果只有一个入口，cmd 不是必须。直接根目录 main.go 更简单。

internal 的意义

internal 是 Go 语言工具链支持的特殊目录。放在 internal 下的包，只能被父目录及其子目录引用，外部模块无法 import。

notes/
└── internal/
    ├── handler/
    ├── service/
    └── store/

这适合应用内部代码。你不希望别人 import 你的 handler 或 store，因为它们不是公共库 API，只服务当前应用。

示例：

package service

type Note struct {
	ID    int64
	Title string
}

type Store interface {
	Create(title string) (Note, error)
	List() ([]Note, error)
}

type Service struct {
	store Store
}

func New(store Store) *Service {
	return &Service{store: store}
}

internal/service 可以被 cmd/notes-server 引用，但不能被其他模块引用。这能防止内部结构无意中变成外部依赖。

handler、service、store 怎么分

一个常见小型 Web 服务结构：

internal/
├── handler/
├── service/
└── store/

handler 关心 HTTP：

func (h *Handler) createNote(w http.ResponseWriter, r *http.Request) {
	var req CreateNoteRequest
	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
		writeError(w, http.StatusBadRequest, "invalid json")
		return
	}

	note, err := h.service.Create(r.Context(), req.Title)
	if err != nil {
		writeError(w, http.StatusBadRequest, err.Error())
		return
	}

	writeJSON(w, http.StatusCreated, note)
}

service 关心业务规则：

func (s *Service) Create(ctx context.Context, title string) (Note, error) {
	title = strings.TrimSpace(title)
	if title == "" {
		return Note{}, fmt.Errorf("title is required")
	}
	return s.store.Create(ctx, title)
}

store 关心数据访问：

func (s *MemoryStore) Create(ctx context.Context, title string) (service.Note, error) {
	s.mu.Lock()
	defer s.mu.Unlock()

	note := service.Note{ID: s.nextID, Title: title}
	s.notes[note.ID] = note
	s.nextID++
	return note, nil
}

这只是一个方向，不是教条。小项目里 handler 和 service 合在一起也可以。拆分的标准是：这层是否有独立职责，是否降低了复杂度。

pkg 目录要谨慎使用

很多模板有 pkg 目录，表示可被外部项目引用的公共库代码。但很多应用项目并不需要对外提供库。初学者常把所有代码都塞进 pkg，反而让内部实现看起来像公共 API。

如果你的包只是当前应用使用，放 internal 更合适。如果你真的写了可复用库，比如通用分页、日志格式化、协议客户端，并愿意让其他模块 import，再考虑 pkg 或直接放在根目录下的命名包。

简单规则：不确定是否要对外复用时，先不要放 pkg。

配置、脚本和文档

项目稍大后可以有：

configs/
scripts/
docs/

但这些目录不是 Go 语言要求。配置示例可以放 configs/，运维脚本放 scripts/，设计文档放 docs/。不要让目录名替你做架构决策。

真正影响 Go 编译和引用的是包目录、go.mod、internal 规则和 import 路径。其他目录更多是团队约定。

小结

Go 项目结构应该服务于当前复杂度。一个入口、几百行代码时，根目录几个文件就够了；多个可执行程序时，引入 cmd；应用内部包不想被外部引用时，用 internal；业务复杂后，再按 handler、service、store 拆职责。

不要一开始就套大型模板，也不要把所有代码堆到无法维护。最好的结构是读者能顺着启动入口，一路看到依赖如何组装、请求如何进入、业务规则在哪里、数据如何保存。

Go 的简单不是没有结构，而是结构要显式、自然、必要。每次拆目录前问一句：它是否让代码更容易读、更容易测、更容易改？如果答案不明确，先保持简单。

大型项目的目录演进

当项目从几百行增长到几万行，目录结构需要自然演进。下面是一个渐进式演进的例子。

阶段一：单一入口（小于 1000 行）

project/
├── go.mod
├── main.go
├── user.go
└── order.go

所有逻辑在一个 package main 中。此时引入 internal 或 pkg 只会增加跳转成本。

阶段二：引入内部包（1000 到 5000 行）

project/
├── go.mod
├── cmd/
│   └── server/
│       └── main.go
├── internal/
│   ├── handler/
│   ├── service/
│   └── store/
└── pkg/
    └── validator/

pkg/validator 是一个被多个服务复用的校验包。如果只有当前服务用，应该放 internal/validator。

阶段三：多服务共享代码（5000 行以上）

project/
├── go.mod
├── api/
│   └── proto/           # protobuf 定义
├── cmd/
│   ├── api-server/
│   ├── worker/
│   └── scheduler/
├── internal/
│   ├── domain/          # 业务实体
│   ├── usecase/         # 业务逻辑
│   ├── repository/      # 数据访问抽象
│   └── infra/           # 基础设施实现
├── pkg/
│   ├── logger/
│   ├── errors/
│   └── middleware/
└── configs/
    ├── dev.yaml
    └── prod.yaml

domain 放实体和值对象，usecase 放业务流程，repository 是接口，infra 是具体实现。这种分层来自 DDD，但不需要严格遵循所有概念。关键是依赖方向：domain 不依赖任何其他层。

Go Module 与多仓库选择

一个 Go module 对应一个 go.mod 文件。常见有两种组织方式：

单仓库单模块：一个 Git 仓库一个 go.mod。适合中小型项目，构建简单，依赖清晰。

单仓库多模块（monorepo）：根目录有多个子目录，每个子目录有自己的 go.mod：

company/
├── libs/
│   ├── logger/
│   │   └── go.mod
│   └── errors/
│       └── go.mod
├── services/
│   ├── user/
│   │   └── go.mod
│   └── order/
│       └── go.mod

多模块的好处是各服务可以独立发版、独立依赖升级。坏处是交叉依赖管理复杂，本地开发时需要 replace 指令。入门阶段建议先用单模块，等业务拆分需求明确后再考虑多模块。

// 本地开发时的 replace 示例
go mod edit -replace company.com/libs/logger=../libs/logger

Makefile 和构建脚本

项目稍大后，用 Makefile 统一常见操作：

.PHONY: build test lint run

build:
	go build -o bin/server ./cmd/server

test:
	go test -race -cover ./...

lint:
	golangci-lint run

run:
	go run ./cmd/server

Makefile 不是 Go 专属，但它是团队协作的好约定。新成员加入后，不需要记住各种 go 命令组合，只看 Makefile 就能上手。

常见项目布局误区

1. 过早抽象：100 行代码就拆 10 个包，每个包只有 1 个文件。包是有命名和导入成本的。
2. 循环依赖：handler 依赖 service，service 又通过某些渠道依赖 handler。Go 不允许包级别循环依赖，这是好事，逼你理清依赖方向。
3. 把所有工具代码放 pkg：pkg 应该是稳定、可复用的库。业务专属代码放 internal。
4. 忽视测试目录：可以每个包配 *_test.go，也可以把集成测试统一放在 tests/ 目录下。选择一种风格，保持一致。
5. 根目录太拥挤：go.mod、README.md、[Dockerfile](/posts/docker/)、Makefile 都在根目录是正常的，但如果有 20 个配置文件，就应该建一个 deployments/ 或 scripts/ 目录。

接口与依赖注入的实践

前面提到 internal/service 依赖 Store 接口。实际项目中，依赖注入通常在 cmd/*/main.go 里组装：

package main

import (
	"database/sql"
	"log"

	"example.com/app/internal/handler"
	"example.com/app/internal/service"
	"example.com/app/internal/store"
	_ "github.com/mattn/go-sqlite3"
)

func main() {
	db, err := sql.Open("sqlite3", "app.db")
	if err != nil {
		log.Fatal(err)
	}
	defer db.Close()

	userStore := store.NewUserStore(db)
	userService := service.NewUserService(userStore)
	userHandler := handler.NewUserHandler(userService)

	// 启动 HTTP 服务
	_ = userHandler
}

这种组装方式叫"手工依赖注入"。它不依赖框架，代码直白，适合中小型项目。大型项目可以考虑 wire 这类代码生成工具，但入门阶段手工组装足够好。

配置管理的目录建议

配置文件不要硬编码路径。可以用环境变量指定配置文件位置：

configPath := os.Getenv("APP_CONFIG")
if configPath == "" {
	configPath = "configs/dev.yaml"
}

configs/ 目录放示例配置，configs/dev.yaml 不放真实密钥。生产配置通过环境变量或配置中心注入。

依赖管理与版本演进

现代 Go 项目依赖管理由 go.mod 负责。一个干净的依赖声明应该：

module example.com/myproject

go 1.21

require (
    github.com/gin-gonic/gin v1.9.1
    github.com/lib/pq v1.10.9
)

require (
    github.com/bytedance/sonic v1.9.1 // indirect
)

require 中的 indirect 依赖是 Go 工具自动计算的，不要手动修改。升级依赖用 go get -u ./...，清理未使用的依赖用 go mod tidy。

vendor 模式

某些公司内网无法直接访问互联网，可以用 vendor 把依赖打包到项目里：

go mod vendor

这会在项目内创建一个 vendor/ 目录，包含所有依赖的源代码。CI 构建时加 -mod=vendor 标志即可。vendor 会增加仓库体积，但可以确保构建可重现。

go.sum 的重要性

go.sum 不是锁文件，而是校验和文件。它记录了每个依赖模块版本的内容哈希。带有错误哈希的模块会在构建时被拒绝，这是 Go 对抗供应链攻击的一道防线。不要把 go.sum 加入 .gitignore。

测试的组织方式

Go 的测试文件以 _test.go 结尾，和源代码放在同一个包下。测试分为几种类型：

单元测试：测试单个函数，依赖测试替身隔离外部系统。

func TestServiceCreate(t *testing.T) {
    store := newFakeStore()
    svc := NewService(store)
    note, err := svc.Create(context.Background(), "test")
    if err != nil {
        t.Fatal(err)
    }
    if note.Title != "test" {
        t.Fatalf("title = %q", note.Title)
    }
}

集成测试：连接真实数据库/服务。通常放在一个单独的 tests/ 目录，或者通过 //go:build integration 标签控制。

基准测试：测试性能。用 testing.B 编写：

func BenchmarkCreate(b *testing.B) {
    store := newFakeStore()
    svc := NewService(store)
    for i := 0; i < b.N; i++ {
        svc.Create(context.Background(), "test")
    }
}

运行：go test -bench=. ./...

包命名与导入路径

包名应该短、有意义。常见约定：

• 包名和目录名一致
• 不要出现下划线（my_package 不如 mypackage）
• 避免和内置包名冲突（不要用 strings、time 等作为包名）
• 导入路径通常包含域名：github.com/username/project

被导入的顶层目录是模块名，和目录结构不一定一一对应。这在多模块 monorepo 中尤其要注意。

代码规范与工具链

Go 有内置的格式化工具：

go fmt ./...

格式化不是可选项，应该在 CI 中强制执行。如果代码没有格式化，PR 不应该通过。

除 fmt 外，还应使用：

• go vet ./...：静态分析，检查常见错误
• golangci-lint：社区标准的综合 linter
• go test -race ./...：检测数据竞争
• go mod tidy：清理未使用的依赖

真实项目用例

在实际团队协作中，下面是几个推荐的工作流：

代码审查清单

• 函数是否处理了所有 error 返回值
• 并发代码是否有明确的退出路径和 WaitGroup
• 用户输入是否经过校验和清洗
• 敏感配置是否通过环境变量或加密存储注入
• 测试是否覆盖了正常路径和至少一个错误路径
• 日志是否包含足够的上下文信息但不泄露敏感数据
• 接口设计是否符合最小接口原则

CI/CD 集成建议

• 每次提交前运行 go fmt ./...
• CI 中运行 go vet ./... 和 golangci-lint run
• 单元测试使用 go test -race ./... 检测数据竞争
• 关键路径的 benchmark 加入回归测试
• 使用 go mod verify 确保依赖完整性

性能调优检查点

• 使用 pprof 分析 CPU 和内存使用
• 关注 benchmark 的 allocs/op，减少高频路径的堆分配
• 检查数据库查询是否使用索引
• 确认外部 HTTP 调用有合理的超时设置
• 缓存热点数据，但注意缓存一致性和过期策略

面试高频考点

如果你正在准备 Go 相关面试，以下概念是高频考点：

1. goroutine 和线程的区别
2. channel 的缓冲和非缓冲用法
3. defer 的执行顺序和与返回值的关系
4. map 的并发不安全性和解决方案
5. interface 的隐式实现和类型断言
6. slice 的底层数组和 append 机制
7. GC 的基本原理和调优参数
8. context 的使用场景和超时控制
9. error 的包装和 errors.Is/errors.As
10. sync.Mutex vs sync.RWMutex vs atomic

掌握这些概念意味着你具备了独立开发 Go 服务的基础能力。继续在实际项目中磨练，你会越来越熟悉 Go 的工程风格和最佳实践。

常见问题（FAQ）

Q: 这个特性在实际项目中真的有用吗？
A: 是的。本文介绍的技术来源于真实后端开发场景。无论是标准库工具还是工程实践，在日常服务开发中都会反复用到。

Q: Go 版本会影响示例代码吗？
A: 本文代码主要针对 Go 1.20+ 编写。较新版本（如 1.22、1.23）的语法可能有微调，但核心概念保持不变。如有版本差异，文中会特别说明。

Q: 学习 Go 应该先学标准库还是直接上框架？
A: 强烈建议先学标准库。框架是对标准库的封装和扩展。只有理解了标准库的能力边界，才能正确选择和使用框架，也才能在框架出问题时快速定位。

Q: 代码里的错误处理为什么都是显式的 if err != nil？
A: 这是 Go 的设计哲学。显式错误处理让失败路径清晰可见，不会隐藏在任何 try-catch 之后。习惯了之后，你会发现这种写法实际上降低了排查错误的难度。

Q: 并发相关代码怎么测试？
A: 使用 Go 内置的 -race 标志检测数据竞争：go test -race ./...。结合 sync.WaitGroup 和 context.WithTimeout 编写有退出路径的并发测试，避免 goroutine 泄漏。

常见坑与避坑指南

1. 不要信任用户输入：无论表单、JSON、Cookie 还是 HTTP Header，都当作不可信数据处理，做校验和转义。
2. 资源要释放：文件、数据库连接、HTTP 响应体都要及时关闭。defer 是一个好习惯。
3. 不要忽略错误：即使 defer file.Close() 可能返回错误，至少记录日志。完全忽略错误是 bug 的温床。
4. 不要滥用 goroutine：每个 goroutine 都要有明确的退出路径。使用 sync.WaitGroup 和 context 管理生命周期。
5. 不要硬编码配置：端口、路径、超时时间、密钥都应该从配置读取，让程序适应不同环境。
6. 不要过早优化：先让代码正确和可读，再用 benchmark 和 profile 找到真正的热点。

延伸阅读与实践建议

读完本文后，建议完成以下实践：

1. 把文中所有示例代码在自己的机器上跑一遍
2. 给示例代码补充错误分支的测试用例
3. 尝试基于本文内容构建一个小型完整项目
4. 在 review 他人的 Go 代码时，检查本文提到的边界是否被覆盖
5. 订阅 Go 官方博客，关注语言演进和最佳实践更新

参考资源

• Go 官方网站：https://go.dev/
• Go 标准库文档：https://pkg.go.dev/std
• Go by Example：https://gobyexample.com/
• Effective Go：https://go.dev/doc/effective_go
• Go 常见问题：https://go.dev/doc/faq
• Go 项目实战社区案例和开源项目源码

本文力求在讲解技术细节的同时兼顾工程实用性。Go 语言的设计简洁但不简单，掌握它需要持续的实践和反思。希望这篇文章能成为你学习道路上的一个可靠参考。