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、路由路径

REST API 从路由到控制器、服务层和数据层的职责关系

用普通值连接控制器和服务层

下面示例适用于 Node.js 18+ 与 Express 5.x,前置条件是项目依赖中已有 express@5。把代码保存为 app.cjs 即可运行;为便于直接运行,数据暂存在 Map 中;换成数据库时,控制器接口不需要改变,只需把服务内部的数据访问替换为仓储调用。

js
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();
});

预期输出

text
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 细节扩散到核心逻辑。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

建立控制器与服务层

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通