本文详解如何通过标准 Go 项目结构，在同一仓库中同时提供可导入的库（import "host.com/project"）和可安装的命令行工具（go install host.com/project/cmd/project），兼顾 Go 社区惯例、模块语义清晰性与维护可持续性。
本文详解如何通过标准 go 项目结构，在同一仓库中同时提供可导入的库（import "host.com/project"）和可安装的命令行工具（go install host.com/project/cmd/project），兼顾 go 社区惯例、模块语义清晰性与维护可持续性。
在 Go 生态中，“一个仓库、双产出”——即同时暴露公共 API 库（library）与同名可执行命令（CLI）——是常见且合理的需求（例如 kubectl 对应 k8s.io/client-go，hugo 对应 github.com/gohugoio/hugo）。但若结构设计不当，极易导致导入路径混乱、包名歧义或 go get 行为不符合预期。核心原则是：库即模块根路径，CLI 作为独立 main 包置于 cmd/ 子目录下。
✅ 推荐结构（符合 Go 官方实践与主流项目惯例）
host.com/project/ ← 模块根目录（go.mod 所在处） ├── go.mod ← module host.com/project ├── project.go ← package project，导出核心类型/函数 ├── utils.go ├── internal/ ← （可选）仅本模块内使用的私有包 │ └── helpers/ ├── cmd/ ← 所有可执行命令的统一入口目录 │ └── project/ ← 命令名即二进制名（go install 后生成 ./project） │ └── main.go ← package main；import "host.com/project" └── README.md
-
库的使用方式：用户直接导入模块根路径
import "host.com/project"
project.go中声明package project，所有导出符号（如NewClient()、DoWork()）自然属于project.命名空间，语义清晰、零认知负担。 -
CLI 的构建与安装方式：
# 构建并安装到 $GOBIN（如 ~/go/bin） go install host.com/project/cmd/project@latest # 安装后即可全局调用 project --help
⚠️ 注意：
go get自 Go 1.17 起已默认不安装命令，仅下载依赖；go install才是正确安装 CLI 的命令（需指定@version或@latest）。
? 示例代码
host.com/project/project.go：
package project
import "fmt"
// Client 是库的核心结构
type Client struct {
Name string
}
// DoSomething 演示导出方法
func (c *Client) DoSomething() string {
return fmt.Sprintf("Hello from %s!", c.Name)
}
host.com/project/cmd/project/main.go：
package main
import (
"flag"
"fmt"
"os"
"host.com/project" // ← 导入根模块，复用全部库能力
)
func main() {
name := flag.String("name", "Project", "client name")
flag.Parse()
client := &project.Client{Name: *name}
fmt.Println(client.DoSomething())
os.Exit(0)
}
运行效果：
$ go install host.com/project/cmd/project@latest $ project --name="GoCLI" Hello from GoCLI!
? 关键注意事项
-
禁止将
main包放在模块根目录：否则go mod init会误判模块为cmd类型，且无法被其他项目正常import。 -
cmd/下每个子目录对应一个独立二进制：支持多命令（如cmd/project,cmd/projectctl），各main包互不干扰。 -
避免
core/、lib/等非标准子目录：它们破坏模块扁平性，迫使用户写import "host.com/project/core"，违背“包名 = 最后路径段”的 Go 约定。 -
测试与文档同步覆盖：
project_test.go放在根目录测试库逻辑；CLI 的集成测试建议放在cmd/project/内（如main_test.go使用os/exec调用自身二进制）。 -
版本兼容性：当库 API 变更时，务必遵循 Semantic Import Versioning，如升级 v2 需重命名模块为
host.com/project/v2并更新go.mod。
✅ 总结
采用 root/ + cmd/<binary>/</binary> 结构，既严格遵循 Go 模块语义（模块路径 = 库导入路径），又天然支持多 CLI 场景，已被 Delve、golang.org/x/tools、Cobra CLI 生成器等大量高星项目验证。它让使用者“所见即所得”：import "host.com/project" 得到库，go install host.com/project/cmd/project 得到工具——无需记忆别名、无需额外配置，真正实现专业、简洁、可持续的 Go 工程实践。
