本文介绍如何在单个 go 仓库中专业、可维护地组织面向同一核心库的多个用户界面（cli 和 web），推荐采用 cmd/ 分层结构，兼顾模块复用性、构建清晰性与 go 生态兼容性。
本文介绍如何在单个 go 仓库中专业、可维护地组织面向同一核心库的多个用户界面（cli 和 web），推荐采用 cmd/ 分层结构，兼顾模块复用性、构建清晰性与 go 生态兼容性。
在 Go 工程实践中，随着工具功能演进——例如从命令行密码生成器逐步扩展出 Web 管理界面——项目结构的设计直接影响长期可维护性、构建一致性与协作效率。核心原则是：逻辑分层要清晰，入口隔离要彻底，复用路径要明确。推荐采用业界广泛采纳的 cmd/ 目录约定，而非将 main.go 散落于根目录或混入业务包中。
✅ 推荐结构：cmd/ 驱动的多入口架构
以下是一个生产就绪的目录结构示例（以 github.com/yourname/passgen 为例）：
passgen/ ├── go.mod ├── generation/ # 纯逻辑包：密码生成算法、配置解析、错误定义等 │ ├── generator.go │ ├── options.go │ └── errors.go ├── cmd/ # 所有可执行入口的统一容器（非导入包！） │ ├── passgen-cli/ # CLI 版本：go build -o passgen-cli ./cmd/passgen-cli │ │ └── main.go # package main；import "github.com/yourname/passgen/generation" │ └── passgen-web/ # Web 版本：go build -o passgen-web ./cmd/passgen-web │ └── main.go # package main；同样 import generation 包 └── README.md
? 关键点说明：
- cmd/ 下每个子目录对应一个独立可执行程序，其名称即为最终二进制文件名（如 passgen-cli）；
- 所有 main.go 必须声明 package main，且不构成可被外部导入的 Go 包——它们仅作为构建入口；
- 业务逻辑（如密码生成）严格封装在 generation/（或其他语义化包名，如 pkg/core）中，供所有 UI 层无差别复用；
- 根目录保持“空净”：不放 main.go，不放业务代码，仅承载 go.mod、文档和顶层构建脚本。
? 示例：Web 入口 cmd/passgen-web/main.go
package main
import (
"fmt"
"log"
"net/http"
"github.com/yourname/passgen/generation"
)
func main() {
http.HandleFunc("/generate", func(w http.ResponseWriter, r *http.Request) {
opts := generation.Options{
Length: 16,
Upper: true,
Symbols: true,
}
pw, err := generation.Generate(opts)
if err != nil {
http.Error(w, err.Error(), http.StatusInternalServerError)
return
}
fmt.Fprintf(w, `{"password": %q}`, pw)
})
log.Println("Web server starting on :8080")
log.Fatal(http.ListenAndServe(":8080", nil))
}CLI 入口同理，仅需 import "github.com/yourname/passgen/generation" 并调用相同 API。
立即学习“前端免费学习笔记（深入）”；
⚠️ 注意事项与最佳实践
- 禁止跨 cmd/ 子目录相互 import：passgen-cli 和 passgen-web 必须完全解耦，仅通过共享的 generation/（或 pkg/）通信；
- 避免 cmd/ 下出现非 main 包：若需复用 Web 路由逻辑，应提取至 internal/webutil/（不可被外部导入）或提升至 pkg/web/（如需跨项目复用）；
- 构建与发布友好：CI/CD 可分别执行 go build -o bin/passgen-cli ./cmd/passgen-cli 和 go build -o bin/passgen-web ./cmd/passgen-web，天然支持多产物输出；
- 符合 Go 工具链直觉：go list ./cmd/... 可一键列出所有可构建入口；go get github.com/yourname/passgen/cmd/passgen-cli 支持直接安装（需模块发布）；
- 未来可扩展性强：新增 GUI（如基于 Fyne）、gRPC 服务或 CLI 插件，只需在 cmd/ 下新增子目录，零侵入现有逻辑。
这种结构不是“教条”，而是 Go 社区在数万个项目中沉淀出的最小共识——它让新成员一眼看懂“哪里是入口、哪里是核心、哪里可复用”，真正实现 One Repo, Multiple Faces, Zero Duplication。
