Express业务接口模块开发：Node.js分层架构与中间件实战

很多刚接触 Node.js 的朋友跟我说，看了一圈 Express 文档之后觉得后端开发不过如此——装个框架、写几个路由、返回一段 JSON，完事了。可等到真要接一个正经的“业务接口模块”，比如用户管理、订单列表、商品查询这类接口，就开始手忙脚乱：参数在哪儿校验、错误怎么统一返回、代码要怎么拆文件、中间件到底按什么顺序挂载，全都含糊。这篇文章想和你聊的，正是这个标题里最容易被忽略的五个字——“业务接口模块”。我会用手把手的方式，基于 Node.js + Express 搭一个用户管理接口模块 Demo，从目录结构、路由设计、控制器与业务层拆分，到参数校验、统一错误处理、中间件鉴权，再到本地启动和自测，完整走一遍。无论你是刚学完 JavaScript 语法想碰后端的新手，还是已经在写前端、想快速验证一个想法的小团队开发者，这篇内容都适配。

1. 先弄明白：什么是“业务接口模块”，以及为什么选 Express

1.1 别把“接口”想简单了

一个接口，本质上是这样一条完整链路：HTTP 请求进来 → 路由定位到对应处理函数 → 解析参数并做校验 → 执行业务逻辑 → 组装统一响应格式 → 返回给调用方。中间任何一环出错，都要有对应的兜底动作。很多新手只盯着“接收请求”和“返回数据”这两步，所以写出来的 Demo 只能跑通，不能真正拿去接业务。

我见过不少项目，最开始功能很少，所有路由和处理逻辑都堆在 app.js 里，两百行、三百行慢慢往上摞。当时觉得挺爽，越短越直接。等到功能一多，要加一个参数校验，得在三个地方各写一遍；要改一个错误提示，得全局搜索替换；要排查一个问题，从上翻到下眼睛都花了。这就是“能跑”和“能用”之间的差别。

1.2 Express 的取舍：自由度过高，更需要约定

选 Express，不是因为它功能最全，而是因为它足够轻、足够稳、资料足够多。Express 的核心机制是中间件，灵活度非常高，你想怎么组织代码都可以。但硬币的另一面是：它不像某些重量级框架那样强制约束你“必须按什么结构写”，反而对开发者的自律提出了要求。

如果你没有提前定好目录结构和调用约定，Express 项目很容易写成“大杂烩”。反过来，只要你在工程结构上稍微花点心思，Express 提供的 Router、中间件、错误处理机制，足以支撑一个中等规模的后端服务。对比 Koa 和 Fastify，Koa 的中间件模型更优雅，Fastify 的性能更好，但 Express 的生态最成熟、踩坑经验最多。对于一个“快速构建 Demo 并验证业务逻辑”的场景，Express 是不需要纠结的选择。

1.3 这个 Demo 要实现的目标

为了让内容不飘在空中，我给这个 Demo 定一个非常明确的业务场景：用户管理模块。包含五个接口：

• 用户列表（支持分页和关键词搜索）
• 用户详情
• 新增用户
• 修改用户信息
• 删除用户

听着不难，但我会用真实工程化的方式去写：路由单独一个文件、控制器单独一个文件、业务逻辑单独一层、数据存储单独一层。这样做的好处是，后面哪怕你要把内存数据换成 MySQL，也只需要动一个文件，这是很多新手项目做不到的。

2. 初始化工程与目录结构设计：把代码放对位置，比写代码更重要

2.1 环境准备和依赖安装

先说环境。Node.js 版本建议用 18 或更高，我本地用的是 20 LTS。Node 18.11 之后自带 node --watch 热重载能力，开发时不需要额外装 nodemon，这一点后面会用到。

bash复制node -v
npm init -y
npm install express

一个容易忽略的知识点：Express 4.16 版本之后，内置了 express.json() 和 express.urlencoded() 两个中间件，用来解析 JSON 请求体和表单请求体，不需要再单独安装 body-parser 包了。很多老教程里还在让你装 body-parser，实际完全没必要。

2.2 推荐的目录结构

初始化完成后，建议按下面的结构组织代码：

code复制demo-project/
├── package.json
├── .gitignore
└── src/
    ├── app.js                 # 应用入口，负责创建服务、挂载中间件和路由
    ├── config/
    │   └── index.js           # 端口、常量、配置项集中管理
    ├── routes/
    │   └── userRouter.js      # 用户模块路由定义
    ├── controllers/
    │   └── userController.js  # 控制器层：取参、校验、调服务、返回响应
    ├── services/
    │   └── userService.js     # 业务逻辑层：数据过滤、分页计算、规则判断
    ├── models/
    │   └── userModel.js       # 数据层：和存储打交道的地方
    ├── middlewares/
    │   ├── authMiddleware.js  # 鉴权中间件
    │   └── loggerMiddleware.js # 日志中间件
    └── utils/
        ├── response.js        # 统一响应格式工具
        └── validate.js        # 轻量参数校验工具

这个分层结构不是拍脑袋定的，每一层只做一件事，依赖关系是单向的：路由层依赖控制器，控制器依赖服务层，服务层依赖数据层。别搞成循环引用，也别跳过某一层直接到底。这样做最大的收益是“可替换性”——以换数据库为例，只要数据层对外提供的函数签名不变，上层代码一行都不用改。

2.3 配置 npm scripts

package.json 里配置好启动命令：

json复制"scripts": {
  "start": "node src/app.js",
  "dev": "node --watch src/app.js"
}

开发时 npm run dev 启动，改代码自动重启；生产环境用 npm start。相比 nodemon，node --watch 零依赖，实测稳定够用。

3. 实现用户管理模块：从路由到数据的完整链路

3.1 接口设计先于编码

动手写代码前，先把接口定义清楚。这一步在真实项目里叫“接口设计”，前后端要一起对齐的。我的用户模块接口设计如下：

路径统一以 /api 为前缀，方便后面做版本控制（如迁到 /api/v1）和统一鉴权。HTTP 方法语义也符合 RESTful 风格：GET 查、POST 增、PUT 改、DELETE 删。这个约定不仅是写给自己看的，更是给调用方看的。

3.2 路由层：只做转发，不带逻辑

路由层尽量保持简洁，它只解决一个问题：当用户访问某个 URL、用某种 HTTP 方法时，应该把请求交给谁。

javascript复制// src/routes/userRouter.js
const express = require('express');
const userController = require('../controllers/userController');
const authMiddleware = require('../middlewares/authMiddleware');

const router = express.Router();

// 列表和详情接口，所有访问者都可以调用
router.get('/', userController.list);
router.get('/:id', userController.detail);

// 新增和删除接口需要有鉴权，演示路由级中间件的用法
router.post('/', authMiddleware, userController.create);
router.delete('/:id', authMiddleware, userController.remove);

// 更新接口
router.put('/:id', userController.update);

module.exports = router;

注意我在 GET 接口上没有挂鉴权中间件，而 POST 和 DELETE 挂了，这是故意为之。真实项目里，不同的路由本来就有不同的安全级别：有的接口需要登录才能访问，有的接口是开放给游客的。通过路由级中间件可以非常灵活地做到“按需鉴权”。

3.3 控制器层：薄一点，再薄一点

控制器不要塞业务逻辑。它只做三件事：从请求里拿参数、调用服务层方法、用统一格式返回响应。这个准则我在代码评审里反复强调，因为控制器一旦厚起来，和路由层耦合就会变重，后面想复用业务逻辑根本无从下手。

javascript复制// src/controllers/userController.js
const userService = require('../services/userService');
const { success, fail } = require('../utils/response');
const { validateCreateUser, validateUpdateUser } = require('../utils/validate');

exports.list = async (req, res, next) => {
  try {
    const { page = 1, pageSize = 10, keyword = '' } = req.query;
    const data = userService.getUserList({
      page: Number(page) || 1,
      pageSize: Math.min(Number(pageSize) || 10, 50),
      keyword: String(keyword).trim()
    });
    res.json(success(data));
  } catch (err) {
    next(err);
  }
};

exports.detail = async (req, res, next) => {
  try {
    const id = Number(req.params.id);
    if (!Number.isInteger(id) || id <= 0) {
      return res.status(400).json(fail(10001, '非法用户ID'));
    }
    const data = userService.getUserById(id);
    if (!data) {
      return res.status(404).json(fail(40401, '用户不存在'));
    }
    res.json(success(data));
  } catch (err) {
    next(err);
  }
};

exports.create = async (req, res, next) => {
  try {
    const errors = validateCreateUser(req.body);
    if (errors.length) {
      return res.status(400).json(fail(10001, errors.join('；')));
    }
    const user = userService.createUser(req.body);
    res.status(201).json(success(user));
  } catch (err) {
    next(err);
  }
};

exports.update = async (req, res, next) => {
  try {
    const id = Number(req.params.id);
    const errors = validateUpdateUser(req.body);
    if (errors.length) {
      return res.status(400).json(fail(10001, errors.join('；')));
    }
    const data = userService.updateUser(id, req.body);
    if (!data) {
      return res.status(404).json(fail(40401, '用户不存在'));
    }
    res.json(success(data));
  } catch (err) {
    next(err);
  }
};

exports.remove = async (req, res, next) => {
  try {
    const id = Number(req.params.id);
    const ok = userService.deleteUser(id);
    if (!ok) {
      return res.status(404).json(fail(40401, '用户不存在'));
    }
    res.json(success(null, '删除成功'));
  } catch (err) {
    next(err);
  }
};

每个处理函数都包了一层 try/catch，并调用 next(err)，这是后面统一错误处理得以生效的前提。你现在可能觉得重复，但等你在真实项目里遇到了“异步错误被 Express 吞掉”的诡异问题，就会明白这层 try/catch 是保护伞。

3.4 服务层：业务逻辑的归宿

服务层，也叫业务逻辑层，是处理规则的地方。比如分页计算、关键词过滤、昵称是否重复、删除是否存在，这些都应该在 service 里。

javascript复制// src/services/userService.js
const userModel = require('../models/userModel');

exports.getUserList = ({ page = 1, pageSize = 10, keyword = '' }) => {
  let list = userModel.findAll();
  const kw = keyword.toLowerCase();

  if (kw) {
    list = list.filter(item =>
      item.username.toLowerCase().includes(kw) ||
      (item.email && item.email.toLowerCase().includes(kw))
    );
  }

  const total = list.length;
  const start = (page - 1) * pageSize;
  const items = list.slice(start, start + pageSize);

  return { list: items, total, page, pageSize };
};

exports.getUserById = (id) => {
  return userModel.findById(id);
};

exports.createUser = ({ username, email, age }) => {
  return userModel.create({ username, email, age: age === undefined ? null : age });
};

exports.updateUser = (id, payload) => {
  return userModel.update(id, payload);
};

exports.deleteUser = (id) => {
  return userModel.remove(id);
};

服务层调用数据层时，传参用的是普通对象，返回的也是普通对象，不暴露存储细节。以后就算换成数据库，controller 的代码一行都不用改，只要 service 内部调整即可。

3.5 数据层：先用内存存储，跑通再说

Demo 阶段我用一个数组模拟数据库，足够验证整个接口链路。数据层只暴露四个方法：查询全部、按 ID 查询、新增、修改、删除。

javascript复制// src/models/userModel.js
// 说明：当前使用内存数组模拟数据库，仅用于 Demo 阶段。
// 正式项目请替换为 MySQL / MongoDB 等真实存储，保持本文件对外方法签名不变即可。
let users = [];
let nextId = 1;

const findAll = () => [...users];

const findById = (id) => users.find(item => item.id === id) || null;

const create = ({ username, email, age }) => {
  const user = { id: nextId++, username, email, age, createdAt: Date.now() };
  users.push(user);
  return user;
};

const update = (id, payload) => {
  const index = users.findIndex(item => item.id === id);
  if (index === -1) return null;
  users[index] = { ...users[index], ...payload, id: users[index].id };
  return users[index];
};

const remove = (id) => {
  const index = users.findIndex(item => item.id === id);
  if (index === -1) return false;
  users.splice(index, 1);
  return true;
};

module.exports = { findAll, findById, create, update, remove };

3.6 统一响应格式：和前端约定一件事

接口的响应体我统一使用 { code, message, data } 结构。code 为 0 代表成功，非 0 代表业务错误码。注意：业务 code 和 HTTP 状态码是两回事。HTTP 状态码负责传输层面的语义，业务 code 负责业务层面的语义，二者不要混为一谈。

javascript复制// src/utils/response.js
exports.success = (data = null, message = 'success') => ({ code: 0, message, data });

exports.fail = (code, message) => ({ code, message, data: null });

优点是什么？前端拿到响应后，可以统一判断 code !== 0 再弹出错误提示，而不需要去匹配 400、404、500 这些状态码。尤其遇到“登录过期”这类业务状态（比如 code 为 40101），前端可以写一套全局的拦截逻辑，直接跳到登录页，不需要每个接口单独处理。

4. Express 中间件机制：理解它，你才真正会用 Express

4.1 中间件到底是个什么东西

最简单的理解：中间件就是普通的函数，接受 req、res、next 三个参数。它可以做任何事——改 req 上的字段、判断请求条件、直接返回响应，或者说一句“这事我处理不了，交给下一个”。

网上管这叫“洋葱模型”，听起来玄乎。实际可以类比成快递流水线上的分拣台：包裹从一端进来，经过一个个工位，每个工位只做自己的事，有的检查重量、有的贴标签，最后到达出口。如果某个工位发现包裹有问题，可以直接标记异常，不让它继续走。

4.2 自己实现一个日志中间件

我不想为了日志功能单独引入一个 morgan 依赖，直接手写一个几十行的中间件，反而更清楚原理。

javascript复制// src/middlewares/loggerMiddleware.js
module.exports = (req, res, next) => {
  const start = Date.now();
  res.on('finish', () => {
    const cost = Date.now() - start;
    console.log(`${req.method} ${req.originalUrl} ${res.statusCode} ${cost}ms`);
  });
  next();
};

关键点在于 res.on('finish') 这个事件。它表示响应已经发送完成，此时再统计耗时才是准确的数据。如果在中间件里直接 console.log，打印的是“请求刚开始”的时间点，状态码也还没渲染出来，日志是残缺的。这个小细节是我在某次排查线上接口耗时问题时才注意到的。

4.3 挂载顺序：中间件最大的坑

中间件的执行顺序，完全取决于挂载顺序。也就是说，你在代码里先 app.use(某中间件)，它就先执行。最常见的坑有两个：

第一个坑：app.use(express.json()) 必须放在所有需要读取请求体的路由之前。否则请求体解析还没执行，路由里 req.body 就是 undefined，而且不会报错，只会产生极其隐蔽的 bug。

第二个坑：next() 必须被调用，否则请求会卡死在这里。这一点很多新手搞不懂，明明控制台什么都没打，接口就是不返回。其实就是某个中间件里只做了判断，却忘了调 next()，流水线卡在工位上了。

4.4 手写一个鉴权中间件

鉴权是业务接口模块里几乎离不开的需求。这里用固定 token 做演示，生产环境应该替换为规范的 JWT 校验方案。

javascript复制// src/middlewares/authMiddleware.js
const TOKEN = 'demo-token-123';

module.exports = (req, res, next) => {
  const auth = req.headers['authorization'] || '';

  if (auth === `Bearer ${TOKEN}`) {
    next();
    return;
  }

  res.status(401).json({ code: 40101, message: '未授权或 token 无效', data: null });
};

这个中间件的价值在于：它被插到 POST /api/users 和 DELETE /api/users/:id 上之后，这两个接口就被保护起来了。没有携带合法 token 的请求会直接收到 40101 的错误码，不会到达业务逻辑层。以后要换 JWT、OAuth 或者更复杂的权限体系，你只需要改这一个文件，所有挂载了它的路由都生效。

5. 参数校验与统一错误处理：让接口面对脏数据时依然体面

5.1 为什么必须做参数校验

很多人图省事，前端传什么后端就存什么，结果出现了年龄字段传字符串、邮箱传成空数组、用户名传成超长文本这些脏数据。一旦接入数据库，这些脏数据就会一直躺在表里，清理成本远高于校验成本。

可以类比成收银台：收银员收到钱的时候不验钞，等出了柜台才发现收到假币，就晚了。参数校验就是入口处的防伪检测，宁可在这里多花几条 if 语句，也别让错误数据进入业务层。

5.2 手写一个轻量校验函数

为不引入额外依赖，我手写一个轻量校验工具。真实项目如果参数很多，建议用 zod 或 joi 这类声明式校验库，但原理和这里做的事情是一样的。

javascript复制// src/utils/validate.js
exports.validateCreateUser = (body = {}) => {
  const errors = [];

  if (!body.username || typeof body.username !== 'string') {
    errors.push('username 必填且必须是字符串');
  } else if (body.username.trim().length < 2 || body.username.trim().length > 20) {
    errors.push('username 长度需在 2-20 个字符之间');
  }

  if (body.email !== undefined) {
    const emailReg = /^[\w.-]+@[\w-]+\.[\w.-]+$/;
    if (typeof body.email !== 'string' || !emailReg.test(body.email)) {
      errors.push('email 格式不正确');
    }
  }

  if (body.age !== undefined) {
    const age = Number(body.age);
    if (Number.isNaN(age) || age < 0 || age > 150) {
      errors.push('age 必须是 0-150 之间的数字');
    }
  }

  return errors;
};

exports.validateUpdateUser = (body = {}) => {
  if (!body || typeof body !== 'object') return ['请求体必须是对象'];
  return exports.validateCreateUser(body);
};

加入校验后，控制器里先校验再调用业务方法，错误请求在入口就被拦截，返回给调用方的是明确的错误提示，而不是一串堆栈。

5.3 自定义错误与统一错误处理中间件

只有统一的响应格式还不够，错误也要有统一的归口。我先定义了一个 AppError 类，用它来承载业务错误码、错误信息和对应的 HTTP 状态码：

javascript复制// src/utils/error.js
class AppError extends Error {
  constructor(code, message, status = 400) {
    super(message);
    this.code = code;
    this.status = status;
    this.name = 'AppError';
  }
}

module.exports = { AppError };

然后在 app.js 的最后，也就是所有路由之后，挂载错误处理中间件。Express 判断错误中间件的标志是：函数必须有四个参数 err, req, res, next，少一个都不行，少一个 Express 就当普通中间件处理。

javascript复制// src/app.js 末尾部分
app.use((err, req, res, next) => {
  if (err instanceof AppError) {
    return res.status(err.status).json(fail(err.code, err.message));
  }

  console.error('【未捕获错误】', err);
  res.status(500).json(fail(50000, '服务器内部错误'));
});

你会发现，控制器里所有 next(err) 传进来的错误，最终都会汇聚到这里。业务代码里不需要到处写 res.status(500).json(...)，错误处理收敛在一个地方，想改统一文案、上报监控、打日志都方便。

5.4 404 兜底与异步异常陷阱

接口路径不存在怎么办？在错误处理中间件之前，加一个 404 兜底：

javascript复制app.use((req, res) => {
  res.status(404).json(fail(40400, '资源不存在'));
});

注意这里不要再 next() 一个错误，因为 URL 不存在本身不是系统故障，直接返回 404 业务响应即可，否则它会被错误中间件当作 500 处理，日志里天天刷红。

最后说一个 Express 4 的老坑：async/await 里抛出的异常不会自动流入错误处理中间件。Express 4 内部对异步函数的错误捕获不完整，你在 async 控制器里直接 await 一个会 reject 的 Promise，如果不手动 try/catch 再 next(err)，异常会被直接吞掉，接口永远处于 pending 状态，排错会非常痛苦。Express 5 修复了这个行为，但当前生产环境大量项目还停留在 Express 4.x，所以我在 controller 里统一用 try { ... } catch (err) { next(err); } 的结构来规避。

6. 启动、自测与后续演进：从“能跑的 Demo”变成“可维护的模块”

6.1 入口文件与启动

把所有部分拼起来，app.js 看起来就像这样：

javascript复制// src/app.js
const express = require('express');
const userRouter = require('./routes/userRouter');
const loggerMiddleware = require('./middlewares/loggerMiddleware');
const { fail } = require('./utils/response');

const app = express();

// 全局中间件：解析 JSON 请求体，注意顺序要放在路由之前
app.use(express.json());
app.use(loggerMiddleware);

// 业务路由
app.use('/api/users', userRouter);

// 404 兜底
app.use((req, res) => {
  res.status(404).json(fail(40400, '资源不存在'));
});

// 统一错误处理
app.use((err, req, res, next) => {
  if (err instanceof AppError) {
    return res.status(err.status).json(fail(err.code, err.message));
  }
  console.error('【未捕获错误】', err);
  res.status(500).json(fail(50000, '服务器内部错误'));
});

app.listen(3000, () => {
  console.log('接口服务已启动：http://localhost:3000');
});

端口建议从 process.env.PORT 读取，代码里给一个默认值，这样部署到云平台时可以直接注入环境变量，不用改代码。

6.2 用 curl 把接口全部测一遍

启动 npm run dev 后，开一个终端，按下面的顺序实测：

bash复制# 1. 用户列表
curl http://localhost:3000/api/users

# 2. 新增用户（注意带上鉴权头）
curl -X POST http://localhost:3000/api/users \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer demo-token-123' \
  -d '{"username":"test01","email":"test01@example.com","age":20}'

# 3. 用户详情
curl http://localhost:3000/api/users/1

# 4. 修改用户
curl -X PUT http://localhost:3000/api/users/1 \
  -H 'Content-Type: application/json' \
  -d '{"username":"test01_updated","age":21}'

# 5. 删除用户
curl -X DELETE http://localhost:3000/api/users/1 \
  -H 'Authorization: Bearer demo-token-123'

预期行为是：列表返回包含 total 的分页结构；新增返回 code: 0 且带自增 id；访问不存在的用户返回 40401 错误码；不带 token 调用新增接口返回 40101。全测通过，这个 Demo 就真正跑通了。

6.3 从 Demo 走向可维护模块的几个演进方向

作为一篇讲“快速构建”的文章，最后把 Demo 阶段的决策和进阶方向放在一张表里，方便你按需参考：

跨域问题也值得一提。如果你的接口模块要给浏览器里的前后端分离项目调用，记得装 cors 中间件，并在 app.js 里 app.use(require('cors')())。这个配置放在所有业务路由之前。

最后分享两个我在实际项目里养成的习惯。第一个：开工前先和前端对齐响应格式，也就是上面说的 code/message/data 结构。很多时候报错都不是逻辑问题，而是前端按 A 结构解析、后端返回 B 结构，联调时互相甩锅。这个约定一定在写码前定好，而不是等接口写完再补。第二个：所有分页接口，pageSize 一定要设上限。我在这个 Demo 里就写死了最大 50条。这个坑是我自己踩过的——当时没限制，某次数据量变大，前端同学一页拉了一万条数据，接口直接超时，数据库连接也被打满。后来在代码规范里加了条硬性要求：列表接口默认不返回全量，必须分页，且每页大小必须封顶。希望你别再踩一遍。