Rest API 教程 – 完整的初学者指南

介绍

在构建 API 时，RESTful API 是最常见的类型之一。像任何技术一样，REST API 可以根据需求提供简单的服务，也可以通过增强功能来处理更复杂的任务。无论正在构建什么样的 API，本文将帮助了解如何构建一个 RESTful API。通过本篇博客，读者将能够使用 NodeJS 构建一个简单的 RESTful API，并能够在此基础上进行扩展，满足特定需求。接下来，我们将进一步了解什么是 REST API。

什么是 REST API？

REST（表述性状态传输）API 是一种允许不同软件应用程序通过互联网或本地网络进行互联互通的机制。REST API 遵循特定的规则和标准，使得应用程序和用户能够通过 HTTP 请求来访问和操作数据。通常，REST API 传输的数据格式为 JSON（JavaScript 对象表示法）。发送的数据被称为请求，从 API 调用中接收到的数据则称为响应。RESTful API 的两个主要特点如下：

无状态交互：每个从客户端到服务器的请求都必须包含处理该请求所需的所有信息，服务器不会保存任何关于客户端的会话信息。
统一接口：REST API 使用标准的 HTTP 方法设计，这使得任何熟悉 HTTP 的开发人员都能轻松上手。

为什么使用 REST API？

虽然有多种类型的 API 可供选择，但 RESTful API 已成为现代生产环境中几乎所有 API 的首选技术。这并非偶然，而是因为 REST 技术具有简单性和可扩展性。在支持 REST API 的框架和技术中，有大量的选择，这对开发和支持 REST API 提供了巨大的优势。接下来，让我们深入了解 REST API 为开发者带来的几大好处：

可扩展性：得益于无状态特性，REST API 能处理各种类型的调用，返回不同的数据格式，甚至可以通过超媒体的实现来调整结构。
灵活性与可移植性：数据的表示不依赖于资源或方法，这带来了更高的灵活性，使得 REST API 适用于多种类型的应用。
独立性：客户端和服务器的分离减少了相互依赖，使得应用程序各部分可以独立开发，避免相互影响。

REST API 的主要特性

REST API 基于六个基本原则构建，以下是这些原则的详细介绍：

统一接口：通过为客户端和服务器提供标准化的通信方法，这一原则简化了架构设计。只要接口保持一致，客户端和服务器即可独立发展。
客户端-服务器分离：这种分离增强了用户界面在多个平台之间的可移植性，同时通过简化服务器组件提升了可扩展性。客户端和服务器的独立性使得一方的更改不会直接影响另一方。
无状态：每个客户端请求必须包含处理请求所需的所有信息，服务器不存储关于客户端会话的任何状态。这种无状态设计简化了系统架构并提高了可靠性。
可缓存：允许响应可缓存，从而减少客户端重复获取相同数据的需求，显著提升性能。恰当的缓存管理确保客户端能获取最新信息，同时减轻服务器负担。
分层系统：该原则通过限制每层组件的行为，允许系统由多个层级组成。客户端与各层交互，但不需要了解是否是终端服务器或中介层，这增加了系统的灵活性和可扩展性。
按需代码（可选）：这一约束允许服务器通过发送可执行代码（如 JavaScript）来扩展客户端功能，虽然这一特性较少见，但它通过卸载部分功能到服务器降低了客户端的复杂性。

REST API 方法

REST API 使用标准的 HTTP 方法，因此大多数开发人员已经熟悉这些动词。每种方法有其特定的功能：

GET：从指定的资源请求数据，只进行数据检索，不进行其他操作。
POST：将数据发送到服务器进行创建，通常用于上传文件或提交表单。
PUT：更新目标资源的所有当前表示，使用上传的内容进行替换。
DELETE：删除指定的资源。
HEAD：与 GET 方法类似，但只传输状态行和头部信息。
PATCH：对资源进行部分修改。

这些方法与数据库管理中的 CRUD 操作（创建、读取、更新、删除）相对应，理解这些方法对于设计 RESTful API 至关重要。

使用 REST API 的优点

REST API 以其简单性和灵活性而闻名，它利用标准的 HTTP 方法，易于理解和使用。这种通用的 Web 通信方式使得平台间具备高度的兼容性。REST API 的一大优势是其可扩展性，得益于无状态设计，无需服务器维护会话状态，简化了服务器架构。REST API 还具有较高的性能和效率，因为可以缓存响应，减少数据传输量。此外，REST 技术被广泛采用，借助庞大的社区和工具支持，REST API 在分布式系统和微服务开发中具有极好的可移植性和易于集成性。

使用 REST API 时的挑战

尽管 REST API 具有诸多优点，但也面临一些挑战。其无状态特性可能导致请求体积较大，因为每个请求都必须包含所有必要的数据。此外，可能会出现数据过度获取或获取不足的问题，这会影响性能，可能需要多个请求来获取完整数据，或返回过多不必要的数据。安全性也是一个潜在挑战，需要正确实施身份验证和数据传输的安全措施以保护数据。版本控制也是一大难题，修改可能会破坏向后兼容性。随着 REST API 的横向扩展，在高负载情况下，HTTP/HTTPS 的开销可能会导致性能瓶颈。最后，由于缺乏严格的标准，不同 REST API 之间可能存在不一致性的问题。

如何构建 REST API

回顾了 REST API 的所有基础知识及相关内容后，接下来将构建一个 REST API。以下示例展示了如何使用 NodeJS 和 Express 实现一个简单的 REST API。当前端点未执行任何实际的 CRUD 操作，但可基于此代码添加相关功能。首先设置环境，然后构建端点。

第 1 步：设置环境

安装 Node.js
确保已安装 Node.js。可从 nodejs.org 下载。

初始化项目
创建项目目录。在命令行中导航到该目录并运行 npm init 以创建 package.json 文件。

第 2 步：安装 Express

由于 API 项目将使用 Express，需通过 npm 安装。在项目目录中运行 npm install express。安装完成后，Express 即可使用。

第 3 步：创建服务器 (server.js)

开始实现实际的 API 代码。首先，设置应用程序的基本基础设施。创建一个名为 server.js 的文件并添加以下代码：

const express = require('express');

const app = express();

app.use(express.json()); // 解析 JSON 请求体的中间件



app.listen(3000, () => console.log('Server running on port 3000'));

上述代码完成了以下操作：

require('express')：导入 Express 模块。
express()：初始化一个新的 Express 应用程序。
app.use(express.json())：使用中间件解析 JSON 请求体。
app.listen(...)：在端口 3000 上启动服务器。

运行该应用程序后，服务器将启动，但尚未提供供用户使用的 API 端点。接下来，将实现用户可利用的端点。

第 4 步：实施 RESTful 端点

创建 API 时，拥有多个端点以实现各种任务是合理的。需使用之前介绍的 CRUD API 的 HTTP 方法（如 GET、POST、PUT、DELETE），每种方法对应不同的 CRUD 操作。以下是每种类型端点的示例，可在 Express 项目中的 app.use() 语句之后添加并执行此代码。

获取端点

实现从服务器获取数据的 GET 端点。以下代码展示了此类端点的基本结构：

app.get('/api/items', (req, res) => {

  res.send('List of items');

});

在 app.get(...) 语句中，定义了 GET 路由。当向 /api/items 发出 GET 请求时，将执行回调函数。上述示例使用 res.send() 返回一个字符串。在功能更强大的端点中，可能会访问数据库等资源并返回数据。

发布端点

实现 POST 端点，该端点包含向服务器添加新数据的逻辑。以下代码展示了此类端点的结构：

app.post('/api/items', (req, res) => {

  const newItem = req.body; // 请求体中发送的数据

  res.send(`Item added: ${newItem.name}`);

});

在上述代码中，app.post(...) 函数处理 POST 请求。req.body 包含请求中发送的数据，并在响应中返回。在功能更强大的端点中，可能会在此处执行将数据写入数据库的逻辑。创建新记录后，可发送一个布尔值，例如 created: true，或新创建实体的 ID。

更新端点

创建用于更新现有数据的 PUT 端点。以下代码展示了 PUT 端点的基本结构：

app.put('/api/items/:id', (req, res) => {

  const itemId = req.params.id; // 访问 URL 参数

  res.send(`Item with ID ${itemId} updated`);

});

在上述代码中，app.put(...) 处理 PUT 请求。要更新的资源的 ID 通常作为查询参数或 URI 参数传递。通过 req.params.id 获取 ID 参数。在实际实现中，通常使用请求正文中的数据进行数据库调用以更新资源，然后返回一个布尔值，说明更新是否已处理。

删除端点

展示从服务器删除数据的 DELETE 端点的示例。以下代码展示了 DELETE 端点在 Express 中的基本示例：

app.delete('/api/items/:id', (req, res) => {

  const itemId = req.params.id;

  res.send(`Item with ID ${itemId} deleted`);

});

如上所示，app.delete(...) 方法处理 DELETE 请求。与 PUT 一样，使用 req.params.id 确定要删除的项目。与其他端点类似，可能会向数据库发出请求，以删除指定资源。

第 5 步：测试 API

构建 API 后，下一步是在本地系统上启动并运行，并使用 Postman 进行测试。以下是部署和测试端点的各个步骤，从启动 Node.js 服务器开始。

设置并运行 API
确保 Node.js 服务器正在运行才能访问 API 端点。通常，通过在终端（指向项目根目录）中执行 node server.js 命令来启动并运行服务器。

配置 Postman
下载并安装 Postman（或 Insomnia）以向端点发出请求进行测试。首先，安装 Postman。如果尚未安装，请从官方网站下载。安装后，创建一个请求：打开 Postman，点击“新建”，然后点击“请求”，并将其保存到新的或现有的集合中。

测试 API 端点
使用所选的适当方法（如 GET、POST、PUT 或 DELETE）向每个端点发出请求。以下是每种方法类型的具体信息：

测试 GET：选择“GET”，输入端点（例如，http://localhost:3000/api/items），然后点击“发送”查看回复。
测试 POST：切换到“POST”，在请求正文中以 JSON 格式添加数据，然后发送请求以检查响应。
测试 PUT 和 DELETE：对 PUT（更新数据）和 DELETE（删除数据）重复类似步骤，确保在端点 URL 中包含项目 ID。

分析响应
测试每个端点时，检查 Postman 中每个请求的响应是否正确。成功的操作通常会返回状态代码，如 200（正常）或 201（已创建）。如出现错误，使用响应详细信息和服务器控制台日志进行调试。如果端点正在更改数据库中的资源，还需检查是否发生了正确的操作。

添加 API 分析和货币化

构建 API 只是一个开始。创建 API 端点后，除了使用 API 测试工具之外，还需要监控和分析传入流量。这有助于识别潜在问题和安全缺陷，并了解 API 的使用情况，这些都是 API 发展的关键方面。

随着 API 平台的发展，可能会开始专注于创建 API 产品。通过专注于 API 产品，API 从简单的构建转变为业务工具和收入来源。与更正式的产品类似，API 产品需要管理并可能被货币化。通过 API 增加收入是扩大业务利润的有效途径。

结论

至此，介绍了构建 REST API 的基础知识。本篇文章中，使用 Node.js 和 Express 构建了一些可扩展的简单端点。总体而言，提供的代码为应用程序构建 API 提供了良好的起点。

构建 API 后，可能希望开始分析 API 的使用情况并从中获利。在这些情况下，合适的工具可以帮助实现 API 分析和货币化，支持更好的 API 开发与管理。

原文链接：Rest API Tutorial – A Complete Beginner’s Guide