2. REST API 基础回顾：RESTful设计原则、HTTP方法语义、资源与端点设计

在深入分页与过滤边界设计之前，必须重新校准对REST API基础的理解。许多边界问题（如过滤参数命名混乱、分页状态管理不当）的根源，恰恰是对RESTful原则的偏离。本节将系统回顾REST架构的核心约束、HTTP方法的正确语义，以及资源与端点的设计范式。

2.1 RESTful 六大架构约束

REST（Representational State Transfer）并非协议，而是一组架构约束。满足这些约束的接口才被称为RESTful。以下是六大约束及其在API设计中的体现：

2.2 HTTP 方法语义与幂等性

每个HTTP方法在REST中都有明确的语义。错误的方法选择会导致接口语义混乱，进而影响客户端对缓存、重试、错误处理的行为判断。

2.3 资源与端点设计范式

资源是REST的核心抽象。端点设计应围绕“名词（资源）”而非“动词（动作）”展开。以下是资源设计的基本原则：

• 使用名词复数形式： /users 而非 /getUser 或 /user。
• 层级关系通过路径表达： /users/{userId}/orders 表示用户下的订单集合。
• 避免过深的嵌套： 超过三级嵌套通常表明设计需要重新审视，可考虑使用查询参数扁平化。
• 动作通过HTTP方法表达： 激活用户应使用 PATCH /users/{userId} 并传递 { "status": "active" }，而非 POST /users/{userId}/activate。

以下SVG图展示了标准REST端点设计与反模式设计的对比：

2.4 查询参数与过滤语义

过滤、排序、分页等操作属于“检索”范畴，应通过GET方法的查询参数表达。以下是标准的查询参数设计模式：

// 标准过滤端点设计
GET /users?status=active&role=admin
GET /users?age_gte=18&age_lte=60
GET /users?search=john&fields=id,name,email

// 排序
GET /users?sort=created_at:desc,name:asc

// 分页
GET /users?page=2&limit=20
GET /users?cursor=eyJpZCI6MTAwfQ==&limit=20

2.5 响应结构与HATEOAS

REST响应应包含自描述信息，使客户端能够通过响应中的链接发现后续操作。对于分页响应，HATEOAS（超媒体作为应用状态引擎）尤为重要：

{
  "data": [
    { "id": 1, "name": "Alice", "email": "alice@example.com" },
    { "id": 2, "name": "Bob", "email": "bob@example.com" }
  ],
  "_links": {
    "self": { "href": "/users?page=1&limit=2" },
    "next": { "href": "/users?page=2&limit=2" },
    "prev": { "href": null },
    "first": { "href": "/users?page=1&limit=2" },
    "last": { "href": "/users?page=5&limit=2" }
  },
  "meta": {
    "total_items": 10,
    "total_pages": 5,
    "current_page": 1
  }
}

以下SVG图展示了REST请求-响应流程中，资源标识、查询参数与HATEOAS链接的关系：

2.6 状态码的正确使用

HTTP状态码是REST响应语义的重要组成部分。在分页与过滤场景中，以下状态码最为常用：