第 82 课：实战：REST API 服务

学习目标

完成本课程的学习，你将能够：

理解并设计一个遵循 RESTful 规范的 API 服务结构。
使用 Gin 框架快速搭建一个包含 CRUD 功能的 Web 服务器。
应用 Go 的并发模型（goroutine 和 channel）来处理 API 请求中的耗时或并行任务。
实现健壮的错误处理和请求验证，提升 API 的可靠性。
集成数据持久化（以模拟的内存数据库为例），为前后端分离项目提供后端支持。

核心概念

1. 什么是 RESTful API？

REST (Representational State Transfer) 不是协议，而是一种架构风格。它将网络上的“资源”（如用户、文章、订单）用唯一的 URI 标识，并通过标准的 HTTP 方法（GET, POST, PUT, DELETE）来操作这些资源。

资源 (Resource)：用名词表示，如 /api/v1/books。
方法 (Method)：
- GET：获取一个或多个资源。
- POST：创建一个新资源。
- PUT/PATCH：更新一个资源。
- DELETE：删除一个资源。

2. 为什么选择 Gin？

Gin 是 Go 语言中最受欢迎的 Web 框架之一。它像一个高效的“路由器”和“管家”，帮你处理了很多底层的 HTTP 细节。

高性能：基于 httprouter，速度很快。
简洁的 API：路由注册、参数解析、中间件都非常直观。
强大的中间件：可以轻松添加日志、认证、跨域等通用功能。

3. 并发在 API 中的应用场景

在构建 API 时，Go 的并发优势常用于：

并发查询：当一个请求需要从多个微服务或数据库表获取数据时，可以同时发起多个 goroutine 查询，然后汇总结果。
后台任务：创建资源后，将耗时的操作（如发送邮件、处理图片）放到 goroutine 中异步执行，让 API 立即返回响应。
限流与熔断：使用 channel 或 sync 包中的工具来控制对资源的并发访问。

代码示例

下面我们将构建一个简单的图书管理系统 REST API，支持基本的增删改查。

项目结构：

book-api/
├── main.go
├── handler.go      # 处理HTTP请求的函数
├── model.go        # 数据模型与模拟数据库
└── go.mod

第一步：初始化项目并安装 Gin

mkdir book-api && cd book-api
go mod init book-api
go get -u github.com/gin-gonic/gin

第二步：定义数据模型与模拟数据库 (model.go)

package main

import (
    "errors"
    "sync"
)

// Book 是我们的核心数据结构
type Book struct {
    ID     string  `json:"id"`
    Title  string  `json:"title" binding:"required"`
    Author string  `json:"author" binding:"required"`
    Price  float64 `json:"price" binding:"required,gt=0"` // 价格必须大于0
}

// 模拟一个数据库，使用 map 和读写锁实现并发安全
var (
    bookStore = make(map[string]*Book)
    storeLock sync.RWMutex
    nextID    = 1
)

// 初始化一些测试数据
func init() {
    books := []Book{
        {ID: "1", Title: "Go Programming", Author: "John Doe", Price: 29.99},
        {ID: "2", Title: "Concurrency in Go", Author: "Jane Smith", Price: 35.50},
    }
    for _, b := range books {
        b := b
        bookStore[b.ID] = &b
    }
    nextID = 3
}

// GetAllBooks 从“数据库”获取所有图书
func GetAllBooks() []*Book {
    storeLock.RLock()
    defer storeLock.RUnlock()

    books := make([]*Book, 0, len(bookStore))
    for _, b := range bookStore {
        books = append(books, b)
    }
    return books
}

// GetBookByID 根据ID获取单本书
func GetBookByID(id string) (*Book, error) {
    storeLock.RLock()
    defer storeLock.RUnlock()

    book, ok := bookStore[id]
    if !ok {
        return nil, errors.New("book not found")
    }
    return book, nil
}

// CreateBook 创建一本新书
func CreateBook(b *Book) error {
    storeLock.Lock()
    defer storeLock.Unlock()

    // 检查是否已存在
    for _, existing := range bookStore {
        if existing.Title == b.Title && existing.Author == b.Author {
            return errors.New("book already exists")
        }
    }
    b.ID = fmt.Sprintf("%d", nextID)
    nextID++
    bookStore[b.ID] = b
    return nil
}

// UpdateBook 更新一本书的信息
func UpdateBook(id string, newBook *Book) (*Book, error) {
    storeLock.Lock()
    defer storeLock.Unlock()

    existing, ok := bookStore[id]
    if !ok {
        return nil, errors.New("book not found")
    }
    existing.Title = newBook.Title
    existing.Author = newBook.Author
    existing.Price = newBook.Price
    return existing, nil
}

// DeleteBook 删除一本书
func DeleteBook(id string) error {
    storeLock.Lock()
    defer storeLock.Unlock()

    if _, ok := bookStore[id]; !ok {
        return errors.New("book not found")
    }
    delete(bookStore, id)
    return nil
}

第三步：编写 HTTP 处理器 (handler.go)

package main

import (
    "net/http"
    "github.com/gin-gonic/gin"
)

// GetBooks 处理 GET /books
func GetBooks(c *gin.Context) {
    books := GetAllBooks()
    c.JSON(http.StatusOK, gin.H{
        "success": true,
        "data":    books,
    })
}

// GetBook 处理 GET /books/:id
func GetBook(c *gin.Context) {
    id := c.Param("id")
    book, err := GetBookByID(id)
    if err != nil {
        c.JSON(http.StatusNotFound, gin.H{
            "success": false,
            "message": err.Error(),
        })
        return
    }
    c.JSON(http.StatusOK, gin.H{
        "success": true,
        "data":    book,
    })
}

// CreateBook 处理 POST /books
func CreateBook(c *gin.Context) {
    var newBook Book
    // 使用 ShouldBindJSON 进行自动验证（基于结构体的 binding tag）
    if err := c.ShouldBindJSON(&newBook); err != nil {
        c.JSON(http.StatusBadRequest, gin.H{
            "success": false,
            "message": "Invalid input: " + err.Error(),
        })
        return
    }

    if err := CreateBook(&newBook); err != nil {
        c.JSON(http.StatusConflict, gin.H{
            "success": false,
            "message": err.Error(),
        })
        return
    }

    c.JSON(http.StatusCreated, gin.H{
        "success": true,
        "data":    newBook,
    })
}

// UpdateBook 处理 PUT /books/:id
func UpdateBook(c *gin.Context) {
    id := c.Param("id")
    var updateBook Book
    if err := c.ShouldBindJSON(&updateBook); err != nil {
        c.JSON(http.StatusBadRequest, gin.H{
            "success": false,
            "message": "Invalid input: " + err.Error(),
        })
        return
    }

    updated, err := UpdateBook(id, &updateBook)
    if err != nil {
        c.JSON(http.StatusNotFound, gin.H{
            "success": false,
            "message": err.Error(),
        })
        return
    }

    c.JSON(http.StatusOK, gin.H{
        "success": true,
        "data":    updated,
    })
}

// DeleteBook 处理 DELETE /books/:id
func DeleteBook(c *gin.Context) {
    id := c.Param("id")
    if err := DeleteBook(id); err != nil {
        c.JSON(http.StatusNotFound, gin.H{
            "success": false,
            "message": err.Error(),
        })
        return
    }
    c.JSON(http.StatusOK, gin.H{
        "success": true,
        "message": "Book deleted successfully",
    })
}

// SimulateAsyncTask 模拟一个并发场景：创建图书后，异步发送通知
func SimulateAsyncTask(c *gin.Context) {
    var newBook Book
    if err := c.ShouldBindJSON(&newBook); err != nil {
        c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
        return
    }

    if err := CreateBook(&newBook); err != nil {
        c.JSON(http.StatusConflict, gin.H{"error": err.Error()})
        return
    }

    // ** 并发示例 **：启动一个 goroutine 发送“邮件通知”，不阻塞主响应
    go func(book Book) {
        // 模拟耗时的网络或IO操作
        fmt.Printf("Sending notification for new book: %s by %s\n", book.Title, book.Author)
        time.Sleep(2 * time.Second) // 模拟延迟
        fmt.Println("Notification sent successfully.")
    }(newBook) // 将 newBook 的值传入闭包，避免数据竞争

    // 立即返回成功，不等待邮件发送完成
    c.JSON(http.StatusAccepted, gin.H{
        "success": true,
        "message": "Book created. Notification will be sent shortly.",
        "data":    newBook,
    })
}

第四步：主程序入口与路由 (main.go)

package main

import (
    "log"
    "github.com/gin-gonic/gin"
)

func main() {
    // 使用默认的中间件（Logger和Recovery）
    r := gin.Default()

    // API版本分组，便于管理
    v1 := r.Group("/api/v1")
    {
        books := v1.Group("/books")
        {
            books.GET("", GetBooks)           // GET /api/v1/books
            books.GET("/:id", GetBook)        // GET /api/v1/books/:id
            books.POST("", CreateBook)        // POST /api/v1/books
            books.PUT("/:id", UpdateBook)     // PUT /api/v1/books/:id
            books.DELETE("/:id", DeleteBook)  // DELETE /api/v1/books/:id

            // 专门用于演示并发的路由
            books.POST("/async", SimulateAsyncTask) // POST /api/v1/books/async
        }
    }

    // 启动服务器，监听 8080 端口
    log.Println("Starting book API server on :8080")
    if err := r.Run(":8080"); err != nil {
        log.Fatalf("Failed to start server: %v", err)
    }
}

运行与测试：

go run .
# 使用 curl 或 Postman 测试以下请求：
# 获取所有图书
curl http://localhost:8080/api/v1/books

# 创建一本新书
curl -X POST http://localhost:8080/api/v1/books \
  -H "Content-Type: application/json" \
  -d '{"title": "Effective Go", "author": "Go Team", "price": 0.0}'

# 测试异步创建（注意观察控制台输出）
curl -X POST http://localhost:8080/api/v1/books/async \
  -H "Content-Type: application/json" \
  -d '{"title": "Async Book", "author": "Test", "price": 10.0}'

实践练习

基础修改：修改 UpdateBook 处理函数，使其支持 部分更新（PATCH）。即如果请求体中只提供了 title 字段，那么只更新书名，其他字段保持不变。（提示：在模型层增加一个 Patch 方法）。
添加新功能：为 API 添加分页功能。
- 修改 GetBooks 处理器，使其接受查询参数 ?page=1&pageSize=10。
- 在模型层实现对应的分页逻辑（对模拟的 bookStore 进行切片操作）。
- 返回的 JSON 应包含 total, page, pageSize 等元数据。
并发场景练习：设计一个 /api/v1/books/batch 的 POST 端点。该端点接收一个图书ID列表，并并发地查询这些图书的信息，最后将结果合并返回。要求：
- 使用 sync.WaitGroup 和 channel 来实现并发查询和结果收集。
- 考虑错误处理：如果某个ID不存在，返回的JSON中应明确标识。

常见错误

忘记并发安全：在多个 goroutine 中直接读写共享的全局变量（如 bookStore）而不加锁，会导致数据竞争。务必使用 sync.RWMutex 或其他同步机制。
过度使用 Goroutine：对于简单的、CPU 密集型或极快完成的操作，启动新的 goroutine 反而会增加开销（调度、内存）。只在需要并发 I/O 或后台任务时使用。
错误处理不完整：只检查了数据库操作的错误，但忽略了 ShouldBindJSON 返回的参数验证错误，或者没有为不同的错误返回合适的 HTTP 状态码（如 400, 404, 409）。
资源泄露：如果在 goroutine 中打开了数据库连接、文件等，必须确保它们被正确关闭，否则会导致连接池耗尽等问题。
路由冲突：/books/:id 和 /books/:name 这样的路由会冲突。Gin 会匹配第一个注册的路由，需要合理设计路由结构。

小结

本节课我们通过一个图书管理 API 的实战项目，将 Go 并发编程与 Web 开发紧密结合：

结构化：我们清晰地分离了路由（main.go）、处理逻辑（handler.go）和数据层（model.go），这是构建可维护项目的关键。
框架使用：利用 Gin 框架高效地定义了 RESTful 路由，并使用了其内置的绑定与验证功能。
并发实践：在 SimulateAsyncTask 函数中，演示了如何使用 goroutine 来处理后台任务，让 API 响应更快速，提升了用户体验。
健壮性：通过读写锁保证了内存数据库的并发安全，通过结构体验证和明确的错误响应提升了 API 的可靠性。
扩展性：项目结构清晰，很容易后续添加中间件（如 JWT 认证）、更换真实的数据库（如 MySQL, PostgreSQL）或集成到更大的系统中。

掌握这些模式后，你就具备了用 Go 开发生产级 RESTful API 服务的核心能力。下一步，我们将挑战更实时的场景——WebSocket 聊天室。

实战：REST API 服务