使用 Express 框架在 Node.js 中构建 RESTful API

一、RESTful 架构核心约束与请求处理模型

在编写任何服务端代码之前，必须明确 REST（Representational State Transfer，表现层状态转移）的核心设计准则。RESTful API 不是一种具体的语法，而是一套设计风格与架构约束：

• 资源导向（Resource-Oriented）：网络上的每一个实体均被视为“资源”，并通过唯一的统一资源标识符（URI）进行寻址。URI 中应始终使用名词而非动词，例如使用 /api/articles 而不是 /api/getArticles 或 /api/createArticle。
• 统一接口与标准动词：针对资源的操作严格依赖标准 HTTP 方法：GET 用于读取资源，POST 用于创建全新资源，PUT 用于全量更新/替换资源，DELETE 用于移除资源。
• 无状态性（Stateless）：每一个从客户端发往服务端的请求必须包含理解并完成该请求所需的全部上下文信息。服务端不应在内存中持久保留客户端的会话状态，这保证了服务的高可伸缩性与可水平扩展能力。
• 明确的自描述响应：服务端必须声明正确的 Content-Type: application/json 响应头，并返回对应执行结果的标准 HTTP 状态码（如 200、201、400、404、500）。

在 Express 体系中，客户端请求依次穿透全局中间件流水线、路由分发器，最终到达业务控制器。理解其生命周期流转是写出健壮接口的前提。

二、开发准备与工程初始化

在当前工作目录下初始化一个新的 Node.js 项目。请确保本地已安装稳定版的 Node.js 运行时（推荐 Node.js 18 LTS 或更高版本）。

1. 初始化 package.json 并安装依赖

打开终端执行以下命令创建项目目录并安装 Express 核心库：

# 创建项目工作目录并进入
mkdir express-rest-api && cd express-rest-api

# 初始化 package.json 文件（接受默认配置）
npm init -y

# 安装 Express 依赖
npm install express

为了更清晰地组织代码，我们采用目前业界通用的模块化组织方式。在项目根目录下创建 app.js 作为服务启动入口，规划合理的目录层级：

express-rest-api/
├── node_modules/
├── package.json
└── app.js

三、构建核心服务与基础中间件装配

RESTful API 绝大多数场景下均以 JSON 格式传输数据。在传统的 HTTP 请求中，客户端通过 POST 或 PUT 发送的 JSON 载荷是以原始数据流（Stream）的形式到达服务端的。如果未配置请求体解析器，req.body 将为 undefined。

自 Express 4.16.0 起，官方重新内置了基于 body-parser 的解析中间件 express.json()，无需额外安装第三方包即可直接解析 JSON 格式请求体。

以下为 app.js 的基础骨架代码：

const express = require('express');

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

// 端口配置：优先读取环境变量 PORT，缺省为 3000
const PORT = process.env.PORT || 3000;

// 装配全局 JSON 解析中间件
// 只有装配此中间件后，Express 才能将请求头为 application/json 的请求体反序列化为 req.body 对象
app.use(express.json());

// 挂载简单的健康检查端点（用于确认服务正常运转）
app.get('/health', (req, res) => {
  res.status(200).json({
    status: 'success',
    message: 'API 服务运行正常',
    timestamp: new Date().toISOString()
  });
});

// 启动 HTTP 服务监听
app.listen(PORT, () => {
  console.log(`[Server] RESTful API 服务已启动，监听端口: http://localhost:${PORT}`);
});

四、设计并实现标准 RESTful CRUD 路由

我们以典型的“技术文章（articles）”资源为例，完整实现增、删、改、查五个标准接口。在实际生产场景中，数据通常持久化存储在 PostgreSQL、MySQL 或 MongoDB 中；为了使本教程可以直接独立运行并保持代码聚焦，我们使用内存数组模拟底层数据源。

1. RESTful 资源路由与 HTTP 方法映射关系

在编写路由前，先审视资源的端点定义。必须严格禁止在 URL 中夹杂动作名词，所有的动作均由 HTTP 方法隐式承载：

2. 编写完整 CRUD 路由实现代码

在 app.js 中补充内存数据源以及完整的 5 个 CRUD 路由处理逻辑。各路由详细解析了 req.query、req.params 及 req.body：

// 内存模拟数据源
let articles = [
  { id: 1, title: 'Node.js 异步编程指南', author: '张三', category: 'Backend', createdAt: '2026-01-10T08:00:00Z' },
  { id: 2, title: '深入理解 Express 中间件机制', author: '李四', category: 'Backend', createdAt: '2026-02-15T09:30:00Z' },
  { id: 3, title: '现代前端工程化最佳实践', author: '王五', category: 'Frontend', createdAt: '2026-03-01T14:20:00Z' }
];

// 自增 ID 游标
let nextId = 4;

// -------------------------------------------------------------
// 1. GET /api/articles - 获取文章列表（支持根据分类筛选）
// -------------------------------------------------------------
app.get('/api/articles', (req, res) => {
  const { category } = req.query;
  let result = articles;

  // 支持查询字符串过滤：例如 /api/articles?category=Backend
  if (category) {
    result = result.filter(item => item.category.toLowerCase() === category.toLowerCase());
  }

  // 成功查询返回 200 OK
  return res.status(200).json({
    status: 'success',
    results: result.length,
    data: {
      articles: result
    }
  });
});

// -------------------------------------------------------------
// 2. GET /api/articles/:id - 获取指定 ID 的文章详情
// -------------------------------------------------------------
app.get('/api/articles/:id', (req, res, next) => {
  const articleId = parseInt(req.params.id, 10);

  // 参数合法性初筛
  if (isNaN(articleId)) {
    return res.status(400).json({
      status: 'fail',
      message: '文章 ID 必须为合法数字'
    });
  }

  const targetArticle = articles.find(item => item.id === articleId);

  // 未找到目标资源返回 404 Not Found
  if (!targetArticle) {
    return res.status(404).json({
      status: 'fail',
      message: `未找到 ID 为 ${articleId} 的文章资源`
    });
  }

  return res.status(200).json({
    status: 'success',
    data: {
      article: targetArticle
    }
  });
});

// -------------------------------------------------------------
// 3. POST /api/articles - 创建新文章
// -------------------------------------------------------------
app.post('/api/articles', (req, res) => {
  const { title, author, category } = req.body;

  // 校验必要字段：REST 规范要求输入不合法时返回 400 Bad Request
  if (!title || typeof title !== 'string' || title.trim() === '') {
    return res.status(400).json({
      status: 'fail',
      message: '字段 title 为必填项且不能为空字符串'
    });
  }

  if (!author || typeof author !== 'string' || author.trim() === '') {
    return res.status(400).json({
      status: 'fail',
      message: '字段 author 为必填项且不能为空字符串'
    });
  }

  const newArticle = {
    id: nextId++,
    title: title.trim(),
    author: author.trim(),
    category: category ? category.trim() : 'Uncategorized',
    createdAt: new Date().toISOString()
  };

  articles.push(newArticle);

  // 资源创建成功必须返回 201 Created，并在响应体中携带创建后的实体
  return res.status(201).json({
    status: 'success',
    message: '文章创建成功',
    data: {
      article: newArticle
    }
  });
});

// -------------------------------------------------------------
// 4. PUT /api/articles/:id - 完整更新指定 ID 的文章
// -------------------------------------------------------------
app.put('/api/articles/:id', (req, res) => {
  const articleId = parseInt(req.params.id, 10);

  if (isNaN(articleId)) {
    return res.status(400).json({
      status: 'fail',
      message: '文章 ID 必须为合法数字'
    });
  }

  const { title, author, category } = req.body;

  if (!title || !author) {
    return res.status(400).json({
      status: 'fail',
      message: 'PUT 请求为全量覆盖更新，title 与 author 字段均为必填项'
    });
  }

  const articleIndex = articles.findIndex(item => item.id === articleId);

  if (articleIndex === -1) {
    return res.status(404).json({
      status: 'fail',
      message: `目标文章不存在，无法执行更新操作（ID: ${articleId}）`
    });
  }

  // 执行全量替换更新，保留原资源创建时间与原有 ID
  const updatedArticle = {
    ...articles[articleIndex],
    title: title.trim(),
    author: author.trim(),
    category: category ? category.trim() : articles[articleIndex].category,
    updatedAt: new Date().toISOString()
  };

  articles[articleIndex] = updatedArticle;

  return res.status(200).json({
    status: 'success',
    message: '文章更新成功',
    data: {
      article: updatedArticle
    }
  });
});

// -------------------------------------------------------------
// 5. DELETE /api/articles/:id - 删除指定 ID 的文章
// -------------------------------------------------------------
app.delete('/api/articles/:id', (req, res) => {
  const articleId = parseInt(req.params.id, 10);

  if (isNaN(articleId)) {
    return res.status(400).json({
      status: 'fail',
      message: '文章 ID 必须为合法数字'
    });
  }

  const articleIndex = articles.findIndex(item => item.id === articleId);

  if (articleIndex === -1) {
    return res.status(404).json({
      status: 'fail',
      message: `未找到欲删除的目标文章（ID: ${articleId}）`
    });
  }

  // 移出数组
  articles.splice(articleIndex, 1);

  // REST 规范中，删除成功且无载荷返回时，推荐使用 204 No Content
  // 此时无需（且不应）发送响应体
  return res.status(204).send();
});

五、未匹配路由与全局集中式错误处理

在实际运行过程中，客户端可能会请求未定义的无效路径，或者在异步操作中抛出未捕获的异常。如果不对这些情况做兜底处理，Express 默认会输出 HTML 格式的 404 或将包含服务端路径的错误调用栈输出给客户端，这既破坏了 JSON 协议的一致性，也带来了严重的信息泄露安全隐患。

1. 404 未定义路径处理中间件

在所有正常业务路由的末尾，放置一个通配中间件，将所有未命中前述路由的请求统一转换为标准 JSON 格式的 404 响应：

// 捕获所有未被定义的路由，返回标准 JSON 404
app.use((req, res) => {
  res.status(404).json({
    status: 'fail',
    message: `无法在当前服务器上找到请求路径: ${req.method} ${req.originalUrl}`
  });
});

2. 4 参数集中式异常捕获中间件

Express 通过中间件函数形参的数量来区分普通中间件与错误处理中间件。必须严格声明 4 个参数：(err, req, res, next)。即使 next 未在函数体中使用，也必须在形参列表中保留，否则 Express 将无法将其识别为错误处理中间件。

// 全局集中式错误捕获中间件（必须包含 4 个形参）
app.use((err, req, res, next) => {
  const statusCode = err.statusCode || 500;
  const status = err.status || 'error';

  console.error('[Error Pipeline] 捕获未处理异常:', err.message);

  return res.status(statusCode).json({
    status: status,
    message: err.message || '服务器内部发生未预期异常'
  });
});

六、API 功能测试与结果验证

完成上述代码后，在终端执行 node app.js 启动服务。服务监听在 http://localhost:3000。使用常用的命令行工具 curl 进行各方法的标准调用验证：

1. 验证获取全部列表 (GET)

# 终端执行命令：
curl -X GET http://localhost:3000/api/articles

# 预期控制台返回输出（示例）：
{
  "status": "success",
  "results": 3,
  "data": {
    "articles": [
      { "id": 1, "title": "Node.js 异步编程指南", "author": "张三", "category": "Backend", "createdAt": "2026-01-10T08:00:00Z" },
      { "id": 2, "title": "深入理解 Express 中间件机制", "author": "李四", "category": "Backend", "createdAt": "2026-02-15T09:30:00Z" },
      { "id": 3, "title": "现代前端工程化最佳实践", "author": "王五", "category": "Frontend", "createdAt": "2026-03-01T14:20:00Z" }
    ]
  }
}

2. 验证创建新资源 (POST)

# 终端执行命令：
curl -X POST http://localhost:3000/api/articles \
     -H "Content-Type: application/json" \
     -d '{"title": "TypeScript 高级类型实战", "author": "赵六", "category": "Language"}'

# 预期返回 HTTP 201 Created 与新对象（示例）：
{
  "status": "success",
  "message": "文章创建成功",
  "data": {
    "article": {
      "id": 4,
      "title": "TypeScript 高级类型实战",
      "author": "赵六",
      "category": "Language",
      "createdAt": "2026-10-31T02:00:00.000Z"
    }
  }
}

3. 验证参数校验失败 (POST 缺失必要字段)

# 终端执行命令（缺少必填字段 title）：
curl -X POST http://localhost:3000/api/articles \
     -H "Content-Type: application/json" \
     -d '{"author": "赵六"}'

# 预期返回 HTTP 400 Bad Request（示例）：
{
  "status": "fail",
  "message": "字段 title 为必填项且不能为空字符串"
}

4. 验证删除资源 (DELETE)

# 终端执行命令：
curl -i -X DELETE http://localhost:3000/api/articles/1

# 预期返回 HTTP 状态头（响应体为空）：
HTTP/1.1 204 No Content
Date: Sat, 31 Oct 2026 02:00:00 GMT
Connection: keep-alive

七、生产实践建议与常见问题排查

在构建真实的生产级 Node.js 服务时，除了完成 CRUD 基础逻辑外，还需注意以下高频陷阱与优化建议：

1. 为什么 POST/PUT 请求中的 req.body 总是 undefined？

这是初学者最常遇到的问题。根本原因在于客户端请求头未声明 Content-Type: application/json，或者在 Express 路由定义之后才调用 app.use(express.json())。中间件在 Express 中是有严格顺序的，所有的请求解析中间件必须在路由挂载之前注册。

2. 异步路由抛出的异常无法被错误中间件捕获

在 Express 4.x 中，如果路由函数是 async (req, res, next) => { ... }，在函数内部使用 await 抛出的 Promise Rejection 无法被 Express 自动同步拦截。必须在 catch 块中显式调用 next(err)，或者引入 express-async-errors 库进行全局打补丁，以确保所有异步异常能够平稳进入集中错误处理流。

3. 严格禁止“状态码 200 返回业务错误”反模式

部分传统 RPC 接口习惯于无论成功与否均返回 HTTP 200，并在 JSON 中定义 { "code": -1, "msg": "未找到" }。在 RESTful 架构中，这是明确的反模式。HTTP 状态码是 HTTP 协议内置的基础设施，API 网关、浏览器缓存、反向代理（如 Nginx）以及网络监控系统（如 Prometheus、Datadog）均依赖 HTTP 状态码计算服务错误率。坚决使用 4xx 表示客户端错误，5xx 表示服务端错误。

4. 路由拆分与模块化工程组织

当业务模型扩张时，应使用 express.Router() 将各资源路由独立至单独的文件中。例如创建 routes/articleRoutes.js，并在主应用中通过 app.use('/api/v1/articles', articleRouter) 进行挂载，保持代码库的清晰与可维护性。