浅谈 RESTful API

最新推荐文章于 2025-10-11 14:56:27 发布

原创最新推荐文章于 2025-10-11 14:56:27 发布 · 244 阅读

0 ·

CC 4.0 BY-SA版权

文章标签：

#restful #后端

RESTfulAPI是一种API设计风格，强调使用HTTP方法（GET,POST,PUT,DELETE）操作资源。例如，GET用于获取资源，POST用于创建，PUT用于更新，DELETE用于删除。登录操作在RESTful中通常表现为POSTapi/sessions（登录）和DELETEapi/sessions（登出）。这种风格提供了简洁的URL结构和明确的操作指示，但可能不适合处理需要多资源操作的场景。

引导篇（RESTful API 是什么？）

REST 全称是 Representational State Transfer，中文意思是表现层（编者注：通常译为表征）状态转化，它首次出现在 2000年 Roy Fielding的博士论文中。Roy Fielding在论文中提到："我这篇文章的写作目的，就是想在符合架构原理的前提下，理解和评估以网络为基础的应用软件的架构设计，得到一个功能强、性能好、适宜通信的架构。REST 指的是一组架构约束条件和原则。"

REST 本身并没有创造新的技术、组件或服务，而隐藏在 RESTful 背后的理念就是使用 Web 的现有特征和能力，更好地使用现有 Web 标准中的一些准则和约束。虽然 REST 本身受 Web 技术的影响很深，但是理论上 REST 架构风格并不是绑定在 HTTP上，只不过目前 HTTP 是唯一与 REST 相关的实例。

简单来说，RESTful 是一种 API 风格，重点！！是风格，不是什么规范。

场景篇

上面讲了这么多关于 RESTful 的知识。

下面我们来模拟使用 RESTful API 风格来定义几个对文章操作的 API。

GET

获取文章详情

# 接口
api/articles/:id

# 状态码 200

# 返回详情
{
 "id": "xxx",
 "content": "xxx",
 "author": "严家辉",
 "createTime": "2023-03-02 23:37:20",
}

获取文章列表数据

# 接口
api/articles

# 状态码 200

# 返回列表数据和总数
{
  "items": [
    {
      "id": "xxx",
      "content": "xxx",
      "author": "严家辉",
      "createTime": "2023-03-02 23:37:20",
    }
  ],
  "total": 100
}

POST

新增文章

# 接口
api/articles

# 状态码 201

# 返回新增数据的详情
{
 "id": "xxx",
 "content": "xxx",
 "author": "严家辉",
 "createTime": "2023-03-02 23:37:20",
}

PUT

更新文章内容

# 接口
api/articles/:id

# 状态码 200

# 返回更新后的详情
{
 "id": "xxx",
 "content": "xxx",
 "author": "严家辉",
 "createTime": "2023-03-02 23:37:20",
}

DELETE

删除一篇文章

# 接口
api/articles/:id

# 状态码 204

# No content

合起来看下

方法	API	用途
GET	api/articles/:id	获取文章详情
GET	api/articles	获取文章列表
POST	api/articles	新增文章
PUT	api/articles/:id	更新文章
DELETE	api/articles/:id	删除文章

RESTful 的核心思想就是，客户端发出的数据操作指令都是动词 + 宾语的结构。

用一句话来描述RESTful API 就是URL定位资源，用HTTP动词（GET,POST,PUT,DELETE)描述操作。

看URL 就知道要什么

看HTTP Method 就知道干什么

看HTTP Status Code 就知道结果如何

引知乎高赞回答 - 徐磊

使用 RESTful API 遇到的问题

可以先看看对用户的其他操作吧

方法	API	用途
GET	api/users/:id	获取用户信息
GET	api/users	获取用户列表
POST	api/users	新增用户
PUT	api/users/:id	更新用户信息
DELETE	api/users/:id	更新用户信息

看着好像没啥问题。

上面我们都在操作 users 资源，那用户的登录怎么使用 RESTful API ？

但是 HTTP Method 里面压根没有一个叫登录的动词让我们直接操作 users 的登录。怎么办呢？

难道是使用 api/login?

当然不行 login 已经是动词了，按照 RESTful API 的风格， URL 只能是用来表示资源主体 的名词？且推荐使用复数。

其实登录我们也是操作一个资源，这个资源就是 session。

所以我们可以定义登录登出为