本文介绍 Go 项目中“库 + CLI”一体化的标准实践：将核心逻辑封装为可导入的包，同时在 cmd/ 目录下组织独立的 main 包实现命令行工具，确保代码复用、模块清晰且符合 Go 工程规范。
本文介绍 go 项目中“库 + cli”一体化的标准实践：将核心逻辑封装为可导入的包，同时在 `cmd/` 目录下组织独立的 `main` 包实现命令行工具，确保代码复用、模块清晰且符合 go 工程规范。
在 Go 生态中，一个高质量的开源项目往往既提供可复用的编程接口（library），又附带开箱即用的命令行工具（CLI）。例如 go fmt、gofmt、etcdctl 或 bolt 命令，其背后都对应着同一仓库中可被其他 Go 程序直接 import 的 API 包。这种“一库多用”的设计并非权宜之计，而是 Go 官方推荐、社区广泛采纳的工程惯例。
✅ 正确的项目结构：以 cmd/ 为核心分隔
应避免将 main.go 与业务逻辑文件（如 account.go）平级混放，也不建议让 main 包直接依赖同目录下的非 main 包——这会破坏 Go 的包可见性规则（如你遇到的 undefined: Account 错误，正是因为 main 包无法访问未导出字段 email string，且更根本的是结构体未导出、包路径未正确组织）。
标准做法是：顶层目录作为库根，cmd/ 子目录存放 CLI 入口。示例如下：
mypackage/ // 模块路径：github.com/username/mypackage ├── go.mod ├── api/ // 可导出的核心包（注意：包名建议小写，如 api） │ ├── account.go // package api │ └── node.go ├── cmd/ │ └── mycli/ // 子命令目录（最终生成二进制名：mycli） │ └── main.go // package main —— 唯一入口，仅负责 CLI 调度 └── README.md
? 关键点：api/ 是普通库包（package api），cmd/mycli/main.go 是独立的 package main，它通过 import "github.com/username/mypackage/api" 使用库功能。
✅ 修复你的代码：导出 + 正确引用
首先，修正 account.go：Go 中只有首字母大写的标识符才对外导出。email 字段必须导出（或提供 Getter 方法），且 Account 类型本身也需导出：
// api/account.go
package api
type Account struct {
Email string `json:"email"` // 字段名首字母大写 → 可导出
}
// 可选：提供构造函数增强封装性
func NewAccount(email string) *Account {
return &Account{Email: email}
}然后，更新 cmd/mycli/main.go：
// cmd/mycli/main.go
package main
import (
"fmt"
"os"
"github.com/username/mypackage/api" // ✅ 正确导入库路径
)
func main() {
if len(os.Args) < 2 {
fmt.Println("Usage: mycli <email>")
os.Exit(1)
}
a := api.NewAccount(os.Args[1]) // ✅ 调用库提供的导出函数
fmt.Printf("Created account: %+v\n", a)
}✅ 构建与分发：一条命令完成安装
确保 go.mod 已初始化（go mod init github.com/username/mypackage），然后执行：
# 安装 CLI 到 $GOBIN（默认为 $GOPATH/bin） go install github.com/username/mypackage/cmd/mycli@latest # 用户也可一键安装整个模块（含所有 cmd/ 下的二进制） go install github.com/username/mypackage/...@latest
安装后，mycli 即可全局调用；其他开发者则可通过 import "github.com/username/mypackage/api" 在自己的项目中复用你的逻辑。
⚠️ 注意事项与最佳实践
- 包名 ≠ 目录名：api/ 目录下的包名可以是 api，但也可以是 mypackage 或 client——关键是语义清晰、避免 main 冲突。
- cmd/ 下每个子目录对应一个独立二进制：适合支持多命令场景（如 kubectl get / kubectl apply），每个子目录内只保留一个 main.go。
- 测试分离：api/ 下的单元测试（*_test.go）应与生产代码同包；CLI 的集成测试可放在 cmd/mycli/mycli_test.go 中。
- 版本兼容性：使用 Go Modules 时，务必通过 go mod tidy 管理依赖，并在发布时打语义化版本 Tag（如 v1.0.0），保障用户 go install 的稳定性。
- 参考典范：Go 源码（src/cmd/）、BoltDB、Caddy 均采用此结构，值得深入学习。
通过这种结构，你既能交付一个被广泛 import 的健壮库，又能提供直观易用的 CLI 工具，真正实现“一套代码，双重价值”。
