Controller、Service、Repository 的职责划分

完成一个分层用户接口,并验证替换数据来源时的影响范围

🎯 引言

学完这篇文章,你能把一个用户查询接口分成请求处理、业务处理和数据库查询三部分,知道修改功能时应该改哪里。

🗃 Repository 查询数据库

安装本节需要的依赖:

npm install mysql2@3.11.5

数据库沿用 MySQL 接入课程 的 user 表,使用 id、username 两个字段。先准备数据库连接配置,将可用的连接地址放入环境变量 DATABASE_URL;格式为 mysql://用户名:密码@主机:3306/数据库名,不要将真实凭据提交仓库。

新建 database.mjs,创建连接池。连接池保存一组可重复使用的数据库连接,避免每次请求重新连接:

database.mjs
import mysql from 'mysql2/promise';

if (!process.env.DATABASE_URL) throw new Error('请配置 DATABASE_URL');
export const pool = mysql.createPool(process.env.DATABASE_URL);

新建 user-repository.mjs,只负责查询记录:

user-repository.mjs
import { pool } from './database.mjs';

export async function findUser(id) {
    const [rows] = await pool.execute(
        'SELECT id, username FROM user WHERE id = ?', [id]
    );
    return rows[0] ?? null;
}

问号由参数绑定传入 ID,不能把客户端值直接拼进 SQL。找到时返回数据库记录,未找到返回 null;查询失败则抛出异常。


⚙️ Service 提供业务需要的数据

新建 user-service.mjs:

user-service.mjs
import { findUser } from './user-repository.mjs';

export async function getUserProfile(id) {
    const user = await findUser(id);
    if (!user) return null;
    return { id: user.id, name: user.username };
}

接口约定的字段是 name,数据库字段是 username,Service 在这里转换,并只返回公开字段。后续加入账号状态等业务判断,也放在这层;HTTP 状态码由控制器决定。


🚪 Controller 读取参数并响应

新建 user-controller.mjs:

user-controller.mjs
import { getUserProfile } from './user-service.mjs';

export async function showUser(req, res) {
    const id = Number(req.params.id);
    if (!/^[1-9]\d*$/.test(req.params.id) || !Number.isSafeInteger(id)) {
        return res.status(400).json({ error: '用户 ID 不合法' });
    }
    const user = await getUserProfile(id);
    if (!user) return res.status(404).json({ error: '用户不存在' });
    res.json({ data: user });
}

合法 ID 交给业务函数;查不到返回 404;成功返回 200 和用户资料。数据库失败时异步函数会抛错,由 Express 5 交给错误中间件,控制器不必重复包装 try/catch。


🔗 接到用户查询接口

新建 user-app.mjs,将控制器接到用户查询地址:

user-app.mjs
import express from 'express';
import { showUser } from './user-controller.mjs';
import { errorHandler } from './error-handler.mjs';

export const app = express();
app.get('/users/:id', showUser);
app.use(errorHandler);

请求 /users/1 时,控制器读取 ID,Service 整理返回字段,Repository 查询记录。统一异常篇的错误中间件处理数据库等异常。项目需要拆分多个路由文件时,再使用框架课程介绍的 Router。


🚀 启动并观察结果

新建启动文件:

user-server.mjs
import { app } from './user-app.mjs';

app.listen(3000, '127.0.0.1');

在 .env 配置数据库地址,运行:

node --env-file=.env user-server.mjs

数据库有 ID 为 1、username 为小明的记录时,访问 /users/1 返回 {"data":{"id":1,"name":"小明"}}。不存在的 ID 返回 404,/users/abc 返回 400。

这个查询接口公开读取基础资料。读取私有信息时,应先挂载身份中间件,再由业务层判断当前用户能否访问目标记录。


🔄 分层后怎样修改功能

接口字段改名时,检查 Service 的返回结构;查询表或数据库驱动改变时,修改 Repository;请求参数或响应状态改变时,修改 Controller。

例如更换数据库中的名字字段,只需调整查询或字段转换,接口仍然可以返回原来的 name。先保持对外结果一致,再修改内部数据来源。


❓ 知识问答

Q1:每个简单接口都必须拆成这些文件吗?

不必。需要独立维护业务规则或数据访问时再拆分,避免只有一行转发的空层次。

Q2:Repository 可以直接调用 res.json 吗?

应返回数据,让控制器处理响应,这样数据库访问也能用于后台任务和测试。

Q3:数据库表增加密码字段,会自动返回给前端吗?

本例不会,查询和返回对象都明确选择了公开字段。


🧪 小练习

在测试数据库添加一条用户记录,查询它并核对响应;再访问不存在的 ID,确认返回 404。

// 请在这里记录结果