# 第六章：实战项目 —— 构建一个 Web API 服务（完整实战版）

> **👋 回顾一下：**
>
> 前四章，我们学会了基础语法、数据结构、函数和接口。第五章，我们攻克了并发编程的难关。现在，你已经掌握了 Go 语言的**所有核心技能**！
>
> **🤔 但是，光会理论可不够，我们要“学以致用”！**
>
> 想象一下，你开了一家**“任务管理餐厅”**。
> *   **顾客**（客户端）点菜（发送 HTTP 请求）。
> *   **服务员**（Handler）接收订单，传给**厨师**（Service）。
> *   **厨师**（Service）根据**仓库**（Repository）的食材，做出菜品（业务逻辑）。
> *   **服务员**（Handler）把菜品端给顾客（返回 HTTP 响应）。
>
> 这就是一个典型的 **Web API 服务**！
>
> **🎯 这一章，我们要亲手搭建这家“餐厅”：**
> 1.  **项目架构**：分层设计（Handler -> Service -> Repository）。
> 2.  **核心功能**：创建、查询、更新、删除任务（CRUD）。
> 3.  **并发处理**：用 Goroutine 处理异步通知，用 Mutex 保护共享状态。
> 4.  **优雅关闭**：收到信号后，优雅地停止服务。
> 5.  **Docker 部署**：把餐厅“打包”成集装箱，随时随地运行。
>
> **别担心，我会一步步带你完成，让你体验“从零到一”的成就感！**

---

## 6.1 项目架构设计 —— 餐厅的“布局图”

> **💡 想象一下：**
> 一家好的餐厅，布局一定要清晰：厨房、仓库、大厅各司其职。
> 我们的代码也要这样，**分层管理**，互不干扰。

### 📂 目录结构

```
task-api/
├── cmd/
│   └── server/
│       └── main.go          # 餐厅大门（入口）
├── internal/
│   ├── handler/             # 服务员（处理 HTTP 请求）
│   │   └── task_handler.go
│   ├── service/             # 厨师（业务逻辑）
│   │   └── task_service.go
│   ├── repository/          # 仓库（数据访问）
│   │   └── task_repo.go
│   ├── middleware/          # 保安、清洁工（中间件）
│   │   ├── logger.go
│   │   └── recovery.go
│   └── model/               # 菜单（数据模型）
│       └── task.go
├── go.mod
└── main.go
```

> **💡 老师的小揭秘：**
> *   **cmd/**：程序入口，负责初始化（加载配置、连接数据库、启动服务）。
> *   **internal/**：私有代码，外部无法导入，保证封装性。
>     *   **handler**：处理 HTTP 请求/响应，参数校验，调用 Service。
>     *   **service**：核心业务逻辑，调用 Repository，处理事务。
>     *   **repository**：数据库操作，SQL 查询，映射到 Model。
>     *   **middleware**：横切关注点（日志、认证、恢复）。
> *   **model**：数据模型，定义数据结构。

---

## 6.2 数据模型 (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**：自定义类型，避免魔法字符串。
> *   **JSON 标签**：明确字段映射，前端看到的字段名。
> *   **时间字段**：`time.Time` 自动序列化为 ISO 8601 格式。

---

## 6.3 仓库层 (Repository) —— 食材的“存取”

> **💡 想象一下：**
> 厨师要炒菜，得先去仓库拿食材。
> Repository 就是**数据仓库**，负责从数据库（或内存）存取数据。

### 📝 内存存储（简化版，方便运行）

```go
// internal/repository/task_repo.go
package repository

import (
    "context"
    "fmt"
    "sync"
    "time"
    "task-api/internal/model"
)

type TaskRepo struct {
    mu    sync.Mutex
    tasks map[int64]*model.Task
    nextID int64
}

func NewTaskRepo() *TaskRepo {
    return &TaskRepo{
        tasks:  make(map[int64]*model.Task),
        nextID: 1,
    }
}

func (r *TaskRepo) Create(ctx context.Context, task *model.Task) error {
    r.mu.Lock()
    defer r.mu.Unlock()
    
    task.ID = r.nextID
    r.nextID++
    task.CreatedAt = time.Now()
    task.UpdatedAt = time.Now()
    r.tasks[task.ID] = task
    return nil
}

func (r *TaskRepo) GetByID(ctx context.Context, id int64) (*model.Task, error) {
    r.mu.Lock()
    defer r.mu.Unlock()
    
    task, ok := r.tasks[id]
    if !ok {
        return nil, fmt.Errorf("task not found")
    }
    return task, nil
}

func (r *TaskRepo) List(ctx context.Context) []*model.Task {
    r.mu.Lock()
    defer r.mu.Unlock()
    
    tasks := make([]*model.Task, 0, len(r.tasks))
    for _, t := range r.tasks {
        tasks = append(tasks, t)
    }
    return tasks
}

func (r *TaskRepo) Update(ctx context.Context, task *model.Task) error {
    r.mu.Lock()
    defer r.mu.Unlock()
    
    if _, ok := r.tasks[task.ID]; !ok {
        return fmt.Errorf("task not found")
    }
    task.UpdatedAt = time.Now()
    r.tasks[task.ID] = task
    return nil
}

func (r *TaskRepo) Delete(ctx context.Context, id int64) error {
    r.mu.Lock()
    defer r.mu.Unlock()
    
    if _, ok := r.tasks[id]; !ok {
        return fmt.Errorf("task not found")
    }
    delete(r.tasks, id)
    return nil
}
```

> **💡 老师的小揭秘：**
> *   **Mutex**：保护共享的 `tasks` 映射，避免并发读写冲突。
> *   **Context**：虽然内存存储不需要超时，但保持接口一致性，方便以后切换数据库。
> *   **错误处理**：返回明确的错误信息，便于上层处理。

---

## 6.4 服务层 (Service) —— 厨师的“烹饪”

> **💡 想象一下：**
> 厨师接到订单，检查食材是否足够，然后开始烹饪。
> Service 层负责**业务逻辑**：参数校验、数据转换、调用 Repository。

### 📝 业务逻辑

```go
// internal/service/task_service.go
package service

import (
    "context"
    "errors"
    "time"
    "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) {
    task, err := s.repo.GetByID(ctx, id)
    if err != nil {
        return nil, ErrNotFound
    }
    return task, nil
}

func (s *TaskService) ListTasks(ctx context.Context) []*model.Task {
    return s.repo.List(ctx)
}

func (s *TaskService) UpdateTask(ctx context.Context, task *model.Task) error {
    if task.Title == "" {
        return errors.New("title is required")
    }
    return s.repo.Update(ctx, task)
}

func (s *TaskService) DeleteTask(ctx context.Context, id int64) error {
    return s.repo.Delete(ctx, id)
}

// 异步通知示例
func (s *TaskService) NotifyTask(ctx context.Context, taskID int64) {
    go func() {
        // 模拟发送通知
        // 实际项目中应传递 context 并处理超时
        ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
        defer cancel()
        
        select {
        case <-ctx.Done():
            // 超时
        default:
            // 成功
        }
    }()
}
```

> **💡 老师的小揭秘：**
> *   **参数校验**：在 Service 层进行，确保数据合法。
> *   **错误定义**：定义自定义错误，便于 Handler 层统一处理。
> *   **异步任务**：用 `go func()` 启动 Goroutine，注意处理 Context 和超时。

---

## 6.5 处理层 (Handler) —— 服务员的“接待”

> **💡 想象一下：**
> 服务员接待顾客，记录订单，把菜端回来。
> Handler 层负责**HTTP 请求/响应**，参数解析，调用 Service。

### 📝 HTTP 处理

```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) ListTasks(w http.ResponseWriter, r *http.Request) {
    tasks := h.service.ListTasks(r.Context())
    h.respondJSON(w, http.StatusOK, "success", tasks)
}

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()` 自动包含超时和取消信号。

---

## 6.6 中间件 (Middleware) —— 餐厅的“保安与清洁工”

> **💡 想象一下：**
> 保安检查顾客身份（认证），清洁工记录顾客进出时间（日志），万一顾客闹事（panic），有人处理（恢复）。
> 中间件就是这些**横切关注点**。

### 📝 中间件实现

```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)
    })
}
```

> **💡 老师的小揭秘：**
> *   **链式调用**：中间件是 `http.Handler` 的装饰器，层层包裹。
> *   **Logger**：记录请求开始和结束时间，便于性能分析。
> *   **Recovery**：捕获 Panic，防止服务器崩溃，返回 500 错误。

---

## 6.7 主函数与优雅关闭 —— 餐厅的“打烊”

> **💡 想象一下：**
> 打烊时，不能直接把顾客赶出去，要等他们吃完，再关灯关门。
> 优雅关闭就是**等待当前请求完成**，再停止服务。

### 📝 主函数

```go
// cmd/server/main.go
package main

import (
    "context"
    "log"
    "net/http"
    "os"
    "os/signal"
    "syscall"
    "time"
    
    "task-api/internal/handler"
    "task-api/internal/middleware"
    "task-api/internal/repository"
    "task-api/internal/service"
    
    "github.com/gorilla/mux"
)

func main() {
    // 初始化依赖
    taskRepo := repository.NewTaskRepo()
    taskSvc := service.NewTaskService(taskRepo)
    taskHandler := handler.NewTaskHandler(taskSvc)
    
    // 路由
    r := mux.NewRouter()
    r.Use(middleware.Logger)
    r.Use(middleware.Recovery)
    
    r.HandleFunc("/tasks", taskHandler.CreateTask).Methods("POST")
    r.HandleFunc("/tasks", taskHandler.ListTasks).Methods("GET")
    r.HandleFunc("/tasks", taskHandler.GetTask).Methods("GET").Queries("id", "{id}")
    
    srv := &http.Server{
        Addr:    ":8080",
        Handler: r,
    }
    
    // 启动服务器
    go func() {
        log.Println("Server starting on port 8080")
        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")
}
```

### 🔄 优雅关闭流程图

```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.  **退出**：主进程退出。
> 6.  **超时控制**：`context.WithTimeout` 防止无限等待。

---

## 6.8 运行与测试 —— 开业大吉！

> **🎉 现在，让我们启动餐厅！**

```bash
# 1. 下载依赖
go mod download

# 2. 运行服务
go run cmd/server/main.go

# 3. 测试 API
# 创建任务
curl -X POST http://localhost:8080/tasks \
  -H "Content-Type: application/json" \
  -d '{"title": "学习 Go", "description": "完成第六章", "priority": 5}'

# 查询任务
curl http://localhost:8080/tasks

# 查询单个任务
curl "http://localhost:8080/tasks?id=1"
```

> **💡 老师的小提醒：**
> *   如果看到 `Server starting on port 8080`，说明启动成功！
> *   用 `curl` 或 Postman 测试 API。
> *   按 `Ctrl+C` 触发优雅关闭，观察日志。

---

## 6.9 本章小结

> **🎯 我们学到了什么？**
> 1.  **分层架构**：Handler -> Service -> Repository，职责清晰。
> 2.  **数据模型**：自定义类型、JSON 标签。
> 3.  **并发安全**：用 Mutex 保护共享数据。
> 4.  **中间件**：日志、恢复，横切关注点。
> 5.  **优雅关闭**：信号处理、超时控制。
> 6.  **Docker 部署**：容器化，环境一致性。
>
> **🚀 恭喜你！**
> 你已经完成了**从零基础到实战**的全过程！现在，你不仅掌握了 Go 语言的核心技能，还具备了**独立开发 Web 服务**的能力！
>
> **下一步**：
> *   尝试添加**数据库支持**（PostgreSQL/MySQL）。
> *   添加**用户认证**（JWT）。
> *   添加**缓存**（Redis）。
> *   添加**监控**（Prometheus）。
>
> **Go 的世界很大，你的旅程才刚刚开始！加油！** 🚀✨