API 设计：使用 Node.js 和 Express.js 的综合教程

API（应用程序编程接口）设计涉及创建一个高效而强大的接口，允许不同的软件应用程序相互交互。

说明

本教程将指导您使用 Node.js 和 Express.js 作为核心技术来规划、设计和构建 API。但是，这些原则可以应用于任何语言或框架。我们将创建一个简单的在线市场 API 作为工作示例。

让我们开始吧！

第 I 部分：规划 API

1. 确定目的：设计 API 的第一步是确定它的用途。我们的 API 适用于在线市场，用户可以在其中查看待售商品并进行购买。
2. 定义资源：接下来，确定 API 将处理的不同类型的数据。对于我们的市场，我们需要"物品"和"购买"的资源。
3. 设计终结点：每个资源都应具有一组关联的终结点，这些终结点允许客户端与数据进行交互。使用 REST 原则，我们将为"项目"和"购买"创建终结点。

以下是 API 端点的粗略草图：

• GET /items：获取所有项目
• GET /items/：id：获取特定项目
• POST /items：添加新项目（仅限管理员）
• DELETE /items/：id：删除项目（仅限管理员）
• POST /purchases：进行新的购买

第 II 部分：构建 API

在本教程中，需要在计算机上安装 Node.js 和 npm。为您的项目创建一个新目录，在终端中导航到该目录，然后初始化一个新的 Node.js 项目：

mkdir marketplace-api && cd marketplace-api
npm init -y

接下来，安装 Express.js，一个流行的 Node.js Web 框架：

npm install express

2.1 设置服务器

让我们从设置一个基本的 Express 服务器开始。创建一个名为 ：app.js

const express = require('express');
const app = express();

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

您可以使用 启动服务器。服务器将在端口 3000 上启动。node app.js

2.2 创建终结点

让我们创建之前计划的终结点。首先，我们需要定义我们的数据。为简单起见，我们将使用内存中数组来存储数据：

let items = [];
let purchases = [];

我们还需要安装和使用 body-parser 中间件，以便 Express 能够理解 JSON body：

npm install body-parser

然后，在：app.js

const bodyParser = require('body-parser');
app.use(bodyParser.json());

现在，让我们创建终结点。以下是实现它们的方法：

查看所有项目：

app.get('/items', (req, res) => {
    res.json(items);
});

查看特定项目：

app.get('/items/:id', (req, res) => {
    const item = items.find(i => i.id === parseInt(req.params.id));
    if (!item) return res.status(404).send('Item not found');
    res.json(item);
});

添加项目（仅限管理员）：

app.post('/items', (req, res) => {
    // This should be protected
    const newItem = {
        id: items.length + 1,
        name: req.body.name,
        price: req.body.price
    };
    items.push(newItem);
    res.status(201).json(newItem);
});

删除项目（仅限管理员）：

app.delete('/items/:id', (req, res) => {
    // This should be protected
    const itemIndex = items.findIndex(i => i.id === parseInt(req.params.id));
    if (itemIndex === -1) return res.status(404).send('Item not found');
    const deletedItem = items.splice(itemIndex, 1);
    res.json(deletedItem);
});

进行购买：

app.post('/purchases', (req, res) => {
    // This should also check if the item exists and if the user has enough funds
    const newPurchase = {
        id: purchases.length + 1,
        userId: req.body.userId,
        itemId: req.body.itemId,
    };
    purchases.push(newPurchase);
    res.status(201).json(newPurchase);
});

第III 部分: 测试您的 API

您可以使用 Postman 或 curl 等工具测试您的 API。确保每个终结点都按预期运行并正确处理错误。始终使用不同类型的输入和场景进行测试，以确保 API 可靠。

第 IV 部分：记录 API

好的 API 文档可以包括概述、身份验证步骤、端点描述、错误代码和示例。您可以手动创建 API 文档，也可以使用工具自动生成 API 文档。

对于 Node.js，您可以使用 Swagger UI Express 等工具自动生成交互式文档。以下是有关如何设置它的快速示例：

1. 安装必要的模块：

npm install swagger-ui-express yamljs

2. 创建一个新的 Swagger 规范文件：swagger.yaml

swagger: "2.0"
info:
  version: "1.0.0"
  title: "Marketplace API"
paths:
  /items:
    get:
      summary: "Get all items"
      responses:
        200:
          description: "A list of items"
          schema:
            $ref: '#/definitions/Item'
definitions:
  Item:
    type: "object"
    properties:
      id:
        type: "integer"
      name:
        type: "string"
      price:
        type: "number"

3. 在以下环境中导入并使用 Swagger UI：app.js

const swaggerUi = require('swagger-ui-express');
const YAML = require('yamljs');
const swaggerDocument = YAML.load('./swagger.yaml');

app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));

现在，您可以在 中查看 API 文档。localhost:3000/api-docs

第 V 部分：保护 API

您可以采取以下一些步骤来保护 API：

第 1 步：使用 HTTPS

Express.js 本身不支持 HTTPS，但在部署应用程序时，请确保使用支持 HTTPS 的提供程序，例如 AWS、Azure 或 Heroku。

第 2 步：身份验证

Express.js 没有内置的身份验证支持，但您可以使用 Passport.js 等中间件来处理此问题。

下面是如何设置基于令牌的身份验证的简化示例：

1. 安装 Passport.js 和 JWT 策略：

npm install passport passport-jwt jsonwebtoken

2. 在您的 ：app.js

const jwt = require('jsonwebtoken');
const passport = require('passport');
const JwtStrategy = require('passport-jwt').Strategy;

// Users should be stored in a database
let users = [{ id: '1', name: 'test', password: 'test', token: '' }];

// JWT strategy
passport.use(new JwtStrategy({ secretOrKey: 'secret' }, (jwtPayload, done) => {
    const user = users.find(user => user.id === jwtPayload.id);
    if (user) {
        return done(null, user);
    } else {
        return done(null, false);
    }
}));

// Login route
app.post('/login', (req, res) => {
    const user = users.find(user => user.name === req.body.username && user.password === req.body.password);
    if (user) {
        const token = jwt.sign({ id: user.id }, 'secret');
        user.token = token;
        res.json({ token });
    } else {
        res.sendStatus(401);
    }
});

// Protected route
app.post('/items', passport.authenticate('jwt', { session: false }), (req, res) => {
    // Process request...
});

此设置要求客户端在标头中发送令牌。Bearer``Authorization

第 3 步：授权

对于授权，请在处理请求之前检查用户的角色。例如：

app.post('/items', passport.authenticate('jwt', { session: false }), (req, res) => {
    if (req.user.role !== 'admin') return res.sendStatus(403);
    // Process request...
});

第 4 步：速率限制

Express.js 本身不支持速率限制，但有一些中间件包可以使用：express-rate-limit

npm install express-rate-limit

然后，在您的 ：app.js

const rateLimit = require('express-rate-limit');

const apiLimiter = rateLimit({
    windowMs: 15 * 60 * 1000, // 15 minutes
    max: 100
});

app.use('/api/', apiLimiter);

第 5 步：输入验证

始终验证 API 的输入。例如：

app.post('/items', (req, res) => {
    if (!req.body.name || !req.body.price) return res.status(400).send('Invalid input');
    // Process request...
});

第 6 步：错误处理

错误处理对于防止信息泄露非常重要。Express.js 会自动处理未捕获的异常并发送响应。自定义错误处理，如下所示：500 Internal Server Error

app.use((err, req, res, next) => {
    console.error(err.stack);
    res.status(500).send('Something broke!');
});

请记住，安全是一个持续的过程。始终了解最新的安全最佳实践，并定期审核 API 是否存在漏洞。瓦利德·穆萨