用途:在设计 HTTP API 端点、不确定该用哪个 HTTP 方法、或发现有人用 POST 做读取时使用。核心规则是 URL 用名词(资源),不用动词;GET 读取、POST 创建、PUT/PATCH 更新、DELETE 删除;过滤、分页、排序通过查询参数完成。
主要能力:给出 RESTful 端点写法,如 GET /users 列表、POST /users 创建、GET /users/:id 获取单个、PUT /users/:id 整体替换、PATCH /users/:id 部分更新、DELETE /users/:id 删除;支持嵌套资源如 GET /users/:id/orders;过滤如 GET /orders?status=pending&userId=123;分页如 GET /orders?page=2&limit=20 或 cursor 方式;排序如 GET /products?sort=price:asc;不适合 CRUD 的动作可用子资源,如 POST /orders/:id/cancel。
方法语义:GET 读取,安全且幂等;POST 创建,非安全非幂等;PUT 整体替换,幂等;PATCH 部分更新,幂等;DELETE 删除,幂等。
限制与例外:禁止用 POST 做读取,禁止在 URL 中放动词。若查询过于复杂,可接受 POST /search 作为例外;GET 请求体属非标准做法,应改用查询参数。对已有用 POST 读取的旧接口,新端点应遵循约定并逐步迁移。