本文介绍如何在单个 go 仓库中合理组织含多个用户界面（如命令行工具、web 服务）的工具型项目，推荐采用 cmd/ 目录分治模式，兼顾可维护性、可构建性和 go 生态惯例。
本文介绍如何在单个 go 仓库中合理组织含多个用户界面（如命令行工具、web 服务）的工具型项目，推荐采用 cmd/ 目录分治模式，兼顾可维护性、可构建性和 go 生态惯例。
在 Go 工程实践中，一个工具库随着演进常需支持多种交互入口：最初可能是 CLI，随后扩展 Web UI、gRPC 接口甚至桌面前端。此时项目结构设计直接影响长期可维护性。最佳实践是将“可执行程序”与“可复用逻辑”严格分离——核心业务逻辑（如密码生成算法、配置解析、加密工具等）应封装为独立的、无副作用的库包；而所有面向用户的入口（即 main 函数所在位置）统一收归 cmd/ 目录下，按功能命名子目录。
✅ 推荐结构（单仓库、多入口、符合 Go 惯例）
以密码生成工具为例，标准布局如下：
github.com/yourname/password-tool/ ├── go.mod ├── generation/ # 核心库包：纯逻辑，无 main，可被任意 UI 调用 │ ├── generator.go │ └── options.go ├── cmd/ # 所有可执行入口的根目录（非 package！仅组织用途） │ ├── pwgen/ # CLI 工具：go build -o pwgen ./cmd/pwgen │ │ └── main.go # package main；import "github.com/yourname/password-tool/generation" │ └── pwweb/ # Web 服务：go build -o pwweb ./cmd/pwweb │ └── main.go # package main；同上导入 generation 包 └── README.md
? 关键点：
- cmd/ 下每个子目录（如 pwgen、pwweb）本身不是 Go 包名，而是构建目标名称；其内部 main.go 必须声明 package main，且只能包含该入口所需的最小依赖。
- generation/ 是真正的可复用库：它不依赖 cmd/，无 main，可单独测试、文档化、版本化，甚至未来开放为独立模块（go get github.com/yourname/password-tool/generation）。
- 构建时直接指定路径即可生成对应二进制：
go build -o pwgen ./cmd/pwgen go build -o pwweb ./cmd/pwweb
⚠️ 注意事项与常见误区
- 不要把 main.go 放在项目根目录：这会污染顶层命名空间，且无法同时支持多个入口。
- 避免 cmd/ 下混用非 main 包：cmd/ 仅用于 package main；其他逻辑（如 Web 路由封装、CLI 参数解析器）应下沉至 internal/ 或提升为 pkg/ 子模块，确保 cmd/ 保持极简。
- 命名清晰优于“通用”：pwgen 比 cli 更具语义，pwweb 比 http 更易识别；最终二进制名即目录名，直接影响用户使用体验。
- Web 入口仍需遵循 Go Web 最佳实践：例如使用 net/http 标准库、结构化路由（如 chi）、静态文件托管路径隔离，但这些实现细节全部封装在 cmd/pwweb/main.go 及其同目录辅助文件中，不暴露给 generation/。
✅ 总结：为什么这是“Go-gettable”的方式？
这种结构完全兼容 Go 的模块系统和工具链：
- go list ./... 可精准扫描所有包（不含 cmd/ 下的 main）；
- go test ./... 自动跳过 cmd/（因 main 包不可测试），聚焦于 generation/ 和 internal/；
- 第三方可 go get github.com/yourname/password-tool/generation 复用核心能力，而无需拉取无关的 UI 代码；
- 发布时通过 goreleaser 等工具可一键构建多平台 CLI/Web 二进制，并分别签名、归档。
最终，好的 Go 项目结构不是追求“看起来复杂”，而是让每个目录职责单一、边界清晰、生长有序——cmd/ 是门面，generation/ 是心脏，二者泾渭分明，方得长久可维护。
