Node.js / 系统课时
建立控制器与服务层
建立控制器与服务层
当路由函数同时读取请求、判断业务规则、访问数据并拼响应时,测试和改动会迅速互相牵连。本篇把 HTTP 适配放进控制器,把可复用业务规则放进服务层,并用一个可运行的 Express 5.x 示例验证 200、400 与 404 三种路径。
学习目标
- 明确 Router、Controller 与 Service 各自负责什么。
- 让服务层不依赖 Express 的
req、res对象。 - 用领域错误把业务失败稳定映射成 HTTP 状态码。
先划清三层边界
一个最小 REST 模块可以按 routes/users.js、controllers/user-controller.js、services/user-service.js 拆分。路由只声明方法和路径;控制器把 HTTP 输入转换成普通值并生成响应;服务层只接收普通参数并执行规则。
| 层 | 可以知道 | 不应该知道 |
|---|---|---|
| Router | HTTP 方法、URL、控制器函数 | 业务条件、数据库细节 |
| Controller | req、res、状态码、序列化格式 |
SQL、数据表结构、复杂业务规则 |
| Service | 普通参数、业务规则、领域错误 | Express 的 req、res、路由路径 |

用普通值连接控制器和服务层
下面示例适用于 Node.js 18+ 与 Express 5.x,前置条件是项目依赖中已有 express@5。把代码保存为 app.cjs 即可运行;为便于直接运行,数据暂存在 Map 中;换成数据库时,控制器接口不需要改变,只需把服务内部的数据访问替换为仓储调用。
const express = require('express');
const app = express();
app.use(express.json());
class ServiceError extends Error {
constructor(code, message) {
super(message);
this.code = code;
}
}
const users = new Map([[1, { id: 1, name: 'Ada' }]]);
const userService = {
getById(id) {
const user = users.get(id);
if (!user) {
throw new ServiceError('USER_NOT_FOUND', `user ${id} not found`);
}
return user;
},
rename(id, name) {
const user = userService.getById(id);
const updated = { ...user, name };
users.set(id, updated);
return updated;
}
};
const userController = {
get(req, res, next) {
try {
const id = Number(req.params.id);
if (!Number.isInteger(id) || id < 1) {
return res.status(400).json({ error: { code: 'INVALID_ARGUMENT' } });
}
res.status(200).json({ data: userService.getById(id) });
} catch (err) {
next(err);
}
},
rename(req, res, next) {
try {
const id = Number(req.params.id);
const name = typeof req.body?.name === 'string' ? req.body.name.trim() : '';
if (!Number.isInteger(id) || id < 1 || name.length < 2) {
return res.status(400).json({ error: { code: 'INVALID_ARGUMENT' } });
}
res.status(200).json({ data: userService.rename(id, name) });
} catch (err) {
next(err);
}
}
};
app.get('/users/:id', userController.get);
app.patch('/users/:id', userController.rename);
app.use((err, req, res, next) => {
if (err instanceof ServiceError && err.code === 'USER_NOT_FOUND') {
return res.status(404).json({
error: { code: err.code, message: err.message }
});
}
console.error(err);
res.status(500).json({ error: { code: 'INTERNAL_ERROR' } });
});
const server = app.listen(0, async () => {
const { port } = server.address();
const base = `http://127.0.0.1:${port}`;
const first = await fetch(`${base}/users/1`);
console.log(first.status, await first.text());
const renamed = await fetch(`${base}/users/1`, {
method: 'PATCH',
headers: { 'content-type': 'application/json' },
body: JSON.stringify({ name: 'Grace' })
});
console.log(renamed.status, await renamed.text());
const invalid = await fetch(`${base}/users/0`);
console.log(invalid.status, await invalid.text());
const missing = await fetch(`${base}/users/99`);
console.log(missing.status, await missing.text());
server.close();
});预期输出
200 {"data":{"id":1,"name":"Ada"}}
200 {"data":{"id":1,"name":"Grace"}}
400 {"error":{"code":"INVALID_ARGUMENT"}}
404 {"error":{"code":"USER_NOT_FOUND","message":"user 99 not found"}}控制器只做 HTTP 边界工作:解析 id、检查请求体、选择状态码和 JSON 结构。userService.rename 不接收 req 或 res,所以以后它可以被定时任务、消息消费者或测试代码直接调用。
把业务错误和 HTTP 错误分开
服务层不应返回 res.status(404),因为它不应该知道 HTTP。示例用 ServiceError('USER_NOT_FOUND') 表达业务事实,再由错误处理中间件映射为 404;同一个服务若被 CLI 调用,也可以把该错误映射成退出码而不是 HTTP 状态。
项目规模继续增大时,可在 Service 之后增加 Repository 层,把 Map、SQL 或 ORM 调用隔离出去。检查是否拆对的简单标准是:替换数据库实现时 Controller 无需改动,替换 HTTP 框架时 Service 仍可原样复用。
用两类测试检查分层是否有效
控制器测试关注状态码和响应体,例如非法 id 是否为 400、缺失用户是否为 404;服务测试则直接调用 userService.rename(1, 'Grace'),不启动 HTTP 服务器。两类测试若都能独立编写,说明职责边界基本成立。
实际项目里还可以把成功响应格式固定为 {"data":...},错误固定为 {"error":{"code":...}}。只要 Controller 统一处理传输格式、Service 只处理业务含义,后续加入数据库事务、缓存或消息队列时就不会把 HTTP 细节扩散到核心逻辑。