REST API 接口设计

RESTful API 是什么？一文看懂 REST API 设计思想

RESTful API（Representational State Transfer API，表述性状态转移接口）是一种基于 REST 架构风格 设计的 Web API 规范，用于让不同的软件系统之间通过网络进行数据交互。

在现代互联网应用中，前端、后端、移动端、第三方服务之间经常需要交换数据，而 RESTful API 提供了一套简单、统一、可扩展的通信方式。

一句话理解：

RESTful API 就像应用之间交流的“标准语言”，通过 HTTP 请求让不同系统能够获取、创建、修改和删除数据。

基础信息

什么是 RESTful API？

通俗解释

在软件开发中，不同系统之间需要互相传递信息。

例如：

• 前端页面需要获取用户信息
• 手机 App 需要查询订单
• 第三方平台需要调用支付服务

这些通信通常通过 API（Application Programming Interface，应用程序接口）完成。

RESTful API 就是一种设计 API 的方式，它规定了：

• 如何定义接口地址
• 如何使用 HTTP 方法
• 如何表示数据
• 如何组织资源

例如：

一个电商系统中有用户资源：

获取用户：

GET /users/1001
复制

创建用户：

POST /users
复制

修改用户：

PUT /users/1001
复制

删除用户：

DELETE /users/1001
复制

通过不同 HTTP 方法表示不同操作。

REST 是什么？

REST 全称：

Representational State Transfer（表述性状态转移）

它由计算机科学家 Roy Fielding 在 2000 年提出。

REST 不是一种编程语言，也不是具体协议，而是一种软件架构设计思想。

它主要强调：

• 资源
• 统一接口
• 无状态通信
• 可缓存
• 分层架构

为什么需要 RESTful API？

传统接口设计的问题

早期 API 常采用动作式命名：

例如：

查询用户：

/getUser?id=1001
复制

创建用户：

/createUser
复制

删除用户：

/deleteUser?id=1001
复制

问题：

• URL 中包含操作行为
• 接口数量容易增加
• 规范不统一
• 难以维护

RESTful API 的解决方式

REST 将重点从：

“执行什么操作”

转换为：

“操作什么资源”

例如：

用户是一种资源：

/users
复制

操作通过 HTTP 方法表达：

这样接口更加统一。

RESTful API 是如何工作的？

基本流程：

客户端
  ↓
HTTP请求
  ↓
RESTful API接口
  ↓
服务器处理业务逻辑
  ↓
访问数据库
  ↓
返回数据
  ↓
客户端展示结果
复制

第一步：客户端发送请求

客户端可能是：

• 浏览器
• 手机 App
• 前端 React/Vue 应用
• 其他服务器

例如：

请求用户信息：

GET /api/users/1001
复制

第二步：服务器解析请求

服务器根据：

• 请求方法
• URL路径
• 参数
• 请求头

判断需要执行什么操作。

例如：

GET /users/1001
复制

表示：

获取 ID 为 1001 的用户。

第三步：处理业务逻辑

服务器：

1. 查询数据库
2. 验证权限
3. 处理数据

例如：

查询：

SELECT * FROM user WHERE id=1001;
复制

第四步：返回响应

服务器返回 JSON 数据：

{
  "id":1001,
  "name":"张三",
  "email":"zhangsan@example.com"
}
复制

客户端接收后展示。

RESTful API 的核心特点

1. 资源（Resource）

REST 的核心思想：

一切皆资源。

资源可以是：

• 用户
• 商品
• 订单
• 文件
• 文章

例如：

用户资源：

/users
复制

文章资源：

/articles
复制

订单资源：

/orders
复制

2. 使用 HTTP 方法表达操作

REST 不推荐：

/getUser
/createOrder
/deleteProduct
复制

而推荐：

GET /users

POST /orders

DELETE /products/10
复制

常见 HTTP 方法：

3. 无状态（Stateless）

REST 要求：

每一次请求都应该包含完成请求所需的信息。

服务器不会保存客户端状态。

例如：

请求：

GET /orders/1001
Authorization: Bearer token
复制

每次请求都携带身份信息。

优点：

• 容易扩展
• 支持负载均衡
• 服务更加稳定

4. 使用统一数据格式

REST API 常使用：JSON

例如：

{
 "username":"admin",
 "role":"user"
}
复制

相比 XML：

• 更简单
• 更适合 Web
• 前端解析方便

RESTful API 设计规范

1. URL 使用名词

推荐：

/users
/products
/orders
复制

不推荐：

/getUsers
/createProduct
/deleteOrder
复制

2. 使用复数形式

推荐：

/users
/articles
/products
复制

避免：

/user
/article
复制

保持统一。

3. 使用 HTTP 状态码

服务器通过状态码表示结果。

常见状态码：

4. 使用版本控制

大型系统通常：

/api/v1/users
复制

未来升级：

/api/v2/users
复制

避免旧客户端受到影响。

RESTful API 示例

假设开发一个博客系统。

资源：

文章 Article
复制

查询文章列表

请求：

GET /articles
复制

返回：

[
 {
  "id":1,
  "title":"REST API介绍"
 }
]
复制

创建文章

请求：

POST /articles
复制

参数：

{
"title":"我的第一篇文章",
"content":"内容"
}
复制

修改文章

请求：

PUT /articles/1
复制

删除文章

请求：

DELETE /articles/1
复制

RESTful API 与相关概念区别

RESTful API 与 GraphQL 的区别

实际应用场景

Web应用

前端 React/Vue：

请求后端接口：

GET /api/user/profile
复制

获取用户信息。

移动应用

手机 App：

调用：

GET /api/products
复制

获取商品列表。

企业系统

企业内部：

• ERP
• CRM
• OA

通过 REST API 连接不同系统。

AI 应用

现代 AI 系统大量使用 REST API。

例如：

前端聊天界面：

↓

调用 AI 服务 API

↓

返回模型生成结果

流程：

用户输入
↓
REST API
↓
AI模型服务
↓
返回回答
复制

举个例子

场景

开发一个 AI 学习平台，需要展示用户课程记录。

前端请求

GET /api/users/1001/courses
复制

后端处理

1. 验证用户身份
2. 查询数据库
3. 返回课程数据

返回

{
"user":"1001",
"courses":[
 {
  "name":"Prompt基础",
  "progress":80
 }
]
}
复制

最终效果

前端无需知道数据库结构，只需要调用 API 获取数据。

RESTful API 的优势

优势

• 设计简单
• 标准统一
• 易于理解
• 跨平台支持
• 方便前后端分离
• 易于扩展

RESTful API 的局限

局限

• 数据获取灵活性有限
• 可能出现接口数量过多
• 不适合复杂查询场景
• 对实时通信支持较弱

例如：

聊天系统通常更适合：

• WebSocket
• SSE

常见问题 FAQ

RESTful API 和 API 有什么区别？

API 是一个更大的概念，而 RESTful API 是 API 的一种设计方式。

RESTful API 一定使用 HTTP 吗？

大多数 RESTful API 基于 HTTP，但 REST 本身是一种架构思想。

前端开发需要学习 RESTful API 吗？

需要。

现代前端开发大量依赖 API 与后端通信。

RESTful API 现在还流行吗？

仍然非常流行。

大量 Web 应用、移动应用和企业系统仍然使用 REST API。

RESTful API 和后端语言有关吗？

无关。

Java、Python、Go、Node.js 等语言都可以开发 RESTful API。

学习路线

如果想学习 RESTful API，可以按照：

HTTP基础
↓
JSON数据格式
↓
REST设计规范
↓
后端接口开发
↓
身份认证 JWT
↓
接口安全
↓
微服务API设计
复制

实践推荐

学习 RESTful API 后，可以尝试：

初级

• 使用 Postman 调试接口
• 调用公开 API
• 编写简单 CRUD 接口

进阶

• 使用 Spring Boot 开发 REST API
• 使用 JWT 实现接口认证
• 设计企业级 API

总结

RESTful API 是现代 Web 应用中最常见的接口设计方式之一，它通过资源、HTTP 方法和统一的数据格式，实现不同系统之间的通信。

它的核心思想是：

用资源表示业务对象，用 HTTP 方法表示操作。

理解 RESTful API，是学习前后端分离、微服务架构、移动开发以及 AI 应用开发的重要基础。

在实际开发中，RESTful API 经常与数据库、身份认证、微服务和 AI 服务结合使用，是现代软件系统的重要组成部分。

知识地图

Web开发基础
├── HTTP协议
│
├── RESTful API
│   │
│   ├── HTTP Method
│   ├── JSON
│   ├── Status Code
│   ├── API Version
│   └── Authentication
│
├── GraphQL
│
├── RPC
│
└── 微服务架构
复制

相关知识

• HTTP协议
• JSON
• API接口设计
• WebSocket
• GraphQL
• RPC
• JWT认证
• OAuth2
• 微服务架构
• Spring Boot REST API

延伸阅读

官方资料

• REST Architectural Style
• HTTP Semantics Documentation

技术资料

• OpenAPI Specification
• API Design Guidelines

开源项目

• Spring Boot
• FastAPI
• Express.js