3. RESTful API 设计原则

RESTful API 是微服务与前后端分离架构中最主流的接口契约风格。本章围绕资源命名、HTTP 动词、状态码与版本控制四个核心维度，给出可直接落地的设计规范与 Go 实现建议。

3.1 资源命名规范

资源是 REST 的核心抽象，命名必须遵循统一、可读、可预测的原则。

3.2 HTTP 动词使用

每个动词对应一种标准操作语义，不可混用。

// Go 路由示例 — 动词与路径分离
r.GET("/orders", handler.ListOrders)
r.POST("/orders", handler.CreateOrder)
r.GET("/orders/{oid}", handler.GetOrder)
r.PUT("/orders/{oid}", handler.ReplaceOrder)
r.PATCH("/orders/{oid}", handler.PatchOrder)
r.DELETE("/orders/{oid}", handler.DeleteOrder)

3.3 状态码选择

状态码是响应契约的第一行语义，客户端依赖它做分支处理。选择错误会导致调用方逻辑混乱。

// 状态码映射函数
func httpStatusFromError(err error) int {
    switch {
    case errors.Is(err, ErrNotFound):
        return http.StatusNotFound
    case errors.Is(err, ErrConflict):
        return http.StatusConflict
    case errors.Is(err, ErrValidation):
        return http.StatusUnprocessableEntity
    default:
        return http.StatusInternalServerError
    }
}

3.4 版本控制策略

API 版本控制是向后兼容的基石。主流策略有三种，各有适用场景。

// 版本中间件示例
func VersionMiddleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        version := chi.URLParam(r, "version")
        ctx := context.WithValue(r.Context(), "apiVersion", version)
        next.ServeHTTP(w, r.WithContext(ctx))
    })
}

3.5 综合设计检查清单

在发布接口契约前，对照以下清单逐项确认。

• 资源命名：是否全部使用名词复数、小写连字符、层级路径？
• 动词语义：GET 是否只读？POST 是否非幂等？PUT 是否全量？PATCH 是否部分？
• 状态码：成功是否返回 200/201/204？客户端错误是否返回 4xx？服务端错误是否返回 5xx？
• 版本控制：是否明确版本策略？是否在路由层统一处理？是否在文档中标注废弃版本？
• 错误体：是否包含 code、message、details 字段？