本文介绍 Go 语言中如何科学组织含多个用户界面（如命令行、Web 服务）的单一工具项目，推荐采用 cmd/ 分层结构，将各入口点隔离为独立可构建的 main 包，并复用统一的核心逻辑包。
本文介绍 go 语言中如何科学组织含多个用户界面（如命令行、web 服务）的单一工具项目，推荐采用 `cmd/` 分层结构，将各入口点隔离为独立可构建的 `main` 包，并复用统一的核心逻辑包。
在 Go 工程实践中，一个工具随着演进逐步支持多种交互方式（如 CLI、HTTP API、Web 前端、TUI）是常见需求。关键在于：既要保持各 UI 入口的独立可部署性，又要避免核心逻辑重复与耦合。Go 官方生态与主流开源项目（如 Kubernetes、Docker、Caddy）普遍采用一种清晰、可扩展且符合 Go 惯例的结构——即 cmd/ 目录驱动的多主程序组织模式。
✅ 推荐结构：cmd/ 下按可执行名分治
以密码生成工具为例，建议项目根目录结构如下：
github.com/yourname/passwordgen/
├── go.mod
├── generation/ # 核心业务逻辑包（无 main，纯导出函数/类型）
│ ├── generator.go
│ └── options.go
├── cmd/
│ ├── passgen/ # CLI 入口：go build ./cmd/passgen → 生成二进制 `passgen`
│ │ └── main.go
│ └── passgen-web/ # Web 服务入口：go build ./cmd/passgen-web → 生成 `passgen-web`
│ └── main.go
└── internal/ # （可选）仅供本项目内部使用的共享组件（如日志封装、配置解析）
└── ...
- 所有 cmd/*/main.go 文件必须声明 package main，且各自包含独立的 func main()；
- 每个 cmd/* 子目录对应一个可单独构建、安装、发布的可执行文件（go install ./cmd/passgen）；
- generation/ 是纯粹的库包（library package），不依赖任何 UI 层，仅提供 Generate(...)、Validate(...) 等无副作用函数，便于测试与复用；
- 根目录不放置 main.go，避免歧义；go build . 将报错（无 main 包），这反而是良好信号——强制明确构建目标。
? 示例：Web 入口 cmd/passgen-web/main.go
package main
import (
"log"
"net/http"
"github.com/yourname/passwordgen/generation"
)
func main() {
http.HandleFunc("/generate", func(w http.ResponseWriter, r *http.Request) {
pw, err := generation.Generate(generation.Options{
Length: 16,
IncludeSymbols: true,
})
if err != nil {
http.Error(w, err.Error(), http.StatusInternalServerError)
return
}
w.Header().Set("Content-Type", "text/plain")
w.Write([]byte(pw))
})
log.Println("Web server listening on :8080")
log.Fatal(http.ListenAndServe(":8080", nil))
}
CLI 入口同理，只需 import "github.com/yourname/passwordgen/generation" 并调用相同 API。
⚠️ 注意事项与最佳实践
- 禁止跨 cmd/ 目录共享代码：若多个 UI 需共用 HTTP 路由逻辑或模板，应提取至 internal/ 或 pkg/（对外公开时用 pkg/），而非直接在 cmd/ 内 import 另一个 cmd/ 子目录（会破坏单入口原则）；
- 命名语义化：cmd/passgen-cli 比 cmd/cmdline 更清晰；cmd/passgen-api 比 cmd/web 更准确反映职责；
- 可测试性保障：generation/ 包应 100% 覆盖单元测试，而 cmd/ 下的 main.go 仅做胶水逻辑（参数解析、HTTP 路由注册等），无需复杂测试；
- Go Modules 兼容性：该结构天然支持 go get —— 用户可通过 go install github.com/yourname/passwordgen/cmd/passgen@latest 直接安装 CLI，或 @v1.2.0 指定版本；
- 未来扩展友好：新增 TUI（如基于 bubbletea）？只需添加 cmd/passgen-tui/；增加 gRPC 服务？新建 cmd/passgen-grpc/ —— 零侵入核心逻辑。
这种结构不是“约定俗成的魔法”，而是 Go 设计哲学的自然延伸：关注点分离、显式依赖、最小接口、可组合性。它让项目从第一天起就具备专业级可维护性与可交付性——无论你现在只有 CLI，还是明天要上线 Web 控制台，架构已为你铺好道路。
