Node.js RESTful API（一文讲透）

什么是 Node.js RESTful API？

在现代 Web 开发中，前后端分离已成为主流架构。当我们访问一个网站时，页面展示的内容往往不是直接写死在 HTML 里的，而是通过一个“数据接口”动态获取的。这个接口，就是我们常说的 Node.js RESTful API。

你可以把 RESTful API 想象成一家餐厅的菜单系统。顾客（前端）不需要知道厨房（后端）怎么做的菜，只需要告诉服务员（API）“我要一份番茄炒蛋”，服务员就会去厨房取菜并送到你桌上。这个“点菜—取菜—上菜”的流程，就是 API 的工作方式。

Node.js 是一个基于 Chrome V8 引擎的 JavaScript 运行时环境，它允许你在服务器端运行 JavaScript。结合 Express 框架，我们可以快速搭建一个高性能、轻量级的服务器，用来响应各种请求，比如获取用户数据、创建新订单、修改信息等。

而 RESTful API 是一种设计风格，它遵循 HTTP 协议的规范，使用标准的 HTTP 方法（如 GET、POST、PUT、DELETE）来操作资源。比如：

• GET /users → 获取用户列表（读取）
• POST /users → 创建新用户（新增）
• PUT /users/1 → 更新用户 ID 为 1 的信息（更新）
• DELETE /users/1 → 删除用户 ID 为 1 的记录（删除）

这些请求路径清晰、语义明确，是构建可维护系统的基石。

搭建 Node.js RESTful API 项目环境

要开始开发，第一步是准备开发环境。

打开终端（Terminal），确保你已安装 Node.js（建议使用 16.x 或 18.x 版本）。运行以下命令检查版本：

node -v

如果提示命令未找到，请先安装 Node.js。推荐使用 Node Version Manager (nvm) 管理多个 Node.js 版本。

接下来，创建项目目录并初始化：

mkdir node-rest-api-demo
cd node-rest-api-demo
npm init -y

npm init -y 会自动创建 package.json 文件，这是项目的核心配置文件，记录了依赖、脚本、版本等信息。

现在安装 Express 框架，它是构建 Node.js RESTful API 的首选工具：

npm install express

安装完成后，创建主文件 server.js，这是整个应用的入口：

// server.js
// 引入 Express 模块
const express = require('express');

// 创建 Express 应用实例
const app = express();

// 定义服务器监听端口
const PORT = 3000;

// 启动服务器并监听指定端口
app.listen(PORT, () => {
  console.log(`服务器已启动，访问地址：http://localhost:${PORT}`);
});

这段代码做了三件事：

1. 引入 Express 模块；
2. 创建一个 Express 实例（app）；
3. 启动服务器，监听 3000 端口。

运行服务器：

node server.js

打开浏览器访问 http://localhost:3000，你会看到控制台输出提示信息。这说明你的 Node.js RESTful API 项目已经成功启动！

实现基础路由与 HTTP 方法

有了基础服务器，下一步是添加路由。路由决定了当用户访问某个 URL 时，服务器该做什么。

我们来实现一个简单的用户信息接口。

创建用户数据模拟

在项目根目录新建 data.js 文件，用于存放模拟数据：

// data.js
// 模拟用户数据数组，每个对象代表一个用户
const users = [
  { id: 1, name: '张三', email: 'zhangsan@example.com' },
  { id: 2, name: '李四', email: 'lisi@example.com' },
  { id: 3, name: '王五', email: 'wangwu@example.com' }
];

// 导出用户数据，供其他模块使用
module.exports = users;

添加 GET 路由：获取用户列表

修改 server.js，添加路由逻辑：

// server.js
const express = require('express');
const usersData = require('./data'); // 引入模拟数据

const app = express();

// 设置端口
const PORT = 3000;

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

// GET /api/users → 获取所有用户
app.get('/api/users', (req, res) => {
  // 返回用户列表，状态码为 200（成功）
  res.status(200).json({
    success: true,
    data: usersData
  });
});

// 启动服务器
app.listen(PORT, () => {
  console.log(`服务器已启动，访问地址：http://localhost:${PORT}`);
});

关键点说明：

• app.use(express.json())：告诉 Express 解析请求体中的 JSON 数据，否则无法接收 POST 请求中的数据。
• res.status(200)：设置 HTTP 状态码为 200，表示请求成功。
• res.json()：将 JavaScript 对象自动转换为 JSON 格式返回给前端。

现在启动服务器，用浏览器或 Postman 访问 http://localhost:3000/api/users，你会看到返回的 JSON 数据。

实现数据增删改功能

接下来，我们实现完整的 CRUD 操作。

POST /api/users：创建新用户

// POST /api/users → 创建新用户
app.post('/api/users', (req, res) => {
  // 从请求体中获取新用户数据
  const { name, email } = req.body;

  // 验证必要字段是否存在
  if (!name || !email) {
    return res.status(400).json({
      success: false,
      message: '姓名和邮箱为必填项'
    });
  }

  // 生成新用户 ID（简单方式：当前最大 ID + 1）
  const newId = usersData.length > 0 ? Math.max(...usersData.map(u => u.id)) + 1 : 1;

  // 创建新用户对象
  const newUser = {
    id: newId,
    name,
    email
  };

  // 添加到数据数组中
  usersData.push(newUser);

  // 返回成功响应，包含新用户信息
  res.status(201).json({
    success: true,
    message: '用户创建成功',
    data: newUser
  });
});

注意：

• 201 状态码表示“创建成功”，适用于新增资源。
• 使用 Math.max(...usersData.map(u => u.id)) 动态获取最大 ID，避免重复。

PUT /api/users/:id：更新用户信息

// PUT /api/users/:id → 更新指定用户
app.put('/api/users/:id', (req, res) => {
  // 从 URL 参数中获取用户 ID
  const userId = parseInt(req.params.id);

  // 查找目标用户
  const userIndex = usersData.findIndex(u => u.id === userId);

  // 如果未找到，返回 404
  if (userIndex === -1) {
    return res.status(404).json({
      success: false,
      message: '用户不存在'
    });
  }

  // 获取更新数据
  const { name, email } = req.body;

  // 验证字段
  if (!name || !email) {
    return res.status(400).json({
      success: false,
      message: '姓名和邮箱为必填项'
    });
  }

  // 更新用户信息
  usersData[userIndex].name = name;
  usersData[userIndex].email = email;

  // 返回更新后的数据
  res.status(200).json({
    success: true,
    message: '用户信息更新成功',
    data: usersData[userIndex]
  });
});

DELETE /api/users/:id：删除用户

// DELETE /api/users/:id → 删除指定用户
app.delete('/api/users/:id', (req, res) => {
  const userId = parseInt(req.params.id);
  const userIndex = usersData.findIndex(u => u.id === userId);

  if (userIndex === -1) {
    return res.status(404).json({
      success: false,
      message: '用户不存在'
    });
  }

  // 删除用户
  usersData.splice(userIndex, 1);

  // 返回删除成功提示
  res.status(200).json({
    success: true,
    message: '用户删除成功'
  });
});

使用 Postman 测试 API 接口

为了更高效地测试，推荐使用 Postman 工具。

1. 下载并安装 Postman ；
2. 打开后创建新请求；
3. 设置请求方式（GET / POST / PUT / DELETE）；
4. 输入 URL：http://localhost:3000/api/users；
5. 对于 POST/PUT，切换到 Body 选项卡，选择 raw → JSON，输入如下内容：

{
  "name": "赵六",
  "email": "zhaoliu@example.com"
}

点击发送，即可看到接口响应结果。

通过这种方式，你可以快速验证每个接口是否按预期工作。

高级技巧：错误处理与中间件

当项目复杂后，统一处理错误变得非常重要。

自定义错误处理中间件

在 server.js 最后添加：

// 错误处理中间件：捕获所有未处理的异常
app.use((err, req, res, next) => {
  console.error(err.stack);
  res.status(500).json({
    success: false,
    message: '服务器内部错误，请稍后再试'
  });
});

这个中间件会捕获所有未被捕获的异常，并返回统一的错误信息。

使用中间件进行日志记录

可以添加一个简单的日志中间件：

// 日志中间件：记录每次请求
app.use((req, res, next) => {
  console.log(`${new Date().toISOString()} | ${req.method} ${req.path}`);
  next(); // 必须调用 next()，否则请求会卡住
});

这样每次请求都会在控制台输出访问记录，方便调试。

总结：Node.js RESTful API 的核心价值

通过本教程，你已经掌握了一个完整 Node.js RESTful API 的搭建流程。从环境配置、路由设计、数据操作到错误处理，每一步都为你构建真实项目打下坚实基础。

Node.js RESTful API 的优势在于：

• 使用 JavaScript 全栈开发，前后端语言统一；
• 基于 HTTP 协议，与前端通信无障碍；
• 易于扩展，支持高并发；
• 社区生态丰富，工具链成熟。

无论你是开发个人项目、团队协作还是企业级应用，掌握这套技能都将让你在开发道路上走得更稳、更快。

现在，你可以尝试将这个项目升级为连接数据库（如 MongoDB 或 MySQL），实现持久化存储，进一步提升实战能力。