3、HTTP方法与CRUD映射：GET（查询）、POST（创建）、PUT（全量更新）、PATCH（部分更新）、DELETE（删除）的语义与幂等性

RESTful 架构的核心是将业务操作抽象为对资源的统一操作，而 HTTP 协议提供的方法（Method）天然对应了数据库的 CRUD（Create、Read、Update、Delete）语义。理解每个方法的语义、副作用以及幂等性，是设计稳定、可预测 API 的基础。

3.1 HTTP 方法与 CRUD 的标准映射

下表展示了五种核心 HTTP 方法与 CRUD 操作的对应关系，以及它们在资源集合（Collection）和单个资源（Resource）上的典型 URL 模式。

3.2 幂等性：API 可靠性的基石

幂等性（Idempotency）是指：无论请求执行一次还是多次，对服务器资源产生的最终状态都是相同的。这是分布式系统中保证数据一致性的关键特性。

• GET：幂等。多次查询同一资源，返回结果应一致（不考虑并发修改）。
• PUT：幂等。多次执行相同的全量更新，资源最终状态与最后一次请求体一致。
• DELETE：幂等。第一次删除后资源已不存在，后续删除请求应返回相同状态（如 404 或 204）。
• POST：非幂等。多次创建会生成多个不同的资源（如不同的 ID）。
• PATCH：非幂等（默认）。如果 PATCH 操作是增量修改（如 {"count": "count + 1"}），多次执行会导致结果不同。

3.3 方法语义与状态码的配合

每个 HTTP 方法都有其推荐的响应状态码，这构成了 API 的“语义契约”。

3.4 方法选择与幂等性决策流程

在实际 API 设计中，选择哪个方法不仅取决于操作类型，还取决于对幂等性的要求。下面的流程图可以帮助你快速决策。

3.5 Go 代码实现示例

以下代码展示了在 Gin 框架中如何根据方法语义实现对应的处理函数，并正确处理幂等性。

package main

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

type User struct {
    ID   int    `json:"id"`
    Name string `json:"name"`
    Age  int    `json:"age"`
}

var users = []User{{ID: 1, Name: "Alice", Age: 30}}

// GET /users/:id — 幂等查询
func getUser(c *gin.Context) {
    id := c.Param("id")
    for _, u := range users {
        if fmt.Sprintf("%d", u.ID) == id {
            c.JSON(http.StatusOK, u)
            return
        }
    }
    c.JSON(http.StatusNotFound, gin.H{"error": "user not found"})
}

// POST /users — 非幂等创建
func createUser(c *gin.Context) {
    var newUser User
    if err := c.ShouldBindJSON(&newUser); err != nil {
        c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
        return
    }
    newUser.ID = len(users) + 1
    users = append(users, newUser)
    // 返回 201 Created 和 Location 头
    c.Header("Location", "/users/"+fmt.Sprintf("%d", newUser.ID))
    c.JSON(http.StatusCreated, newUser)
}

// PUT /users/:id — 幂等全量更新
func updateUser(c *gin.Context) {
    id := c.Param("id")
    var updatedUser User
    if err := c.ShouldBindJSON(&updatedUser); err != nil {
        c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
        return
    }
    for i, u := range users {
        if fmt.Sprintf("%d", u.ID) == id {
            updatedUser.ID = u.ID // 保持 ID 不变
            users[i] = updatedUser
            c.JSON(http.StatusOK, updatedUser)
            return
        }
    }
    c.JSON(http.StatusNotFound, gin.H{"error": "user not found"})
}

// DELETE /users/:id — 幂等删除
func deleteUser(c *gin.Context) {
    id := c.Param("id")
    for i, u := range users {
        if fmt.Sprintf("%d", u.ID) == id {
            users = append(users[:i], users[i+1:]...)
            c.JSON(http.StatusNoContent, nil)
            return
        }
    }
    // 资源已不存在，仍返回 204（幂等）
    c.JSON(http.StatusNoContent, nil)
}

func main() {
    r := gin.Default()
    r.GET("/users/:id", getUser)
    r.POST("/users", createUser)
    r.PUT("/users/:id", updateUser)
    r.DELETE("/users/:id", deleteUser)
    r.Run(":8080")
}

3.6 方法语义对比总结

为了帮助你在设计 API 时快速查阅，下表总结了各方法的核心特性。