RESTful API：最佳实践和使用约定-JavaScript中文网-JavaScript教程资源分享门户

什么是 RESTful API？

RESTful API 是一种 Web 服务的架构风格，它使用标准的 HTTP 协议进行通信，并遵循一组设计原则和约定，提供灵活、可扩展和可维护的接口。RESTful API 的设计重点在于资源的表达和状态转换，可以通过 URL、HTTP 动词、内容协商等方式实现。

RESTful API 的最佳实践

1. URI 的设计

URI 应该基于名词而不是动词
URI 中应该只包含资源标识符，不应该包含操作信息
URI 应该遵循统一的路径结构
URI 长度应该适中，不要太短也不要太长
URI 应该使用连字符 "-" 进行单词分隔，避免使用下划线 "_"
URI 应该是大小写无关的，推荐使用小写字母

示例：

GET /api/users/123  // 获取用户 ID 为 123 的信息
PUT /api/users/123  // 更新用户 ID 为 123 的信息
GET /api/users?name=John  // 获取用户名为 John 的用户列表

2. HTTP 动词的使用

使用标准的 HTTP 动词，如 GET、POST、PUT、DELETE 等，不要使用自定义动词
使用 HTTP 动词对资源进行 CRUD（增删改查）操作
不要在 URL 中使用动词，如 /get、/register 等

示例：

GET /api/users/123  // 获取用户 ID 为 123 的信息
PUT /api/users/123  // 更新用户 ID 为 123 的信息
POST /api/users  // 新增用户
DELETE /api/users/123  // 删除用户 ID 为 123 的信息

3. HTTP 状态码的使用

使用恰当的 HTTP 状态码，如 200 OK、400 Bad Request、404 Not Found、500 Internal Server Error 等
对资源的错误操作返回适当的状态码和错误信息
尽可能减少使用 2XX 状态码以外的状态码

示例：

GET /api/users/123
- 成功：返回 200 OK 和用户信息
- 失败：返回 404 Not Found

PUT /api/users/123
- 成功：返回 200 OK 和更新后的用户信息
- 失败：返回 400 Bad Request 或 500 Internal Server Error

4. 内容协商的使用

支持多种格式的数据返回，如 JSON、XML、HTML 等
使用 Accept 请求头来指定客户端期望接受的数据格式
使用 Content-Type 响应头来指定服务器返回的数据格式

示例：

GET /api/users/123
- 请求头：Accept: application/json
- 成功：响应头：Content-Type: application/json，返回 JSON 格式的用户信息

5. 安全性和权限控制

使用 HTTPS 协议保证数据传输的安全性
对需要身份验证的接口进行权限控制，使用 Token、Cookie、HTTP Basic Authentication 等方式进行身份验证
注意接口的访问限制，避免对敏感资源进行未经授权的访问

RESTful API 的使用约定

如果要使用 RESTful API 开发客户端或服务端，需要遵守以下约定：

1. URL 规范

使用合适的 HTTP 动词对资源进行操作
URI 使用名词而不是动词，并且遵循一定的格式规范
URI 尽可能短，路径层级不宜太深嵌套
URI 不包含操作信息，所有操作都应该由 HTTP 动词表示

2. 数据格式规范

接口返回的数据格式应该为 JSON 格式，并且使用一定的命名约定（如驼峰式命名）
接口的参数格式应该使用 URL 参数或请求体参数，并且遵循一定的数据结构规范

3. 错误处理规范

接口返回的错误信息应该包含错误码、错误信息、错误详情等信息
错误码应该有一定的约定意义，方便客户端和服务端进行错误码解析和处理
对于不同的错误类型应该返回不同的 HTTP 状态码，并且遵循一定的错误处理规范

示例代码

下面是一个简单的 RESTful API 的示例代码：

// www.javascriptcn.com code example
const Koa = require('koa');
const Router = require('@koa/router');

const app = new Koa();
const router = new Router();

const users = [
  { id: 1, name: 'Alice', age: 20 },
  { id: 2, name: 'Bob', age: 30 },
  { id: 3, name: 'Charlie', age: 40 },
];

router.get('/api/users', (ctx, next) => {
  ctx.body = users;
});

router.get('/api/users/:id', (ctx, next) => {
  const user = users.find(u => u.id === +ctx.params.id);
  if (user) {
    ctx.body = user;
  } else {
    ctx.status = 404;
  }
});

router.post('/api/users', (ctx, next) => {
  const { name, age } = ctx.request.body;
  const id = users[users.length - 1].id + 1;
  const user = { id, name, age };
  users.push(user);
  ctx.body = user;
});

router.put('/api/users/:id', (ctx, next) => {
  const user = users.find(u => u.id === +ctx.params.id);
  if (user) {
    const { name, age } = ctx.request.body;
    user.name = name || user.name;
    user.age = age || user.age;
    ctx.body = user;
  } else {
    ctx.status = 404;
  }
});

router.delete('/api/users/:id', (ctx, next) => {
  const index = users.findIndex(u => u.id === +ctx.params.id);
  if (index !== -1) {
    users.splice(index, 1);
  }
  ctx.status = 204;
});

app.use(require('koa-bodyparser')());
app.use(router.routes());
app.use(router.allowedMethods());

app.listen(3000);

在上面的示例代码中，我们使用 Koa 框架实现了一个简单的 RESTful API，包含了获取用户列表、获取单个用户、新增用户、更新用户和删除用户等功能，并且遵循了 RESTful API 的设计原则、最佳实践和使用约定。

来源：JavaScript中文网，转载请注明来源 https://www.javascriptcn.com/post/67d7d0bda941bf7134dfce3c

RESTful API：最佳实践和使用约定