Golang cmd目录在项目中的职责说明

cmd目录是Go项目中存放可执行程序入口的标准化位置，每个子目录对应一个独立二进制文件，必须包含且仅包含一个main函数，业务逻辑须下沉至internal或pkg，不可在cmd中直接编写。

cmd 目录存放可执行程序入口

Go 项目中 cmd 目录的唯一职责是：**每个子目录对应一个独立的可执行命令（binary）**，其内部必须包含且仅包含一个 main 函数。它不是“工具集合”或“脚本目录”，而是 Go 模块对外暴露 CLI 程序的标准化出口。

• 每个 cmd/xxx 下必须有 main.go，且该文件里只能有 package main 和 func main()
• 不能在 cmd 中直接写业务逻辑——所有核心逻辑应下沉到 internal 或 pkg，cmd 只做初始化、参数解析、依赖注入和启动调用
• 多个命令（如 cmd/server 和 cmd/cli）可共用同一套库，但构建出的是两个完全独立的二进制文件

为什么不能把 main.go 放在项目根目录

根目录放 main.go 看似简单，但会破坏模块边界和复用性。Go Modules 要求每个可执行命令是一个独立的 build unit，而 cmd 目录结构天然支持：

• go build -o myserver ./cmd/server —— 明确指定输出哪个 binary
• CI/CD 中可并行构建不同命令：go build ./cmd/... 自动发现所有 cmd/*
• 避免根目录下 main.go 与测试、配置、文档等文件混杂，降低 go list ./... 的噪音
• 当项目演变为多进程架构（如 server + worker + migrate），cmd 是最无歧义的组织方式

常见错误：在 cmd 中 import internal 包失败

报错信息通常是：import "myproject/internal/xxx" is a program, not an importable package。根本原因是：Go 规定 internal 包只能被其父目录或同级子目录中的代码导入，而 cmd/xxx 和 internal/xxx 是平级目录，不满足路径约束。

正确做法是：确保 cmd/xxx 的父目录就是 module root（即 go.mod 所在目录），且 internal 也在同一级。目录结构必须为：

myproject/
├── go.mod
├── cmd/
│   └── server/
│       └── main.go   // import "myproject/internal/handler"
├── internal/
│   └── handler/
│       └── handler.go

• 如果 cmd 下某命令需要引用 internal，它的 import path 必须以 module name 开头，如 "myproject/internal/config"
• 不要用相对路径（../../internal/...）或 ./internal/... —— Go 不允许
• 若误将 cmd 放在子模块内（如 submodule/cmd/...），会导致 internal 不可见，此时应调整模块划分

cmd 目录不影响运行时性能，但影响构建和部署粒度

cmd 本身不参与运行，只影响构建阶段。但它决定了你交付什么、怎么交付：

• 每个 cmd/xxx 可单独 go install，便于开发者本地快速安装调试工具
• Docker 多阶段构建中，可针对不同 cmd 写不同 Dockerfile（如 server 需要监听端口，migrate 只需数据库连接）
• 发布时生成多个二进制（myapp-server, myapp-migrate），而非一个大而全的 binary，更利于权限隔离和灰度发布
• 注意：所有 cmd 共享同一份 go.mod 依赖，因此升级一个依赖会影响全部命令 —— 这是设计使然，不是 bug

Go 的 cmd 目录本质是构建契约，不是代码组织习惯。一旦项目需要交付不止一个可执行文件，这个目录就不再是“可选”，而是避免后续重构成本的必经路径。最容易被忽略的一点是：它要求你从第一天就思考「哪些逻辑属于通用能力」和「哪些逻辑绑定特定入口」——这种分离不会自动发生，得靠目录结构倒逼设计。