前端接口 | Hi Andre

type

Post

status

Published

date

Feb 12, 2026

slug

summary

什么是 RESTful API？

REST 的全称是 REpresentational State Transfer， “表现层状态转移”。

RE（Representational） 表现层，是指 资源（Resource） 的表现形式。

资源就是 你想要操作的数据对象。

比如用户、商品、文章，这些都是资源。用户列表是一个资源，某个具体的用户也是一个资源。

表现层是指资源呈现出来的具体格式，比如同一个用户资源，可以用 JSON 格式返回给客户端，也可以用 XML 格式返回，这就是不同的 “表现形式”。

S（State） 是指 “状态”。

鱼皮：比如你登录网站后，服务器会在内存中记住 “你是谁”，之后在网站上操作就不用再次登录了，这就是 有状态。

而 无状态（Stateless） 就是服务器不记录客户端的任何信息，每次请求都是独立的。

T（Transfer） 转移。转移是双向的：

1）当你用 GET 请求时，服务器把资源的状态（比如用户信息的 JSON 数据）转移给客户端。

2）当你用 POST/PUT 请求时，客户端把资源的新状态（比如新用户的信息）转移给服务器，从而改变服务器上资源的状态。

组合起来，REST（Representational State Transfer） 是一种 软件架构风格，让客户端和服务器通过统一的接口，以无状态的方式，互相传递资源的表现层数据（比如 JSON），来查询或者变更资源状态。

而 ful 是个后缀，就像 powerful（充满力量的）一样，表示 “充满...特性的”。

因此，RESTful API 是指符合 REST 架构风格的 API，也就是遵循 REST 原则设计出来的接口。

注意，它 不是协议、不是标准、不是强制规范，只是一种建议的设计风格。你可以遵循，也可以不遵循。

比如你要做个用户管理系统，对用户信息进行增删改查，用 RESTful 风格的 API 就长这样：

RESTful API 写法

构造一个完整的 RESTful API。分为两部分，客户端发送请求 和 服务端给出响应。

客户端请求

第一步：确定资源

资源用 URI（统一资源标识符）来表示。核心原则是：用名词来表示资源，不用动词。

具体来说，推荐用名词复数表示资源集合，比如 /users 表示用户列表、/products 表示商品列表。

如果要操作 具体某个资源，就加上 ID，比如 /users/123 表示 ID 为 123 的用户。

资源还 支持嵌套，比如 /users/123/orders 表示用户 123 的所有订单。

那还可以更深层级么？比如 /users/123/orders/456 表示用户 123 的订单 456。

第二步：选择动作

确定了资源后，接下来要选择动作，也就是你想怎么处理这个资源。

RESTful API 主要通过不同的 HTTP 方法来表示增删改查操作：

1）GET：查询资源

GET /users 查询所有用户

GET /users/123 查询 ID 为 123 的用户

2）POST：创建资源

POST /users 创建新用户

3）PUT：完整更新资源，需要提供资源的所有字段，多次执行结果相同（幂等性）

PUT /users/123 完整更新用户 123

4）PATCH：部分更新资源，通常用于更精细的操作

PATCH /users/123 只更新用户 123 的某些字段

5）DELETE：删除资源

DELETE /users/123 删除用户 123

到这里，一个基本的 RESTful API 请求就构造完成了。

第三步：添加查询条件（可选）

有时候我们需要更精确地筛选数据，这时候可以加查询参数，比如：

分页：/users?page=2&limit=10 查询第 2 页，每页 10 条用户数据

过滤：/users?gender=male&age=25 查询性别为男、年龄 25 的用户

排序：/users?sort=created_at&order=desc 按创建时间倒序排列用户

这查询参数跟 RESTful 有啥关系？正常的请求不都是这么写吗？

查询参数本身不是 RESTful 特有的。但 RESTful 风格强调 把筛选、排序、分页这些操作，都通过 URL 参数来表达：

而不是在请求体里传一堆复杂的 JSON 对象：

这样一来，URL 更清晰，而且浏览器、CDN、代理服务器都能直接根据 URL 来缓存响应结果。比如 /users?page=1 和 /users?page=2 是两个不同的 URL，可以分别缓存。但如果把参数放在请求体里，URL 都是 /users，缓存就没法区分了。

第四步：版本控制（可选）

随着业务发展，接口可能需要升级。为了不影响老用户，可以在 URI 中标明版本：

/v1/users 第一版用户接口

/v2/users 第二版用户接口

这样，老用户继续用 v1，新用户用 v2，互不影响。

第五步：保持无状态

此外，还记得我们前面讲 REST 里的 ST（State Transfer） 吗？

RESTful 的核心原则之一是 无状态（Stateless），客户端每次请求必须包含所有必要信息，服务器不记录客户端状态。

比如用户登录后，不是让服务器记住 “你已经登录了”，而是每次请求都要带上身份凭证（Token），像这样：

这么做的好处是，服务器不用记录谁登录了、谁没登录，每个请求都是独立的。这样一来，你想加多少台服务器都行，任何一台都能处理请求，轻松实现负载均衡和横向扩展。

怪不得我调用 AI 大模型 API 的时候，就要传这个 Token！

服务端响应

讲完客户端请求，再来看服务器收到请求后，该怎么响应？

主要注意 2 点：

1、统一响应格式

目前大多数 RESTful API 基本都用 JSON 格式，因为轻量、容易解析。

但这并不是强制的，也可以用 XML、HTML 等格式。

2、返回合适的 HTTP 状态码

响应要带上合适的状态码，让客户端一眼看懂发生了什么。

HTTP 状态码有很多，大体可以分为 5 类：

1xx 系列：信息提示（用得少，了解即可）

2xx 系列：成功

3xx 系列：重定向

4xx 系列：客户端错误

5xx 系列：服务器错误

恍然大悟：懂了，以后前端看到 500，就知道是我后端的锅；看到 400，就知道是她自己传参传错了。

下面哪个是标准的 RESTful API？

A. GET /getUsers

B. GET /user/list

C. POST /users/query

D. GET /users/delete/123

你开心地说：肯定是 C 啊！

错，4 个全都不标准！

A 用了动词 getUsers

B 用了单数 user 和动词 list

C 用 POST 查询，还带了动词 query

D 用 GET 删除，还带了动词 delete

RESTful 不能用动词，但有些操作不是标准的增删改查啊，比如用户要支付订单，该怎么设计接口呢？是要用 POST /orders/123/pay？

但 pay 是动词。更标准的设计是把 “支付” 行为看作创建一个支付记录，用名词而不是动词。

比如这个请求，表示为订单 123 创建一笔支付记录。

RESTful 的六大约束

RESTful 其实有 6 个约束条件：

Client-Server（客户端-服务器分离）：前后端各干各的活，前端负责展示，后端负责数据处理，互不干扰。

Stateless（无状态）：每次请求都是独立的，服务器不保存客户端的会话信息，所有必要信息都在请求中携带。

Cacheable（可缓存）：服务器的响应可以被标记为可缓存或不可缓存，客户端可以重用缓存数据，减少服务器压力，提升性能。

Layered System（分层系统）：客户端不需要知道直接连的是服务器还是中间层，系统可以灵活地加代理、网关、负载均衡器等。

Uniform Interface（统一接口）：所有资源都通过统一的接口访问，降低理解成本，提高可维护性。

Code-On-Demand（按需代码）：可选项，服务器可以返回可执行代码（比如 JavaScript）给客户端执行，但实际工作中很少用。

这么多约束，我必须全遵守吗？

可以不用，RESTful 只是一种 API 的 建议风格。在实际工作中，很少有 API 能完美符合所有约束，大家可以灵活调整，甚至什么接口都用 POST + 动词 一把梭。只要团队达成一致、用得舒服就行。

就像刚才那个支付订单的例子，POST /orders/123/payments 虽然符合 RESTful 规范，但有同学会觉得 POST /orders/123/pay 更直观易懂，也没问题。

不过我建议先养成遵循 RESTful 的好习惯，等积累了经验，再根据实际情况灵活调整。

怎么快速实现 RESTful API？

1、使用开发框架

几乎所有主流开发框架都支持 RESTful API 的开发，它们能帮你自动处理很多细节，比如：

Java 的 Spring Boot：通过 @GetMapping("/users")、@PostMapping("/users") 等注解，你只需要写一行代码就能定义符合 RESTful 风格的路由。框架会自动把对象转成 JSON、设置正确的 HTTP 状态码，你都不用操心。

Python 的 Django REST Framework：你只需要定义一个数据模型（比如 User 类），框架就能自动生成 GET /users、POST /users、PUT /users/123、DELETE /users/123 这一整套 RESTful 接口，大幅减少代码量。

Go 的 Gin ：专门为 RESTful API 设计，语法非常简洁。比如 router.GET("/users/:id", getUser) 就能绑定一个 GET 请求，自动从 URL 中提取 ID 参数，还能通过路由分组把 /api/v1/users 和 /api/v2/users 轻松分开管理。

这些框架虽然不强制你遵循 RESTful，但用它们的特性，开发起来既轻松又规范，帮你省掉大量重复代码。