React / 系统课时

控制器与服务层

控制器与服务层

本课将一个混杂了参数读取、业务判断和数据操作的 Express 路由拆成路由层、控制器层和服务层,并通过依赖注入验证服务逻辑,让每一层只承担明确职责。

学习目标

  • 能区分路由、控制器和服务层的职责
  • 能完成三层代码拆分并保持调用链清晰
  • 能为服务层编写不依赖 HTTP 的单元测试

为什么要拆分

把所有逻辑写在路由回调中,短期看起来直接,但参数校验、状态码、业务规则和数据访问会迅速混在一起。拆分后,路由只负责地址与处理函数的绑定,控制器处理 HTTP 细节,服务层实现可复用的业务规则。

这三层的依赖方向应保持单向:路由调用控制器,控制器调用服务;服务层不应该接触 req、res 或 Express 状态码,否则业务逻辑会被 Web 框架绑死。

Express 路由控制器服务层调用图

建立结构并实现服务层

最小结构可以保持四个文件。这里不额外引入数据库,使注意力集中在职责划分。

text
express-layered-demo/
├── app.js
├── user.controller.js
├── user.routes.js
└── user.service.js

这段内容是目录结构说明,不独立执行。运行时由 app.js 加载路由,路由再引用控制器实例。

服务层接收普通 JavaScript 数据并返回普通对象,不处理 HTTP 请求。构造函数接收数据数组,这种依赖注入方式让测试可以提供独立数据,避免测试之间相互污染。

js
class UserService {
  constructor(users = []) {
    // 注入数据集合,测试时可为每个用例创建独立状态
    this.users = users;
    this.nextId =
      users.reduce((maxId, user) => Math.max(maxId, user.id), 0) + 1;
  }

  list() {
    return this.users;
  }

  create(input) {
    const { name, email } = input;
    // 业务校验留在服务层,避免不同入口重复实现
    if (!name || !email) {
      const error = new Error("name and email are required");
      error.code = "VALIDATION_ERROR";
      throw error;
    }

    const user = { id: this.nextId++, name, email };
    this.users.push(user);
    return user;
  }
}

module.exports = UserService;

这是模块代码,不单独启动。生效行为是:list() 返回当前用户集合,create() 校验必填字段后创建用户;验证方法将在后面的应用运行和单元测试中完成。

编写控制器与路由

控制器把服务层结果转换为 HTTP 响应,并统一处理业务错误。路由文件只声明方法、路径和对应控制器函数。

js
class UserController {
  constructor(userService) {
    this.userService = userService;
  }

  // 控制器只负责把业务结果适配为 HTTP 响应
  list = (req, res) => {
    res.status(200).json(this.userService.list());
  };

  create = (req, res) => {
    try {
      const user = this.userService.create(req.body);
      res.status(201).json(user);
    } catch (error) {
      // 已知业务错误返回 400,未知错误不暴露内部细节
      if (error.code === "VALIDATION_ERROR") {
        return res.status(400).json({ message: error.message });
      }
      res.status(500).json({ message: "Internal server error" });
    }
  };
}

module.exports = UserController;

控制器中的箭头函数用于保留实例的 this。如果改成普通方法并直接传给 Express,可能因调用上下文变化而无法访问 this.userService。

js
const express = require("express");

function createUserRouter(userController) {
  const router = express.Router();

  // 路由层只声明“方法 + 路径 + 处理函数”
  router.get("/", userController.list);
  router.post("/", userController.create);

  return router;
}

module.exports = createUserRouter;

路由模块通过参数接收控制器,而不是在文件内部自行创建依赖,因此应用入口和测试都能替换具体实现。

组装并运行应用

应用入口负责创建服务、控制器和路由,再挂载到 /users。将以下内容保存为 app.js,并确保前面三个文件位于同一目录。

js
const express = require("express");
const UserService = require("./user.service");
const UserController = require("./user.controller");
const createUserRouter = require("./user.routes");

const app = express();
app.use(express.json());

// 应用入口统一组装依赖,其他层不自行创建下游对象
const userService = new UserService([
  { id: 1, name: "Ada", email: "ada@example.com" }
]);
const userController = new UserController(userService);

app.use("/users", createUserRouter(userController));

app.listen(3000, () => {
  console.log("Layered API running at http://localhost:3000");
});

先执行 npm init -y 和 npm install express,再运行:

bash
node app.js

预期输出

text
Layered API running at http://localhost:3000

端口 3000 是示例值,实际运行端口可能是 <PORT>。访问 POST /users 时,请求会按“路由 → 控制器 → 服务”的顺序执行。

测试服务层

服务层不依赖 Express,因此可直接使用 Node.js 内置测试运行器。将下面代码保存为 user.service.test.js。

js
const test = require("node:test");
const assert = require("node:assert/strict");
const UserService = require("./user.service");

test("create should add a valid user", () => {
  const service = new UserService([]);

  // 直接调用服务,不需要伪造 req 和 res
  const user = service.create({
    name: "Grace",
    email: "grace@example.com"
  });

  assert.deepEqual(user, {
    id: 1,
    name: "Grace",
    email: "grace@example.com"
  });
  assert.equal(service.list().length, 1);
});

test("create should reject missing fields", () => {
  const service = new UserService([]);

  // 缺少 email 时应抛出稳定的业务错误
  assert.throws(
    () => service.create({ name: "Grace" }),
    { message: "name and email are required" }
  );
});

运行测试:

bash
node --test user.service.test.js

预期输出(关键行)

text
✔ create should add a valid user
✔ create should reject missing fields
ℹ tests 2
ℹ pass 2
ℹ fail 0

测试耗时和前缀格式可能随 Node.js 版本不同,验收标准是两个测试均通过且失败数为 0。

分层边界与常见错误

控制器可以读取路径参数、请求体和查询参数,也可以设置状态码与响应头;服务层负责业务校验、流程编排和数据操作。数据库访问进一步复杂时,可再引入仓储层,但不必为简单项目过早增加层级。

常见错误包括在服务层直接调用 res.status()、在路由文件堆放业务判断,以及控制器重复实现相同规则。判断职责归属时,可以问:这段代码换成命令行或消息队列入口后是否仍然成立?仍然成立的通常属于服务层。

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

目录与阅读设置

阅读设置

17

记录一个想法

控制器与服务层

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

登录哪都通