4、RESTful API 设计原则：资源命名规范、HTTP 动词与状态码选择、版本控制策略

在微服务架构中，服务之间的通信主要依赖 RESTful API。一个设计良好的 API 边界，能显著降低服务耦合度，提升前后端协作效率。本章聚焦 RESTful API 设计的三大核心原则：资源命名规范、HTTP 动词与状态码选择、版本控制策略，并结合 Go + Gin 框架给出落地建议。

4.1 资源命名规范

RESTful API 的核心是“资源”（Resource），每个 URL 代表一个资源或资源集合。命名规范直接影响 API 的可读性和一致性。

// Gin 路由示例：资源命名规范
r := gin.Default()
v1 := r.Group("/api/v1")
{
    users := v1.Group("/users")
    {
        users.GET("", listUsers)                // GET /api/v1/users
        users.GET("/:id", getUser)              // GET /api/v1/users/123
        users.POST("", createUser)              // POST /api/v1/users
        users.PUT("/:id", updateUser)           // PUT /api/v1/users/123
        users.DELETE("/:id", deleteUser)        // DELETE /api/v1/users/123
        // 子资源：用户的订单
        users.GET("/:id/orders", listUserOrders) // GET /api/v1/users/123/orders
    }
}

4.2 HTTP 动词与状态码选择

HTTP 动词（Method）和状态码（Status Code）是 API 语义的重要组成部分。选择正确的动词和状态码，能让调用方无需查看文档即可理解操作结果。

4.2.1 动词映射

4.2.2 常用状态码

4.3 版本控制策略

随着业务迭代，API 接口可能发生不兼容变更。版本控制是保证向后兼容的关键手段。主流策略有三种：URL 路径版本、请求头版本、查询参数版本。

// Gin 实现 URL 路径版本控制
func main() {
    r := gin.Default()

    // v1 版本路由组
    v1 := r.Group("/api/v1")
    {
        v1.GET("/users", v1ListUsers)
        v1.POST("/users", v1CreateUser)
    }

    // v2 版本路由组（独立 handler）
    v2 := r.Group("/api/v2")
    {
        v2.GET("/users", v2ListUsers)
        v2.POST("/users", v2CreateUser)
    }

    r.Run(":8080")
}

4.4 综合示例：RESTful API 设计流程

下图展示了从资源定义到版本发布的完整设计流程，帮助你在 Gin 项目中建立清晰的 API 边界。

4.5 边界案例：微服务拆分中的 API 设计

在微服务拆分场景下，API 设计边界直接影响服务间的耦合度。以下是一个典型的用户服务与订单服务的 API 边界案例：