构建 Go CLI 应用与可复用库的统一项目结构

本文介绍如何在单个 go 项目中同时提供可导入的库（package）和可执行的命令行工具（CLI），采用业界标准的 cmd/ 目录结构，兼顾代码复用性、模块清晰性和 Go 工具链兼容性。

本文介绍如何在单个 go 项目中同时提供可导入的库（package）和可执行的命令行工具（cli），采用业界标准的 `cmd/` 目录结构，兼顾代码复用性、模块清晰性和 go 工具链兼容性。

在 Go 生态中，一个高质量的开源项目往往既作为库被其他程序导入使用（如 import “github.com/you/mypackage/api”），又自带便捷的命令行接口（如 mypackage-cli sync –dry-run）。实现这一目标的关键不在于“把所有代码塞进 main.go”，而在于合理分层、明确职责边界——将核心逻辑封装为可导出的库包，再让独立的 main 包作为其消费者。

✅ 推荐项目结构（标准实践）

遵循 Go 社区广泛采用的约定，建议采用以下目录布局：

mypackage/ ├── go.mod                          # 必须：定义模块路径（如 module github.com/you/mypackage） ├── api/                            # 核心库包：对外暴露的 API │   ├── account.go                  # package api │   ├── node.go                     # package api │   └── account_test.go ├── cmd/                            # CLI 入口目录（非必须，但强烈推荐） │   └── mypackage/                  # 子命令名 → 构建后生成二进制文件名 │       └── main.go                 # package main：仅负责解析参数、调用 api 包 └── README.md

? 为什么是 cmd/？
Go 官方源码（src/cmd/）、BoltDB、Caddy、terraform 等成熟项目均采用此结构。cmd/ 下每个子目录是一个独立的 package main，go build 时会将其编译为同名可执行文件，并自动安装到 $GOBIN（或 $(go env GOPATH)/bin）。

✅ 修复你的代码：两步走

1. 修正包可见性（关键！）

Go 中只有首字母大写的标识符才可被外部包导出。你原代码中 Account.email 是小写字段，无法被 main 包访问，且结构体本身也未导出：

// api/account.go package api  type Account struct {     Email string // ✅ 首字母大写 → 导出字段     // email string ❌ 小写 → 包内私有，main 无法访问 }

2. 正确组织 main.go（置于 cmd/mypackage/main.go）

// cmd/mypackage/main.go package main  import (     "fmt"     "os"      "github.com/you/mypackage/api" // ✅ 导入你的库包 )  func main() {     if len(os.Args) < 2 {         fmt.Fprintln(os.Stderr, "Usage: mypackage [command]")         os.Exit(1)     }      a := api.Account{Email: "user@example.com"} // ✅ 使用导出的类型和字段     fmt.Printf("Created account: %+vn", a) }

3. 初始化模块并构建

# 在项目根目录执行（确保已配置 GOPROXY） go mod init github.com/you/mypackage  # 构建 CLI（生成 ./mypackage 二进制） go build -o mypackage ./cmd/mypackage  # 或直接安装到 $GOBIN（需设置 GOBIN） go install ./cmd/mypackage  # 其他开发者可一键获取库 + CLI go get github.com/you/mypackage/...

⚠️ 注意事项与最佳实践

• 避免循环依赖：api/ 包绝不应导入 cmd/ 或任何 main 包；cmd/ 可自由导入 api/ 和其他库包。
• go get … 的魔力：go get github.com/you/mypackage/… 中的 … 表示“所有子包”，Go 会自动构建并安装所有 cmd/ 下的 main 包。
• 测试分离：为 api/ 编写单元测试（api/account_test.go），为 cmd/ 编写集成测试（如验证 CLI 输出），互不干扰。
• 版本管理：使用语义化版本（如 v1.2.0）发布 tag，go mod 会自动解析依赖，保障下游用户稳定性。
• 替代方案？ 单 repo 多模块（go.mod in api/ and cmd/）虽可行，但增加复杂度，对绝大多数项目，单模块 + cmd/ 结构更简洁、更符合 Go 惯例。

通过这种结构，你既能 import “github.com/you/mypackage/api” 在业务代码中调用稳定接口，又能 mypackage –help 快速验证功能——真正实现“一套代码，双重价值”。