本文介绍如何在单个 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: %+v\n", 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 快速验证功能——真正实现“一套代码，双重价值”。
