390 lines
9.2 KiB
Markdown
390 lines
9.2 KiB
Markdown
# Go 项目中的 cmd 目录详解
|
||
|
||
## 🎯 cmd 目录的作用
|
||
|
||
`cmd` 目录是 Go 项目的标准目录布局，专门用来存放**可执行程序的入口点**。每个子目录代表一个不同的应用程序。
|
||
|
||
## 📁 目录结构示例
|
||
|
||
```
|
||
user-service/
|
||
├── cmd/ # 应用程序入口目录
|
||
│ ├── server/ # HTTP/gRPC 服务器
|
||
│ │ └── main.go # 服务器启动入口
|
||
│ ├── cli/ # 命令行工具
|
||
│ │ └── main.go # CLI 工具入口
|
||
│ ├── worker/ # 后台任务处理器
|
||
│ │ └── main.go # Worker 入口
|
||
│ └── migrator/ # 数据库迁移工具
|
||
│ └── main.go # 迁移工具入口
|
||
├── internal/ # 内部业务逻辑
|
||
├── api/ # API 定义
|
||
└── pkg/ # 可复用的包
|
||
```
|
||
|
||
## 🔧 具体示例
|
||
|
||
### 1. 服务器入口 (cmd/server/main.go)
|
||
|
||
```go
|
||
package main
|
||
|
||
import (
|
||
"context"
|
||
"flag"
|
||
"fmt"
|
||
"log"
|
||
"net"
|
||
"os"
|
||
"os/signal"
|
||
"syscall"
|
||
|
||
"google.golang.org/grpc"
|
||
"user-service/internal/config"
|
||
"user-service/internal/server"
|
||
"user-service/internal/service"
|
||
)
|
||
|
||
func main() {
|
||
// 1. 解析命令行参数
|
||
var (
|
||
configFile = flag.String("config", "configs/config.yaml", "配置文件路径")
|
||
port = flag.Int("port", 8080, "服务端口")
|
||
)
|
||
flag.Parse()
|
||
|
||
// 2. 加载配置
|
||
cfg, err := config.Load(*configFile)
|
||
if err != nil {
|
||
log.Fatal("加载配置失败:", err)
|
||
}
|
||
|
||
// 3. 初始化服务
|
||
userService := service.NewUserService(cfg)
|
||
|
||
// 4. 创建 gRPC 服务器
|
||
grpcServer := grpc.NewServer()
|
||
server.RegisterUserServer(grpcServer, userService)
|
||
|
||
// 5. 启动服务器
|
||
lis, err := net.Listen("tcp", fmt.Sprintf(":%d", *port))
|
||
if err != nil {
|
||
log.Fatal("监听端口失败:", err)
|
||
}
|
||
|
||
// 6. 优雅关闭
|
||
go func() {
|
||
log.Printf("用户服务启动在端口 %d", *port)
|
||
if err := grpcServer.Serve(lis); err != nil {
|
||
log.Fatal("服务启动失败:", err)
|
||
}
|
||
}()
|
||
|
||
// 7. 等待中断信号
|
||
quit := make(chan os.Signal, 1)
|
||
signal.Notify(quit, syscall.SIGINT, syscall.SIGTERM)
|
||
<-quit
|
||
|
||
log.Println("正在关闭服务...")
|
||
grpcServer.GracefulStop()
|
||
log.Println("服务已关闭")
|
||
}
|
||
```
|
||
|
||
### 2. CLI 工具入口 (cmd/cli/main.go)
|
||
|
||
```go
|
||
package main
|
||
|
||
import (
|
||
"flag"
|
||
"fmt"
|
||
"os"
|
||
|
||
"user-service/internal/config"
|
||
"user-service/internal/service"
|
||
)
|
||
|
||
func main() {
|
||
var (
|
||
action = flag.String("action", "", "执行的动作: create-user, list-users, reset-password")
|
||
userID = flag.Int64("user-id", 0, "用户ID")
|
||
username = flag.String("username", "", "用户名")
|
||
)
|
||
flag.Parse()
|
||
|
||
cfg, err := config.Load("configs/config.yaml")
|
||
if err != nil {
|
||
fmt.Printf("加载配置失败: %v\n", err)
|
||
os.Exit(1)
|
||
}
|
||
|
||
userService := service.NewUserService(cfg)
|
||
|
||
switch *action {
|
||
case "create-user":
|
||
if *username == "" {
|
||
fmt.Println("用户名不能为空")
|
||
os.Exit(1)
|
||
}
|
||
user, err := userService.CreateUser(*username)
|
||
if err != nil {
|
||
fmt.Printf("创建用户失败: %v\n", err)
|
||
os.Exit(1)
|
||
}
|
||
fmt.Printf("用户创建成功: ID=%d, Username=%s\n", user.ID, user.Username)
|
||
|
||
case "list-users":
|
||
users, err := userService.ListUsers()
|
||
if err != nil {
|
||
fmt.Printf("获取用户列表失败: %v\n", err)
|
||
os.Exit(1)
|
||
}
|
||
for _, user := range users {
|
||
fmt.Printf("ID: %d, Username: %s, Email: %s\n", user.ID, user.Username, user.Email)
|
||
}
|
||
|
||
case "reset-password":
|
||
if *userID == 0 {
|
||
fmt.Println("用户ID不能为空")
|
||
os.Exit(1)
|
||
}
|
||
newPassword, err := userService.ResetPassword(*userID)
|
||
if err != nil {
|
||
fmt.Printf("重置密码失败: %v\n", err)
|
||
os.Exit(1)
|
||
}
|
||
fmt.Printf("密码重置成功，新密码: %s\n", newPassword)
|
||
|
||
default:
|
||
fmt.Println("不支持的操作，支持的操作: create-user, list-users, reset-password")
|
||
os.Exit(1)
|
||
}
|
||
}
|
||
```
|
||
|
||
### 3. Worker 入口 (cmd/worker/main.go)
|
||
|
||
```go
|
||
package main
|
||
|
||
import (
|
||
"context"
|
||
"log"
|
||
"os"
|
||
"os/signal"
|
||
"syscall"
|
||
"time"
|
||
|
||
"user-service/internal/config"
|
||
"user-service/internal/worker"
|
||
)
|
||
|
||
func main() {
|
||
cfg, err := config.Load("configs/config.yaml")
|
||
if err != nil {
|
||
log.Fatal("加载配置失败:", err)
|
||
}
|
||
|
||
// 创建上下文
|
||
ctx, cancel := context.WithCancel(context.Background())
|
||
defer cancel()
|
||
|
||
// 初始化 Worker
|
||
emailWorker := worker.NewEmailWorker(cfg)
|
||
notificationWorker := worker.NewNotificationWorker(cfg)
|
||
|
||
// 启动 Workers
|
||
go func() {
|
||
log.Println("启动邮件处理 Worker...")
|
||
if err := emailWorker.Start(ctx); err != nil {
|
||
log.Printf("邮件 Worker 错误: %v", err)
|
||
}
|
||
}()
|
||
|
||
go func() {
|
||
log.Println("启动通知处理 Worker...")
|
||
if err := notificationWorker.Start(ctx); err != nil {
|
||
log.Printf("通知 Worker 错误: %v", err)
|
||
}
|
||
}()
|
||
|
||
// 优雅关闭
|
||
quit := make(chan os.Signal, 1)
|
||
signal.Notify(quit, syscall.SIGINT, syscall.SIGTERM)
|
||
<-quit
|
||
|
||
log.Println("正在关闭 Workers...")
|
||
cancel()
|
||
|
||
// 等待 Workers 完成
|
||
time.Sleep(5 * time.Second)
|
||
log.Println("Workers 已关闭")
|
||
}
|
||
```
|
||
|
||
### 4. 数据库迁移工具 (cmd/migrator/main.go)
|
||
|
||
```go
|
||
package main
|
||
|
||
import (
|
||
"flag"
|
||
"log"
|
||
|
||
"user-service/internal/config"
|
||
"user-service/internal/migration"
|
||
)
|
||
|
||
func main() {
|
||
var (
|
||
direction = flag.String("direction", "up", "迁移方向: up 或 down")
|
||
steps = flag.Int("steps", 0, "迁移步数，0表示全部")
|
||
)
|
||
flag.Parse()
|
||
|
||
cfg, err := config.Load("configs/config.yaml")
|
||
if err != nil {
|
||
log.Fatal("加载配置失败:", err)
|
||
}
|
||
|
||
migrator := migration.NewMigrator(cfg.Database.URL)
|
||
|
||
switch *direction {
|
||
case "up":
|
||
log.Println("执行数据库迁移...")
|
||
if err := migrator.Up(*steps); err != nil {
|
||
log.Fatal("迁移失败:", err)
|
||
}
|
||
log.Println("迁移成功")
|
||
|
||
case "down":
|
||
log.Println("回滚数据库迁移...")
|
||
if err := migrator.Down(*steps); err != nil {
|
||
log.Fatal("回滚失败:", err)
|
||
}
|
||
log.Println("回滚成功")
|
||
|
||
default:
|
||
log.Fatal("不支持的迁移方向:", *direction)
|
||
}
|
||
}
|
||
```
|
||
|
||
## 🎯 为什么这样设计？
|
||
|
||
### 1. **关注点分离**
|
||
|
||
- `cmd/` 只负责程序启动和配置解析
|
||
- `internal/` 负责具体的业务逻辑
|
||
- 每个应用程序有独立的入口点
|
||
|
||
### 2. **多种运行模式**
|
||
|
||
```bash
|
||
# 启动 HTTP/gRPC 服务器
|
||
./user-service-server -port=8080 -config=prod.yaml
|
||
|
||
# 使用 CLI 工具
|
||
./user-service-cli -action=create-user -username=john
|
||
|
||
# 启动后台 Worker
|
||
./user-service-worker
|
||
|
||
# 执行数据库迁移
|
||
./user-service-migrator -direction=up
|
||
```
|
||
|
||
### 3. **构建和部署灵活性**
|
||
|
||
```dockerfile
|
||
# Dockerfile 示例
|
||
FROM golang:1.20-alpine AS builder
|
||
|
||
WORKDIR /app
|
||
COPY . .
|
||
|
||
# 分别构建不同的应用程序
|
||
RUN go build -o server ./cmd/server
|
||
RUN go build -o cli ./cmd/cli
|
||
RUN go build -o worker ./cmd/worker
|
||
RUN go build -o migrator ./cmd/migrator
|
||
|
||
FROM alpine:latest
|
||
RUN apk --no-cache add ca-certificates
|
||
WORKDIR /root/
|
||
|
||
# 根据需要复制不同的可执行文件
|
||
COPY --from=builder /app/server .
|
||
COPY --from=builder /app/migrator .
|
||
|
||
# 可以选择启动不同的程序
|
||
CMD ["./server"]
|
||
```
|
||
|
||
### 4. **Makefile 示例**
|
||
|
||
```makefile
|
||
# Makefile
|
||
.PHONY: build-server build-cli build-worker build-migrator
|
||
|
||
build-server:
|
||
go build -o bin/server ./cmd/server
|
||
|
||
build-cli:
|
||
go build -o bin/cli ./cmd/cli
|
||
|
||
build-worker:
|
||
go build -o bin/worker ./cmd/worker
|
||
|
||
build-migrator:
|
||
go build -o bin/migrator ./cmd/migrator
|
||
|
||
build-all: build-server build-cli build-worker build-migrator
|
||
|
||
run-server:
|
||
./bin/server -port=8080
|
||
|
||
run-worker:
|
||
./bin/worker
|
||
|
||
migrate-up:
|
||
./bin/migrator -direction=up
|
||
|
||
migrate-down:
|
||
./bin/migrator -direction=down -steps=1
|
||
```
|
||
|
||
## 🚀 在你的项目中的应用
|
||
|
||
在你当前的项目中，每个服务都应该有这样的结构：
|
||
|
||
```
|
||
apps/user/
|
||
├── cmd/
|
||
│ ├── server/main.go # gRPC 服务器
|
||
│ ├── cli/main.go # 用户管理 CLI
|
||
│ └── migrator/main.go # 数据库迁移
|
||
├── internal/ # 业务逻辑
|
||
├── user.proto # API 定义
|
||
└── Dockerfile
|
||
|
||
apps/gateway/
|
||
├── cmd/
|
||
│ ├── server/main.go # HTTP 网关服务器
|
||
│ └── cli/main.go # 网关管理 CLI
|
||
├── internal/
|
||
├── gateway.api
|
||
└── Dockerfile
|
||
```
|
||
|
||
## 📋 总结
|
||
|
||
`cmd` 目录的核心作用：
|
||
|
||
1. **程序入口点** - 每个 main.go 是一个独立的应用程序
|
||
2. **配置解析** - 处理命令行参数和配置文件
|
||
3. **依赖注入** - 初始化和连接各个组件
|
||
4. **生命周期管理** - 启动、运行、优雅关闭
|
||
5. **多种运行模式** - 服务器、CLI、Worker 等不同形态
|