2、资源与URI设计：资源的概念、URI的命名规范（使用名词、小写、连字符）、避免动词、版本控制策略（URL路径 vs Header）

2.1 资源（Resource）的核心概念

在RESTful架构中，资源是API操作的核心对象。资源可以是一个实体（如用户、订单）、一个集合（如用户列表）、或者一个过程（如计算、转换）。每个资源必须有一个唯一的标识符，即URI（Uniform Resource Identifier）。

资源设计的关键原则：

• 抽象性：资源是业务概念的抽象，而非数据库表的直接映射。
• 唯一性：每个资源通过URI全局唯一标识。
• 可寻址性：客户端通过URI即可定位并操作资源。
• 无状态性：服务器不保存客户端状态，每次请求包含所有必要信息。

2.2 URI命名规范

URI是资源的地址，其命名直接影响API的可读性、一致性和可维护性。以下是业界公认的规范：

2.3 避免动词：让HTTP方法说话

RESTful API的核心原则之一是利用HTTP标准方法表达操作语义，而非在URI中嵌入动词。这样设计的好处：

• 统一接口：所有资源使用相同的HTTP方法集合，降低学习成本。
• 可缓存性：GET、PUT、DELETE等方法的语义明确，便于代理和缓存服务器处理。
• 幂等性：PUT、DELETE是幂等的，POST不是，URI设计不应破坏这些语义。

2.4 版本控制策略：URL路径 vs Header

API版本控制是保证向后兼容性的关键手段。业界主要有两种策略：URL路径版本控制 和 Header版本控制。以下是详细对比：

2.5 资源与URI设计总览图

下图展示了资源、URI命名规范、HTTP方法与版本控制之间的整体关系：

2.6 Go代码示例：版本化资源路由

以下是用Go的 gin 框架实现URL路径版本控制的示例：

package main

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

func main() {
    r := gin.Default()

    // v1 版本的用户接口
    v1 := r.Group("/v1")
    {
        v1.GET("/users", listUsersV1)
        v1.GET("/users/:id", getUserV1)
        v1.POST("/users", createUserV1)
        v1.PUT("/users/:id", updateUserV1)
        v1.DELETE("/users/:id", deleteUserV1)
    }

    // v2 版本的用户接口（可能返回更多字段）
    v2 := r.Group("/v2")
    {
        v2.GET("/users", listUsersV2)
        v2.GET("/users/:id", getUserV2)
        v2.POST("/users", createUserV2)
        v2.PUT("/users/:id", updateUserV2)
        v2.DELETE("/users/:id", deleteUserV2)
    }

    r.Run(":8080")
}

func listUsersV1(c *gin.Context) {
    c.JSON(200, gin.H{"version": "v1", "users": []string{"alice", "bob"}})
}

func listUsersV2(c *gin.Context) {
    c.JSON(200, gin.H{"version": "v2", "users": []string{"alice", "bob", "charlie"}})
}
// 其他处理器实现略...

2.7 资源层级与URI设计示例

以下表格展示了常见业务场景下的资源层级与URI设计：