Express 的项目结构之所以会烂,不是因为文件多,而是因为没人管「谁可以 import 谁」。它不像 Nest 自带模块系统,也不像 Spring Boot 有包扫描约定,app.get('/xxx', handler) 一行就能上生产,于是所有东西都往 app.js 里塞。这篇给一套五层骨架、三条单向依赖规则,外加一个零依赖的脚本,让 CI 替你守住边界。
目录
- 一、先说结论:结构问题本质是依赖方向问题
- 二、为什么 Express 特别容易长成一坨
- 三、五层骨架:每层只做什么
- 四、完整目录树
- 五、把 app.js 和 server.js 拆开
- 六、依赖只能单向
- 七、完整可运行代码
- 八、让机器守边界:一份校验脚本
- 九、技术分层还是按功能切块
- 十、症状、原因、解法
一、先说结论:结构问题本质是依赖方向问题
判断一个 Express 项目的结构好不好,别数目录,问一个更狠的问题:改一个接口的业务规则,需要碰几个文件?
如果你的答案里包含「打开 app.js 找到那个路由,往下翻两百行改 if」,那这个项目没有结构,只有文件摆放顺序。真正可维护的结构,是把一次请求拆成几段互不越界的处理,并且每段的依赖方向固定下来------路由只知道控制器,控制器只知道服务,服务只知道仓储,谁也看不见上一层。
这套骨架我在 Node 24 + Express 5.1 上完整跑过一遍,八个小文件、一个零依赖校验脚本,下面全部代码可以直接复制运行。
二、为什么 Express 特别容易长成一坨
Express 的设计哲学是「极简、不预设」,社区文章里反复出现的就是 routes/、controllers/、services/、models/ 这几个目录名,但 没有任何一条强制约束。共识很清楚,问题在于共识不会自动生效。
于是最常见的退化路径是这样的:
- 一开始
app.js里几个路由,够用; - 业务变复杂,加个
controllers/,但 controller 里顺手写了 SQL; - 又有人要复用这段逻辑,就在 controller 里
import另一个 controller,最后两个文件互相依赖,环成了,谁也不敢动。
类比一下:这就像厨房里没有灶台分区,切菜、炒菜、装盘全在同一块台面上,人一多就开始互相挡手。分层不是为了让目录好看,是为了让每个人 只需要知道上下游是谁,不必记住全部。
三、五层骨架:每层只做什么
| 层 | 只做 | 绝不做 | 典型文件 |
|---|---|---|---|
| router 路由 | 声明 URL 与处理函数的映射 | 取参数、写逻辑、碰数据库 | user.routes.js |
| controller 控制层 | 从 req 取输入、调 service、组装 res |
写业务规则、写 SQL、做数据校验 | user.controller.js |
| service 业务层 | 校验、编排规则、抛业务错误 | 出现 req / res / express |
user.service.js |
| repository 仓储层 | 增删改查,隔离 ORM / SQL | 判断「该不该」「合不合法」 | user.repository.js |
| model / schema | 描述数据结构与类型 | 承载流程控制 | user.schema.js |
这张表最容易被违反的是 service 和 repository 之间的分工。举个真实的分歧点:「邮箱不能重复」这条规则放哪?
放 repository 是错的------仓储只负责「按 email 查有没有人」,它不知道「有就不能建」这意味着什么;放 service 才对,因为这是业务规则。判断方法很简单:换一个存储实现(Postgres 换成 Mongo),这条规则还在不在? 在,就是业务规则;不在,才是数据访问细节。
四、完整目录树
bash
express-clean/
├── package.json
├── server.js # 进程入口,只负责 listen 与优雅退出
├── scripts/
│ └── check-layers.mjs # 零依赖的分层边界校验器
└── src/
├── app.js # 组装中间件与路由,不 listen
├── routes/
│ └── user.routes.js
├── controllers/
│ └── user.controller.js
├── services/
│ └── user.service.js
├── repositories/
│ └── user.repository.js # 换数据库只改这一层
├── middlewares/
│ └── error-handler.js # 4 个参数的错误中间件
└── errors/
└── app-error.js # 带状态码与错误码的业务异常
三个刻意的取舍,值得单独说:
app.js 和 server.js 分开。 前者只组装应用、导出 app;后者才 listen。这样写测试时可以直接 import app 用 supertest 打请求,不用真的占端口,也不会因为端口被占用导致测试挂掉。
errors/ 单独成目录。 业务异常是跨层契约:service 抛出 AppError(409, 'EMAIL_TAKEN'),error middleware 统一转 HTTP 响应,前端按 code 分支。没有这个类型,service 只能返回 { ok: false } 这类鸭子类型,层层判断。
没有 utils/。 一个 helpers 文件里同时躺着日期格式化、JWT 签名和数组去重时,它已经没有边界可言。需要工具函数时,让它跟着使用它的那一层走。
五、把 app.js 和 server.js 拆开
Express 5 在这件事上顺手给了两个便利,都不是新 API,而是行为修正。
第一,async 处理函数里抛错或 reject,会自动交给错误中间件 ,等价于手动调 next(err)。Express 4 时代必须给每个 async 路由套 asyncHandler(fn) 包装器,否则一次未捕获的 rejection 轻则请求挂死、重则进程退出。升级到 5 之后,包装器可以整个删掉。
第二,app.listen 的启动错误走回调参数,不再抛异常。端口被占用时,错误作为第一个参数传进回调,必须显式判断:
js
const server = app.listen(port, (err) => {
if (err) {
console.error('启动失败:', err.message);
process.exit(1);
}
console.log(`listening on http://localhost:${port}`);
});
这两个变化对结构的影响是:server.js 现在真的只管进程生命周期,app.js 只管应用组装,两者职责不再混。
六、依赖只能单向
三条规则,一条都不能松:
- controller 不许 import repository。 一旦允许,service 就被架空,业务规则会分裂到两个地方,改一次需求得改两处。
- service 不许出现
req/res/express。 service 是纯业务函数,入参是普通对象,出参是实体或抛错。出现req.body说明它被 HTTP 污染了,换 CLI 或消息队列触发时就得重写一遍。 - repository 不许做业务判断。 它只回答「查到了什么」,不回答「要不要抛 409」。
反例长什么样?很常见的一种:
js
// ❌ controller 直接查库,service 形同虚设
export async function getUser(req, res) {
const user = await db.query('SELECT * FROM users WHERE id = $1', [req.params.id]);
if (!user) return res.status(404).json({ message: 'not found' });
res.json(user);
}
这段代码能跑,但业务规则藏在了 SQL 和 if 之间,既没法单测(要连库),也没法复用(要构造 req、res)。
七、完整可运行代码
把下面八个文件放进同一个目录,npm i express@5 之后 node server.js 就能跑。仓储用的是内存数组,所以不需要数据库;换成 Prisma 或 pg 时只改 repository 一个文件。
js
// src/errors/app-error.js
export class AppError extends Error {
constructor(status, code, message) {
super(message);
this.name = 'AppError';
this.status = status; // error middleware 据此映射状态码
this.code = code; // 前端按 code 分支,不解析文案
}
}
js
// src/repositories/user.repository.js ------ 只做数据存取
const users = [{ id: 1, name: 'Ada', email: 'ada@example.com' }];
let nextId = 2;
export const findById = (id) => users.find((u) => u.id === Number(id)) ?? null;
export const findByEmail = (email) => users.find((u) => u.email === email) ?? null;
export const findAll = () => [...users];
export function insert({ name, email }) {
const user = { id: nextId, name, email };
nextId += 1;
users.push(user);
return user;
}
js
// src/services/user.service.js ------ 业务规则都在这,不碰 req/res
import { AppError } from '../errors/app-error.js';
import * as userRepository from '../repositories/user.repository.js';
export function getUserById(id) {
const user = userRepository.findById(id);
if (!user) throw new AppError(404, 'USER_NOT_FOUND', `user ${id} 不存在`);
return user;
}
export const listUsers = () => userRepository.findAll();
export function createUser({ name, email }) {
if (!name || !email) throw new AppError(400, 'VALIDATION_FAILED', 'name 与 email 必填');
if (!String(email).includes('@')) throw new AppError(400, 'VALIDATION_FAILED', 'email 格式不正确');
if (userRepository.findByEmail(email)) throw new AppError(409, 'EMAIL_TAKEN', 'email 已被占用');
return userRepository.insert({ name, email });
}
js
// src/controllers/user.controller.js ------ 只做 HTTP 翻译
import * as userService from '../services/user.service.js';
export function getUser(req, res) {
res.json({ data: userService.getUserById(req.params.id) });
}
export function listUsers(req, res) {
res.json({ data: userService.listUsers() });
}
export function createUser(req, res) {
res.status(201).json({ data: userService.createUser(req.body ?? {}) });
}
js
// src/routes/user.routes.js
import { Router } from 'express';
import * as userController from '../controllers/user.controller.js';
const router = Router();
router.get('/', userController.listUsers);
router.get('/:id', userController.getUser);
router.post('/', userController.createUser);
export default router;
js
// src/middlewares/error-handler.js ------ 必须写满 4 个参数,否则不会被当作错误中间件
import { AppError } from '../errors/app-error.js';
export function errorHandler(err, req, res, next) { // eslint-disable-line no-unused-vars
if (err instanceof AppError) {
return res.status(err.status).json({ error: { code: err.code, message: err.message } });
}
console.error('[unhandled]', err);
return res.status(500).json({ error: { code: 'INTERNAL_ERROR', message: '服务器内部错误' } });
}
js
// src/app.js ------ 组装应用,不 listen
import express from 'express';
import userRoutes from './routes/user.routes.js';
import { errorHandler } from './middlewares/error-handler.js';
const app = express();
app.use(express.json());
app.get('/health', (req, res) => res.json({ ok: true })); // 部署探针
app.use('/api/users', userRoutes);
app.use((req, res) => res.status(404).json({ error: { code: 'NOT_FOUND', message: '路由不存在' } }));
app.use(errorHandler); // 错误中间件必须放最后
export default app;
js
// server.js ------ 只负责启动与优雅退出
import app from './src/app.js';
const port = Number(process.env.PORT ?? 3000);
const server = app.listen(port, (err) => {
if (err) {
console.error('启动失败:', err.message);
process.exit(1);
}
console.log(`listening on http://localhost:${port}`);
});
const shutdown = (signal) => {
console.log(`收到 ${signal},准备退出`);
server.close(() => process.exit(0)); // 等在途请求处理完再退
};
process.on('SIGTERM', () => shutdown('SIGTERM'));
process.on('SIGINT', () => shutdown('SIGINT'));
package.json 里记得加 "type": "module" 和 "express": "^5.1.0"。跑起来后实测输出是这样的:
bash
GET /api/users → {"data":[{"id":1,"name":"Ada","email":"ada@example.com"}]}
GET /api/users/1 → {"data":{"id":1,"name":"Ada","email":"ada@example.com"}}
POST /api/users → 201 {"data":{"id":2,"name":"Bob","email":"bob@example.com"}}
POST 重复 email → 409 {"error":{"code":"EMAIL_TAKEN",...}}
GET /api/users/999 → 404 {"error":{"code":"USER_NOT_FOUND",...}}
注意 409 和 404 是 service 抛的、middleware 转的,controller 里一行错误处理都没写。 错误路径也是结构的一部分,不该散落在每个 handler 的 if 里。
八、让机器守边界:一份校验脚本
规则写在文档里没人看。下面这个脚本零依赖,只用 Node 内置模块,扫一遍 src/ 里所有 import,发现越层就退出码 1,直接挂 CI。
js
// scripts/check-layers.mjs
import { readdirSync, readFileSync, statSync } from 'node:fs';
import { join, relative, dirname, resolve } from 'node:path';
import { fileURLToPath } from 'node:url';
const root = resolve(dirname(fileURLToPath(import.meta.url)), '..');
const srcDir = join(root, 'src');
// 每层禁止依赖的目标,命中即违规
const FORBIDDEN = {
controllers: ['repositories/', 'express'],
services: ['controllers/', 'express'],
repositories: ['services/', 'controllers/', 'express'],
routes: ['repositories/', 'services/'],
};
const walk = (dir) => readdirSync(dir).flatMap((name) => {
const full = join(dir, name);
if (statSync(full).isDirectory()) return walk(full);
return /\.(js|mjs)$/.test(name) ? [full] : [];
});
const importsOf = (code) => {
const out = [];
const patterns = [
/(?:import|export)[^'"]*?from\s*['"]([^'"]+)['"]/g, // import x from '...'
/import\s*\(\s*['"]([^'"]+)['"]\s*\)/g, // 动态 import
/require\s*\(\s*['"]([^'"]+)['"]\s*\)/g, // CJS
];
for (const re of patterns) for (const m of code.matchAll(re)) out.push(m[1]);
return out;
};
const violations = [];
for (const file of walk(srcDir)) {
const rel = relative(srcDir, file).replace(/\\/g, '/');
const layer = rel.split('/')[0];
const rules = layer === 'app.js' ? ['repositories/', 'services/'] : FORBIDDEN[layer] ?? [];
for (const spec of importsOf(readFileSync(file, 'utf8'))) {
if (!spec.startsWith('.')) continue; // 只看相对路径
const target = relative(srcDir, resolve(dirname(file), spec)).replace(/\\/g, '/');
const hit = rules.find((bad) => target.startsWith(bad));
if (hit) violations.push(`${rel} -> ${target}(禁止依赖 ${hit})`);
}
}
if (violations.length) {
console.error(`发现 ${violations.length} 处越层依赖:`);
violations.forEach((v) => console.error(' -', v));
process.exit(1);
}
console.log('分层边界检查通过 ✅');
我在干净工程上跑输出是 分层边界检查通过 ✅;随后故意在 controller 顶部加了一行 import * as bad from '../repositories/user.repository.js',脚本立刻报 controllers/user.controller.js -> repositories/user.repository.js(禁止依赖 repositories/),退出码 1。这条规则进了 npm run check:layers 之后,新人第一次 PR 就会撞上,比 code review 里靠人记靠谱得多。
九、技术分层还是按功能切块
社区里一直有两派:一派按 controllers/、services/ 平铺切,一派按 modules/user/、modules/order/ 纵向切。两派都能成功,选错的代价却不一样。
| 方案 | 形态 | 适合 | 什么时候会疼 |
|---|---|---|---|
| 技术分层 | controllers/ services/ 全项目平铺 |
接口数 20 以内、团队 1--3 人 | 文件一多,改一个功能要横跨四个目录 |
| 按功能纵向 | modules/user/ 内自带 controller/service/repository |
中型以上、多人并行开发 | 跨模块共用逻辑时,容易互相 import 成环 |
| 混合 | 顶层按功能切,层内再分层 | 绝大多数企业项目 | 边界变多,必须靠脚本或 lint 守 |
我的判断标准还是开头那句:改一个功能要碰几个目录。 每次需求都要在四个平铺目录里各改一个文件时,就该往纵向切;切完之后模块之间互相 import 的风险会上升,这时脚本要扩一条规则------模块之间只能通过对方的 service 入口调用,不许跨模块碰 repository。
十、症状、原因、解法
| 症状 | 原因 | 解法 |
|---|---|---|
| 改一个接口要翻遍全项目 | controller 里混了业务与数据访问 | 五层拆分,业务规则全部上移 service |
service 里出现 req.body |
分层只做了目录,没守依赖 | 用校验脚本禁止 service import express |
| 换数据库要改十几个文件 | SQL 散落在 controller 与 service | 数据访问只留 repository 一层 |
| 单元测试必须连库 | 业务逻辑与 ORM 耦合 | service 只依赖 repository 接口,测试时注入内存实现 |
| 报错处理每个接口写一遍 | 没有统一 AppError 与错误中间件 | 业务抛 AppError,4 参数 middleware 统一映射 |
| 不同功能之间循环依赖 | 没有单向依赖方向约定 | 按层导入 + CI 跑 check:layers |
结构这件事没有标准答案,但有稳定的判据:依赖方向是否单一、业务规则是否只有一处、换实现是否只动一层。三条都满足,目录叫什么都行;有一条不满足,目录再整齐也只是摆放顺序。
这套五层骨架适合接口数已经过二十、开始有人并行提交的 Express 项目。如果只是给内部工具写三五个接口,app.js 加一个路由文件就够了,硬套五层反而增加跳转成本。
本专栏《全栈开发》覆盖 Node.js 服务端、前端工程化与全栈项目的目录治理,偏重「能落地、能验证」的工程取舍,每篇都带可直接运行的示例,每周更新一篇。