RESTful API 是现代 Web 应用程序中最常用的 API 设计风格之一。它以资源为中心，使用 HTTP 方法来处理资源的 CRUD 操作。在本文中，我们将深入探讨如何从 URI 到方法设计 RESTful API，并提供最佳实践和示例代码。
URI 设计
URI（Uniform Resource Identifier）是 RESTful API 中最重要的组成部分之一。它是一个字符串，用于唯一标识资源。在 URI 设计中，我们应该遵循以下几个原则：
1. 使用名词而不是动词
RESTful API 的 URI 应该使用名词而不是动词来表示资源。这是因为 HTTP 方法已经定义了动词的含义，我们只需要使用名词来指定资源即可。
例如，使用 /users URI 表示用户资源，而不是使用 /getUsers。
2. 使用复数形式
RESTful API 的 URI 应该使用复数形式来表示资源。这是因为资源通常是一个集合，而不是一个单一的实体。
例如，使用 /users URI 表示用户资源集合，而不是使用 /user。
3. 使用连字符
RESTful API 的 URI 应该使用连字符（-）来连接单词。这是因为空格和下划线在 URI 中是不允许的。
例如，使用 /user-profiles URI 表示用户资料资源，而不是使用 /user profiles 或 /user_profiles。
4. 避免使用动态 URI
RESTful API 的 URI 应该尽量避免使用动态 URI，因为它们对缓存和索引等方面的支持不够友好。如果必须使用动态 URI，应该将其参数化，以便于缓存和索引。
例如，使用 /users/{id} URI 表示具有指定 ID 的用户资源，而不是使用 /users?id={id}。
HTTP 方法设计
HTTP 方法是 RESTful API 中处理资源 CRUD 操作的核心。在 HTTP/1.1 中，共定义了 8 种方法，其中 4 种最常用：
- GET：获取资源
- POST：创建资源
- PUT：更新资源
- DELETE：删除资源
在 HTTP 方法设计中，我们应该遵循以下几个原则：
1. 将 HTTP 方法映射到 CRUD 操作
RESTful API 的 HTTP 方法应该映射到资源的 CRUD 操作。这是因为 HTTP 方法已经定义了它们的含义，我们只需要将它们映射到对应的操作即可。
例如，使用 GET 方法获取资源，使用 POST 方法创建资源，使用 PUT 方法更新资源，使用 DELETE 方法删除资源。
2. 使用 HTTP 状态码表示操作结果
RESTful API 的 HTTP 方法应该返回适当的 HTTP 状态码来表示操作结果。这是因为 HTTP 状态码已经定义了它们的含义，我们只需要将它们映射到对应的操作结果即可。
例如，使用 200 状态码表示成功获取资源，使用 201 状态码表示成功创建资源，使用 204 状态码表示成功删除资源，使用 400 状态码表示请求参数错误，使用 404 状态码表示资源不存在，使用 500 状态码表示服务器错误。
示例代码
下面是一个基于 Node.js 和 Express 框架的 RESTful API 示例代码，它演示了 URI 设计和 HTTP 方法设计的最佳实践。
// javascriptcn.com 代码示例
const express = require('express');
const app = express();
const port = 3000;
let users = [
{ id: 1, name: 'Alice', age: 20 },
{ id: 2, name: 'Bob', age: 30 },
{ id: 3, name: 'Charlie', age: 40 },
];
app.use(express.json());
// 获取所有用户
app.get('/users', (req, res) => {
res.status(200).json(users);
});
// 获取指定 ID 的用户
app.get('/users/:id', (req, res) => {
const id = Number(req.params.id);
const user = users.find(user => user.id === id);
if (!user) {
res.status(404).send('User not found');
} else {
res.status(200).json(user);
}
});
// 创建用户
app.post('/users', (req, res) => {
const user = req.body;
if (!user || !user.name || !user.age) {
res.status(400).send('Invalid request');
} else {
const id = users.length + 1;
users.push({ id, ...user });
res.status(201).json({ id });
}
});
// 更新指定 ID 的用户
app.put('/users/:id', (req, res) => {
const id = Number(req.params.id);
const user = users.find(user => user.id === id);
if (!user) {
res.status(404).send('User not found');
} else {
const updatedUser = req.body;
if (!updatedUser || !updatedUser.name || !updatedUser.age) {
res.status(400).send('Invalid request');
} else {
users = users.map(user => user.id === id ? { id, ...updatedUser } : user);
res.status(204).send();
}
}
});
// 删除指定 ID 的用户
app.delete('/users/:id', (req, res) => {
const id = Number(req.params.id);
const user = users.find(user => user.id === id);
if (!user) {
res.status(404).send('User not found');
} else {
users = users.filter(user => user.id !== id);
res.status(204).send();
}
});
app.listen(port, () => {
console.log(`Server listening at http://localhost:${port}`);
});在上面的示例代码中，我们使用了以下 URI：
/users：表示用户资源集合/users/:id：表示具有指定 ID 的用户资源
我们使用了以下 HTTP 方法：
- GET：用于获取资源
- POST：用于创建资源
- PUT：用于更新资源
- DELETE：用于删除资源
我们使用了以下 HTTP 状态码：
- 200：表示成功获取资源
- 201：表示成功创建资源
- 204：表示成功删除资源
- 400：表示请求参数错误
- 404：表示资源不存在
总结
在本文中，我们深入探讨了从 URI 到方法的 RESTful API 设计思路及最佳实践，并提供了示例代码。通过遵循 URI 设计和 HTTP 方法设计的最佳实践，我们可以设计出易于理解、易于使用和易于维护的 RESTful API。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/650c3e9895b1f8cacd6485eb