Express 企业级项目结构怎么组织:五层骨架、单向依赖和一份能跑的边界检查脚本

0 阅读8分钟

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/ 这几个目录名,但 没有任何一条强制约束。共识很清楚,问题在于共识不会自动生效。

于是最常见的退化路径是这样的:

  1. 一开始 app.js 里几个路由,够用;
  2. 业务变复杂,加个 controllers/,但 controller 里顺手写了 SQL;
  3. 又有人要复用这段逻辑,就在 controller 里 import 另一个 controller,最后两个文件互相依赖,环成了,谁也不敢动。

类比一下:这就像厨房里没有灶台分区,切菜、炒菜、装盘全在同一块台面上,人一多就开始互相挡手。分层不是为了让目录好看,是为了让每个人 只需要知道上下游是谁,不必记住全部。

三、五层骨架:每层只做什么

层只做绝不做典型文件
router 路由声明 URL 与处理函数的映射取参数、写逻辑、碰数据库user.routes.js
controller 控制层从 req 取输入、调 service、组装 res写业务规则、写 SQL、做数据校验user.controller.js
service 业务层校验、编排规则、抛业务错误出现 req / res / expressuser.service.js
repository 仓储层增删改查,隔离 ORM / SQL判断「该不该」「合不合法」user.repository.js
model / schema描述数据结构与类型承载流程控制user.schema.js

这张表最容易被违反的是 service 和 repository 之间的分工。举个真实的分歧点:「邮箱不能重复」这条规则放哪?

放 repository 是错的——仓储只负责「按 email 查有没有人」,它不知道「有就不能建」这意味着什么;放 service 才对,因为这是业务规则。判断方法很简单:换一个存储实现(Postgres 换成 Mongo),这条规则还在不在? 在,就是业务规则;不在,才是数据访问细节。

四、完整目录树

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 的启动错误走回调参数,不再抛异常。端口被占用时,错误作为第一个参数传进回调,必须显式判断:

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 只管应用组装,两者职责不再混。

六、依赖只能单向

flowchart TD
    A[HTTP 请求] --> B[router 路由层]
    B --> C[controller 控制层]
    C --> D[service 业务层]
    D --> E[repository 仓储层]
    E --> F[(数据库 / 外部 API)]
    C -. 越界直连仓储 .-> E
    D -. 越界 import express .-> G[express 框架]
    classDef input fill:#DBEAFE,stroke:#3B82F6,stroke-width:2px,color:#111827
    classDef process fill:#DCFCE7,stroke:#22C55E,stroke-width:2px,color:#111827
    classDef store fill:#CFFAFE,stroke:#06B6D4,stroke-width:2px,color:#111827
    classDef output fill:#EDE9FE,stroke:#8B5CF6,stroke-width:2px,color:#111827
    classDef bad fill:#FEE2E2,stroke:#EF4444,stroke-width:2px,color:#111827
    class A input
    class B process
    class C process
    class D process
    class E store
    class F output
    class G bad

三条规则,一条都不能松:

  1. controller 不许 import repository。 一旦允许,service 就被架空,业务规则会分裂到两个地方,改一次需求得改两处。
  2. service 不许出现 req / res / express。 service 是纯业务函数,入参是普通对象,出参是实体或抛错。出现 req.body 说明它被 HTTP 污染了,换 CLI 或消息队列触发时就得重写一遍。
  3. repository 不许做业务判断。 它只回答「查到了什么」,不回答「要不要抛 409」。

反例长什么样?很常见的一种:

// ❌ 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 一个文件。

// 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 分支,不解析文案
  }
}
// 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;
}
// 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 });
}
// 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 ?? {}) });
}
// 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;
// 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: '服务器内部错误' } });
}
// 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;
// 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"。跑起来后实测输出是这样的:

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。

// 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 服务端、前端工程化与全栈项目的目录治理,偏重「能落地、能验证」的工程取舍,每篇都带可直接运行的示例,每周更新一篇。