RESTful API 介绍

🧩 一、REST 概念简介

REST（Representational State Transfer） 是一种 软件架构风格，由 Roy Fielding 在 2000 年的博士论文中提出。 它并不是一种协议或标准，而是一组设计原则，用于构建 可扩展、易维护、结构清晰 的 Web API。

基于 REST 设计原则开发的 API，我们称之为 RESTful API。

🌍 二、REST 的核心思想

“一切皆资源（Everything is a Resource）”

在 REST 中，服务器上所有可以被操作的对象都被视为资源，每个资源由一个 唯一的 URI（统一资源标识符）表示。

例如：

资源	URI 示例
所有用户	/users
某个用户	/users/123
某个用户的文章	/users/123/posts

🚦 三、HTTP 方法与操作对应关系

RESTful API 使用 HTTP 的标准动词来描述对资源的操作：

HTTP 方法	语义	常用场景
GET	获取资源	获取单个或多个对象
POST	创建资源	新增一条数据
PUT	更新资源（整体替换）	覆盖式更新
PATCH	更新资源（部分更新）	修改部分字段
DELETE	删除资源	删除对象

📘 示例：

GET     /users           → 获取所有用户
GET     /users/123       → 获取ID为123的用户
POST    /users           → 创建新用户
PUT     /users/123       → 更新ID为123的用户（全量）
PATCH   /users/123       → 更新ID为123的用户（部分）
DELETE  /users/123       → 删除ID为123的用户

🧱 四、RESTful API 设计规范

1. 资源路径命名规则

• 使用名词而不是动词 ✅ /users ❌ /getUsers
• 使用复数形式表示集合 ✅ /books ❌ /book
• 使用层级结构表示资源关系 ✅ /users/123/posts/456/comments

2. 请求与响应格式

建议使用 JSON 作为主要格式：

{
  "id": 123,
  "name": "Alice",
  "email": "alice@example.com"
}

响应头中应指定：

Content-Type: application/json

3. 状态码规范化

状态码	含义	示例
200 OK	请求成功	成功返回数据
201 Created	创建成功	POST 新建资源成功
204 No Content	删除或更新成功，无返回体	DELETE 成功
400 Bad Request	请求参数错误	缺少必填字段
401 Unauthorized	未认证	需要登录
403 Forbidden	无权限	拒绝访问
404 Not Found	资源不存在	ID 不存在
500 Internal Server Error	服务器错误	后端异常

4. 过滤、排序与分页

使用 查询参数 处理：

GET /users?role=admin&status=active
GET /posts?sort=-created_at&page=2&limit=10

5. 超媒体（HATEOAS）

响应中包含可操作的链接，让客户端根据链接继续访问资源：

{
  "id": 1,
  "name": "Alice",
  "links": [
    {"rel": "self", "href": "/users/1"},
    {"rel": "posts", "href": "/users/1/posts"}
  ]
}

⚙️ 六、一个完整示例（以用户系统为例）

请求：

POST /users
Content-Type: application/json

{
  "name": "Alice",
  "email": "alice@example.com"
}

响应：

201 Created
Location: /users/123
Content-Type: application/json

{
  "id": 123,
  "name": "Alice",
  "email": "alice@example.com"
}

🔒 七、安全与认证

RESTful API 常使用以下认证方式：

• Token 认证（JWT）
• OAuth 2.0
• API Key
• HTTPS 加密传输

示例：

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6...

🧭 八、RESTful 与传统接口的区别

对比项	RESTful API	传统接口
URL 风格	以资源为中心	以动作为中心
方法	使用标准 HTTP 动词	一般只用 POST
状态码	有语义的响应码	通常用200+自定义code
可读性	语义清晰	接口复杂
维护性	高	低

🧩 九、延伸：REST 与 GraphQL、gRPC 对比

特性	REST	GraphQL	gRPC
传输格式	JSON	JSON	Protobuf
调用方式	HTTP	HTTP	HTTP/2
优势	简单通用	查询灵活	高性能、类型安全
缺点	请求次数多	复杂	学习成本高