# 第六章：实战项目 —— 构建一个简易 Web API 服务（深度图解版）
> **本章目标**：综合运用前五章知识，构建一个**生产级别**的 Go Web API 服务（任务管理系统），涵盖路由、中间件、数据库、并发、配置、错误处理、部署等核心技能。
> **项目功能**：
> 1. 创建、读取、更新、删除（CRUD）任务（Task）。
> 2. 支持任务状态（待办、进行中、已完成）。
> 3. 支持按状态、优先级筛选。
> 4. 异步处理任务通知（模拟）。
> 5. 优雅关闭、健康检查、监控指标。
---
## 6.1 项目架构设计
### 6.1.1 目录结构
```
task-api/
├── cmd/
│ └── server/
│ └── main.go # 入口文件
├── internal/
│ ├── handler/ # HTTP 处理层（Handler）
│ │ └── task_handler.go
│ ├── service/ # 业务逻辑层（Service）
│ │ └── task_service.go
│ ├── repository/ # 数据访问层（Repository）
│ │ └── task_repo.go
│ ├── middleware/ # 中间件
│ │ ├── logger.go
│ │ ├── auth.go
│ │ └── recovery.go
│ ├── config/ # 配置管理
│ │ └── config.go
│ └── model/ # 数据模型
│ └── task.go
├── pkg/
│ └── logger/ # 公共工具
│ └── logger.go
├── migrations/ # 数据库迁移
│ └── 001_init.sql
├── .env # 环境变量
├── Dockerfile
├── docker-compose.yml
└── go.mod
```
**📖 深度解析**：
- **cmd/**：应用入口，负责初始化配置、数据库连接、启动服务器。
- **internal/**：私有代码，外部无法导入，保证封装性。
- **handler**：处理 HTTP 请求/响应，参数校验，调用 Service。
- **service**：核心业务逻辑，调用 Repository，处理事务。
- **repository**：数据库操作，SQL 查询，映射到 Model。
- **middleware**：横切关注点（日志、认证、限流）。
- **pkg/**：公共工具库，可被外部导入。
- **migrations/**：数据库结构变更脚本。
---
## 6.2 核心代码实现
### 6.2.1 数据模型 (Model)
```go
// internal/model/task.go
package model
import "time"
type Status string
const (
StatusTodo Status = "todo"
StatusInProgress Status = "in_progress"
StatusDone Status = "done"
)
type Task struct {
ID int64 `json:"id"`
Title string `json:"title"`
Description string `json:"description"`
Status Status `json:"status"`
Priority int `json:"priority"` // 1-5
CreatedAt time.Time `json:"created_at"`
UpdatedAt time.Time `json:"updated_at"`
}
```
**📖 深度解析**：
- **Status**：使用自定义类型（基于 string），增强类型安全，避免魔法字符串。
- **JSON 标签**：明确字段映射，支持 `omitempty` 等选项。
- **时间字段**：`time.Time` 自动映射为 ISO 8601 格式。
---
### 6.2.2 配置管理 (Config)
```go
// internal/config/config.go
package config
import (
"os"
"strconv"
)
type Config struct {
Port string
DBHost string
DBPort string
DBUser string
DBPassword string
DBName string
LogLevel string
}
func Load() *Config {
return &Config{
Port: getEnv("PORT", "8080"),
DBHost: getEnv("DB_HOST", "localhost"),
DBPort: getEnv("DB_PORT", "5432"),
DBUser: getEnv("DB_USER", "postgres"),
DBPassword: getEnv("DB_PASSWORD", "password"),
DBName: getEnv("DB_NAME", "taskdb"),
LogLevel: getEnv("LOG_LEVEL", "info"),
}
}
func getEnv(key, defaultVal string) string {
if val := os.Getenv(key); val != "" {
return val
}
return defaultVal
}
```
**📖 深度解析**：
- **环境变量**：优先从环境变量读取，支持容器化部署。
- **默认值**：提供安全默认值，避免配置缺失导致崩溃。
- **集中管理**：所有配置集中加载，便于传递和测试。
---
### 6.2.3 数据库连接池 (Repository)
```go
// internal/repository/task_repo.go
package repository
import (
"context"
"database/sql"
"fmt"
"task-api/internal/model"
)
type TaskRepo struct {
db *sql.DB
}
func NewTaskRepo(db *sql.DB) *TaskRepo {
return &TaskRepo{db: db}
}
// 创建任务
func (r *TaskRepo) Create(ctx context.Context, task *model.Task) error {
query := `INSERT INTO tasks (title, description, status, priority, created_at, updated_at)
VALUES ($1, $2, $3, $4, NOW(), NOW()) RETURNING id`
err := r.db.QueryRowContext(ctx, query,
task.Title, task.Description, task.Status, task.Priority).Scan(&task.ID)
if err != nil {
return fmt.Errorf("create task failed: %w", err)
}
return nil
}
// 获取所有任务
func (r *TaskRepo) List(ctx context.Context, status *model.Status) ([]model.Task, error) {
query := `SELECT id, title, description, status, priority, created_at, updated_at FROM tasks`
if status != nil {
query += " WHERE status = $1"
rows, err := r.db.QueryContext(ctx, query, *status)
if err != nil {
return nil, err
}
defer rows.Close()
// ... 解析 rows
} else {
rows, err := r.db.QueryContext(ctx, query)
if err != nil {
return nil, err
}
defer rows.Close()
// ... 解析 rows
}
return tasks, nil
}
// 更新任务
func (r *TaskRepo) Update(ctx context.Context, task *model.Task) error {
query := `UPDATE tasks SET title=$1, description=$2, status=$3, priority=$4, updated_at=NOW()
WHERE id=$5`
res, err := r.db.ExecContext(ctx, query,
task.Title, task.Description, task.Status, task.Priority, task.ID)
if err != nil {
return err
}
rows, _ := res.RowsAffected()
if rows == 0 {
return fmt.Errorf("task not found")
}
return nil
}
// 删除任务
func (r *TaskRepo) Delete(ctx context.Context, id int64) error {
query := `DELETE FROM tasks WHERE id = $1`
res, err := r.db.ExecContext(ctx, query, id)
if err != nil {
return err
}
rows, _ := res.RowsAffected()
if rows == 0 {
return fmt.Errorf("task not found")
}
return nil
}
```
**📖 深度解析**：
- **Context 传递**：所有 DB 操作都接收 `context.Context`，支持超时控制和取消。
- **预编译语句**：使用 `$1, $2` 防止 SQL 注入。
- **连接池**：`sql.DB` 内部维护连接池，自动管理连接生命周期。
- **错误包装**：使用 `fmt.Errorf("%w")` 包装错误，保留原始错误信息。
- **资源管理**：`defer rows.Close()` 确保资源释放。
---
### 6.2.4 业务逻辑层 (Service)
```go
// internal/service/task_service.go
package service
import (
"context"
"errors"
"task-api/internal/model"
"task-api/internal/repository"
)
var ErrNotFound = errors.New("task not found")
type TaskService struct {
repo *repository.TaskRepo
}
func NewTaskService(repo *repository.TaskRepo) *TaskService {
return &TaskService{repo: repo}
}
func (s *TaskService) CreateTask(ctx context.Context, task *model.Task) error {
if task.Title == "" {
return errors.New("title is required")
}
if task.Priority < 1 || task.Priority > 5 {
return errors.New("priority must be between 1 and 5")
}
return s.repo.Create(ctx, task)
}
func (s *TaskService) GetTask(ctx context.Context, id int64) (*model.Task, error) {
// 模拟从 repo 获取
task, err := s.repo.GetByID(ctx, id)
if err != nil {
return nil, ErrNotFound
}
return task, nil
}
// 异步通知示例
func (s *TaskService) NotifyTask(ctx context.Context, taskID int64) {
go func() {
// 模拟发送通知
// 注意：这里没有接收 context，实际项目中应传递 context 并处理超时
// 使用 context.WithTimeout 创建子 context
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()
// 发送通知逻辑...
select {
case <-ctx.Done():
// 超时
default:
// 成功
}
}()
}
```
**📖 深度解析**：
- **参数校验**：在 Service 层进行业务规则校验。
- **错误定义**：定义自定义错误（`ErrNotFound`），便于 Handler 层统一处理。
- **异步任务**：使用 `go func()` 启动 Goroutine，注意处理 Context 和超时。
- **依赖注入**：Service 依赖 Repository，便于测试和替换。
---
### 6.2.5 HTTP 处理层 (Handler)
```go
// internal/handler/task_handler.go
package handler
import (
"encoding/json"
"net/http"
"strconv"
"task-api/internal/model"
"task-api/internal/service"
)
type TaskHandler struct {
service *service.TaskService
}
func NewTaskHandler(svc *service.TaskService) *TaskHandler {
return &TaskHandler{service: svc}
}
type Response struct {
Code int `json:"code"`
Message string `json:"message"`
Data interface{} `json:"data,omitempty"`
}
func (h *TaskHandler) CreateTask(w http.ResponseWriter, r *http.Request) {
var task model.Task
if err := json.NewDecoder(r.Body).Decode(&task); err != nil {
h.respondError(w, http.StatusBadRequest, "invalid request body")
return
}
if err := h.service.CreateTask(r.Context(), &task); err != nil {
h.respondError(w, http.StatusInternalServerError, err.Error())
return
}
h.respondJSON(w, http.StatusCreated, "created", task)
}
func (h *TaskHandler) GetTask(w http.ResponseWriter, r *http.Request) {
idStr := r.URL.Query().Get("id")
id, err := strconv.ParseInt(idStr, 10, 64)
if err != nil {
h.respondError(w, http.StatusBadRequest, "invalid id")
return
}
task, err := h.service.GetTask(r.Context(), id)
if err != nil {
h.respondError(w, http.StatusNotFound, "task not found")
return
}
h.respondJSON(w, http.StatusOK, "success", task)
}
func (h *TaskHandler) respondJSON(w http.ResponseWriter, code int, msg string, data interface{}) {
w.Header().Set("Content-Type", "application/json")
w.WriteHeader(code)
json.NewEncoder(w).Encode(Response{Code: code, Message: msg, Data: data})
}
func (h *TaskHandler) respondError(w http.ResponseWriter, code int, msg string) {
h.respondJSON(w, code, msg, nil)
}
```
**📖 深度解析**：
- **统一响应格式**：`Response` 结构体，包含 Code、Message、Data。
- **错误处理**：统一调用 `respondError`，避免重复代码。
- **Context 传递**：`r.Context()` 自动包含超时和取消信号。
- **JSON 编解码**：使用标准库 `encoding/json`。
---
### 6.2.6 中间件 (Middleware)
```go
// internal/middleware/logger.go
package middleware
import (
"log"
"net/http"
"time"
)
func Logger(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
start := time.Now()
log.Printf("Started %s %s", r.Method, r.URL.Path)
next.ServeHTTP(w, r)
log.Printf("Completed %s %s in %v", r.Method, r.URL.Path, time.Since(start))
})
}
// internal/middleware/recovery.go
func Recovery(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
defer func() {
if err := recover(); err != nil {
log.Printf("Panic recovered: %v", err)
http.Error(w, "Internal Server Error", http.StatusInternalServerError)
}
}()
next.ServeHTTP(w, r)
})
}
// internal/middleware/auth.go
func Auth(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
token := r.Header.Get("Authorization")
if token != "secret-token" {
http.Error(w, "Unauthorized", http.StatusUnauthorized)
return
}
next.ServeHTTP(w, r)
})
}
```
**📖 深度解析**：
- **链式调用**：中间件是 `http.Handler` 的装饰器，层层包裹。
- **Logger**：记录请求开始和结束时间，便于性能分析。
- **Recovery**：捕获 Panic，防止服务器崩溃，返回 500 错误。
- **Auth**：简单的 Token 验证，实际项目应使用 JWT。
---
### 6.2.7 主函数与优雅关闭 (Main)
```go
// cmd/server/main.go
package main
import (
"context"
"log"
"net/http"
"os"
"os/signal"
"syscall"
"time"
"task-api/internal/config"
"task-api/internal/handler"
"task-api/internal/middleware"
"task-api/internal/repository"
"task-api/internal/service"
"github.com/gorilla/mux"
_ "github.com/lib/pq"
"database/sql"
)
func main() {
cfg := config.Load()
// 连接数据库
dsn := fmt.Sprintf("host=%s port=%s user=%s password=%s dbname=%s sslmode=disable",
cfg.DBHost, cfg.DBPort, cfg.DBUser, cfg.DBPassword, cfg.DBName)
db, err := sql.Open("postgres", dsn)
if err != nil {
log.Fatal(err)
}
defer db.Close()
// 初始化依赖
taskRepo := repository.NewTaskRepo(db)
taskSvc := service.NewTaskService(taskRepo)
taskHandler := handler.NewTaskHandler(taskSvc)
// 路由
r := mux.NewRouter()
r.Use(middleware.Logger)
r.Use(middleware.Recovery)
r.Use(middleware.Auth)
r.HandleFunc("/tasks", taskHandler.CreateTask).Methods("POST")
r.HandleFunc("/tasks", taskHandler.GetTask).Methods("GET")
srv := &http.Server{
Addr: ":" + cfg.Port,
Handler: r,
}
// 启动服务器
go func() {
log.Printf("Server starting on port %s", cfg.Port)
if err := srv.ListenAndServe(); err != nil && err != http.ErrServerClosed {
log.Fatal(err)
}
}()
// 优雅关闭
quit := make(chan os.Signal, 1)
signal.Notify(quit, syscall.SIGINT, syscall.SIGTERM)
<-quit
log.Println("Shutting down server...")
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()
if err := srv.Shutdown(ctx); err != nil {
log.Fatal("Server forced to shutdown:", err)
}
log.Println("Server exited")
}
```
**📖 深度解析**：
- **依赖注入**：从 Config -> Repo -> Service -> Handler，层层构建。
- **中间件链**：`r.Use()` 按顺序添加中间件（Logger -> Recovery -> Auth）。
- **优雅关闭**：
- 监听 `SIGINT` (Ctrl+C) 和 `SIGTERM` (Docker 停止) 信号。
- 收到信号后，调用 `srv.Shutdown(ctx)`，等待当前请求完成（最多 5 秒）。
- 超时后强制关闭。
- **并发启动**：`go func()` 启动服务器，主进程等待信号。
---
## 6.3 深度图解：请求处理流程
```mermaid
sequenceDiagram
participant Client
participant Router
participant Logger
participant Auth
participant Recovery
participant Handler
participant Service
participant Repo
participant DB
Client->>Router: POST /tasks
Router->>Logger: 调用 Logger 中间件
Logger->>Auth: 记录开始时间
Auth->>Recovery: 验证 Token
Recovery->>Handler: 捕获 Panic
Handler->>Service: CreateTask
Service->>Repo: Create
Repo->>DB: INSERT INTO tasks
DB-->>Repo: 返回 ID
Repo-->>Service: Task with ID
Service-->>Handler: nil
Handler-->>Client: 201 Created + JSON
Logger->>Client: 记录结束时间
```
**📖 深度解析**：
1. **Client**：发起 HTTP 请求。
2. **Router**：匹配路由，调用中间件链。
3. **Logger**：记录请求开始时间。
4. **Auth**：验证 Token，失败直接返回 401。
5. **Recovery**：包裹整个处理链，捕获 Panic。
6. **Handler**：解析请求，调用 Service。
7. **Service**：业务逻辑，调用 Repo。
8. **Repo**：执行 SQL，映射结果。
9. **DB**：执行数据库操作。
10. **返回**：沿调用链返回，Logger 记录结束时间。
---
## 6.4 深度图解：数据库连接池
```mermaid
graph TB
subgraph "应用层"
App[Go 应用]
Pool[sql.DB 连接池]
end
subgraph "数据库层"
DB[(PostgreSQL)]
Conn1[连接 1]
Conn2[连接 2]
Conn3[连接 3]
end
App <--> Pool
Pool <--> Conn1
Pool <--> Conn2
Pool <--> Conn3
Note over Pool: 最大连接数：20
空闲超时：30s
最大生命周期：1h
style Pool fill:#ffeb3b,stroke:#333
style DB fill:#2196f3,stroke:#333,color:#fff
```
**📖 深度解析**：
- **sql.DB**：不是单个连接，而是**连接池**。
- **最大连接数**：通过 `db.SetMaxOpenConns(n)` 设置，避免耗尽数据库资源。
- **空闲超时**：`db.SetConnMaxLifetime()` 设置连接最大生命周期。
- **复用**：连接用完归还池，下次请求直接复用，避免频繁创建/销毁。
---
## 6.5 深度图解：优雅关闭流程
```mermaid
sequenceDiagram
participant OS
participant Main
participant Server
participant Req1
participant Req2
participant DB
OS->>Main: SIGTERM
Main->>Server: Shutdown(ctx)
Server->>Req1: 拒绝新请求
Server->>Req2: 拒绝新请求
Req1-->>Server: 完成处理
Req2-->>Server: 完成处理
Server->>DB: 关闭连接
Server-->>Main: 退出
Main->>OS: 退出
```
**📖 深度解析**：
1. **收到信号**：OS 发送 `SIGTERM`。
2. **停止监听**：`srv.Shutdown()` 停止接收新请求。
3. **等待完成**：等待当前正在处理的请求（Req1, Req2）完成。
4. **关闭资源**：关闭数据库连接、文件句柄等。
5. **退出**：主进程退出。
- **超时控制**：`context.WithTimeout` 防止无限等待。
---
## 6.6 Docker 部署
### 6.6.1 Dockerfile
```dockerfile
FROM golang:1.21-alpine AS builder
WORKDIR /app
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 GOOS=linux go build -o main ./cmd/server
FROM alpine:latest
RUN apk --no-cache add ca-certificates
WORKDIR /root/
COPY --from=builder /app/main .
EXPOSE 8080
CMD ["./main"]
```
### 6.6.2 docker-compose.yml
```yaml
version: '3.8'
services:
app:
build: .
ports:
- "8080:8080"
environment:
- DB_HOST=db
- DB_PORT=5432
- DB_USER=postgres
- DB_PASSWORD=password
- DB_NAME=taskdb
depends_on:
- db
restart: always
db:
image: postgres:15-alpine
environment:
POSTGRES_USER: postgres
POSTGRES_PASSWORD: password
POSTGRES_DB: taskdb
volumes:
- postgres_data:/var/lib/postgresql/data
ports:
- "5432:5432"
volumes:
postgres_data:
```
**📖 深度解析**：
- **多阶段构建**：第一阶段编译，第二阶段只复制二进制文件，镜像更小。
- **环境变量**：通过 `docker-compose` 传递配置。
- **依赖管理**：`depends_on` 确保数据库先启动。
- **数据持久化**：Volume 挂载，防止数据丢失。
---
## 6.7 总结与扩展
### 6.7.1 核心知识点回顾
1. **分层架构**：Handler -> Service -> Repository，职责清晰。
2. **中间件**：日志、认证、恢复，横切关注点。
3. **Context**：超时控制、取消信号、优雅关闭。
4. **连接池**：数据库连接复用，性能优化。
5. **Docker**：容器化部署，环境一致性。
### 6.7.2 扩展方向
1. **ORM**：使用 `gorm` 或 `sqlx` 简化数据库操作。
2. **缓存**：引入 Redis，缓存热点数据。
3. **消息队列**：使用 Kafka/RabbitMQ 处理异步任务。
4. **监控**：集成 Prometheus + Grafana。
5. **CI/CD**：自动化测试、构建、部署。
---
**代码仓库位置**：https://giter.top/openclaw/test/tree/main/chapters/chapter-6
**完整项目代码**：https://giter.top/openclaw/test/tree/main/chapters/chapter-6
---
*最后更新：2026-03-24 00:05 UTC（实战项目版）*