RESTful 接口 + 实际开发通用规范

文章目录

• 接口方法与参数使用速查表
• • [1. GET（查询、获取资源）](#1. GET（查询、获取资源）)
  • [2. POST（新增资源、提交表单）](#2. POST（新增资源、提交表单）)
  • [3. PUT（全量更新资源）](#3. PUT（全量更新资源）)
  • [4. PATCH（局部更新资源）](#4. PATCH（局部更新资源）)
  • [5. DELETE（删除资源）](#5. DELETE（删除资源）)
• 极简记忆版（面试/写代码直接背）
• 安全与规范小规则

下面这份是RESTful 接口 + 实际开发通用规范，直接照着用就行，清晰不踩坑。

接口方法与参数使用速查表

1. GET（查询、获取资源）

用途 ：获取列表、详情、搜索、分页
允许参数

• ✅ Path 参数（必须）
• ✅ Query 参数（筛选、分页、排序）
• ✅ Header 参数（token、版本）
• ❌ 禁止 Body 参数（很多服务器/框架不支持）
• ❌ 禁止敏感参数（密码、密钥）

示例

GET /users/123
GET /orders?status=paid&page=1&size=10

---

2. POST（新增资源、提交表单）

用途 ：创建、注册、登录、提交数据
允许参数

• ✅ Path 参数（可选）
• ✅ Query 参数（少量附加参数）
• ✅ Body 参数（主要数据放这里）
• ✅ Header 参数
• ✅ Form-data / x-www-form-urlencoded

示例

POST /users
Body: { name, phone, password }

---

3. PUT（全量更新资源）

用途 ：替换整个资源（覆盖更新）
允许参数

• ✅ Path 参数（必须，指定要更新的资源 ID）
• ✅ Query 参数（极少用）
• ✅ Body 参数（完整更新数据）
• ✅ Header

示例

PUT /users/123
Body: { name: "新名字", age: 25 }

---

4. PATCH（局部更新资源）

用途 ：只改某几个字段（如改昵称、改状态）
允许参数

• ✅ Path 参数（必须）
• ✅ Body 参数（只传要改的字段）
• ✅ Header

示例

PATCH /users/123
Body: { nickname: "新昵称" }

---

5. DELETE（删除资源）

用途 ：删除单个/批量资源
允许参数

• ✅ Path 参数（必须，删谁）
• ✅ Query 参数（可选附加条件）
• ✅ Header
• ❌ 尽量不要 Body（规范不推荐）

示例

DELETE /users/123

---

极简记忆版（面试/写代码直接背）

• GET：Path + Query
• POST：Path + Body（主）
• PUT：Path + Body（全量）
• PATCH：Path + Body（局部）
• DELETE：Path（为主）

---

安全与规范小规则

1. 密码、token、密钥 → 一律放 Header 或 Body，绝不放 URL
2. 文件上传 → 必须 POST + form-data
3. 列表查询 → 只用 Query
4. 操作某个具体资源 → 必须用 Path 带 ID
5. GET 永远不修改数据，只查询