====== Express 教程 ======
Express 是 Node.js 上最老牌、使用最广的 Web 框架(2010 年开源,现由 OpenJS 基金会维护)。
它的设计哲学可以用一句话概括:
> **Express 只做两件事:路由(routing)和中间件(middleware)。其余一切交给中间件和你自己的代码。**
理解这一句,就理解了 Express 的全部:它不规定目录结构、不内置 ORM、不做参数校验、不管日志,
但正因为如此它极其灵活,几乎能和任何库自由组合。学 Express 的本质是学**中间件模型**。
^ 特点 ^ 说明 ^
| 极简核心 | 核心代码很小,能力靠中间件叠加 |
| 中间件模型 | 请求像洋葱一样层层穿过函数链 |
| 路由能力 | 方法 + 路径 + 参数 + Router 模块化 |
| 生态最大 | 几乎所有 Node 教程、示例、中间件都先支持 Express |
| 不适合 | 需要极致性能时考虑 Fastify,需要强约束与类型安全可看 NestJS |
===== 1. 安装与最小应用 =====
npm init -y
npm install express
当前主流版本是 **Express 5**(''express@^5''),本教程以 Express 5 + ESM 为准,版本差异见[[#express-5-的变化|第 16 节]]。
把工程拆成 ''app.js''(应用本身,导出 app)与 ''server.js''(真正监听端口)两个文件,是为了让测试可以直接引入 app 而不占用端口。
import express from 'express';
const app = express();
// 内置中间件:解析 JSON 与表单请求体
app.use(express.json({ limit: '1mb' }));
app.use(express.urlencoded({ extended: true }));
// 不暴露 X-Powered-By
app.disable('x-powered-by');
app.get('/', (req, res) => {
res.send('Hello Express');
});
app.get('/health', (req, res) => {
res.json({ ok: true, uptime: process.uptime() });
});
export default app;
import app from './app.js';
const port = Number(process.env.PORT ?? 3000);
const server = app.listen(port, () => {
console.log(`listening on http://localhost:${port}`);
});
export { server };
{
"type": "module",
"scripts": {
"dev": "node --watch src/server.js",
"start": "node src/server.js"
},
"dependencies": {
"express": "^5.1.0"
}
}
npm run dev
curl http://localhost:3000/health
===== 2. 推荐的项目结构 =====
Express 不强制结构,但业务一多就必须分层,否则路由文件会变成几千行的 if-else。
src/
app.js 创建 app、挂中间件、挂路由(不 listen)
server.js 监听端口、优雅退出
config.js 读取并校验环境变量
routes/
index.js 汇总所有子路由
users.js 只负责「路径 → 控制器」的映射
controllers/
userController.js 解析请求、调用 service、返回响应
services/
userService.js 业务逻辑,不碰 req / res
repositories/ 数据访问(数据库 / 外部 API)
middlewares/
auth.js
errorHandler.js
notFound.js
utils/
HttpError.js
分层原则:
* **controller 不写业务逻辑**,只做「取参数 → 调 service → 返回结果」;
* **service 不知道 HTTP 的存在**,不接收 ''req''/''res'',方便复用与单测;
* **middleware 只做横切关注点**:认证、日志、限流、校验。
===== 3. 路由 =====
==== 3.1 基本形式 ====
路由 = HTTP 方法 + 路径 + 处理函数,一个路径可以挂多个处理函数(形成局部中间件链)。
// 单处理函数
app.get('/users', (req, res) => res.json([]));
// 多处理函数:前一个必须调用 next() 才会继续
app.post('/users', requireAuth, validateBody, createUser);
// 链式写法,同一路径不同方法集中声明
app.route('/users/:id')
.get(getUser)
.put(updateUser)
.patch(patchUser)
.delete(removeUser);
// app.all 匹配所有方法
app.all('/admin/*splat', requireAdmin);
方法别名包括 ''get'' / ''post'' / ''put'' / ''patch'' / ''delete'' / ''options'' / ''head'' / ''all'' / ''use''。
Express 5 已移除 ''app.del'',请用 ''app.delete''。
==== 3.2 路径参数与查询串 ====
// GET /users/42/books/it?page=2
app.get('/users/:id/books/:category', (req, res) => {
const { id, category } = req.params; // 路径参数一定是字符串
const { page = '1', size = '10' } = req.query;
res.json({ id, category, page: Number(page), size: Number(size) });
});
^ 需求 ^ 写法 ^ 取值方式 ^
| 普通参数 | ''/users/:id'' | ''req.params.id'' |
| 可选段(Express 5) | ''/users{/:id}'' | ''req.params.id'' 可能为 undefined |
| 通配(Express 5) | ''/files/*splat'' | ''req.params.splat'' 是**数组** |
| 通配可空(Express 5) | ''/files/{*splat}'' | 同上,但可匹配空路径 |
| 查询串 | ''/users?page=2'' | ''req.query.page'' |
注意两点:
* ''req.query'' 里的值类型是字符串(或字符串数组),数字、布尔要自己转换;
* Express 5 默认使用 **simple** 查询解析器,''?a[b]=1'' 不再解析成嵌套对象;要旧行为需显式 ''app.set('query parser', 'extended')''。
==== 3.3 Router 模块化 ====
''express.Router()'' 是一个独立的「迷你 app」,有自己的中间件栈,最后挂到主 app 的某个前缀下。
这是 Express 项目里最重要的组织方式。
import { Router } from 'express';
import { listUsers, getUser, createUser } from '../controllers/userController.js';
import { requireAuth } from '../middlewares/auth.js';
const router = Router();
// 这个路由下所有请求都会经过它
router.use((req, res, next) => {
req.scope = 'users';
next();
});
router.get('/', listUsers);
router.get('/:id', requireAuth, getUser);
router.post('/', createUser);
export default router;
import { Router } from 'express';
import usersRouter from './users.js';
import postsRouter from './posts.js';
const api = Router();
api.use('/users', usersRouter); // → /api/users/...
api.use('/posts', postsRouter);
export default api;
import api from './routes/index.js';
app.use('/api', api);
''router.param()'' 可以对同名参数做预处理(比如统一把 ''id'' 转成数字并检查合法性):
router.param('id', (req, res, next, id) => {
const numeric = Number(id);
if (!Number.isInteger(numeric)) return next(new HttpError(400, 'id 必须是整数'));
req.userId = numeric;
next();
});
===== 4. 请求对象 req 与响应对象 res =====
==== 4.1 req 常用属性 ====
^ 成员 ^ 说明 ^
| ''req.params'' | 路径参数 |
| ''req.query'' | 查询串(字符串) |
| ''req.body'' | 请求体,需先挂 ''express.json()'' 等解析中间件 |
| ''req.headers'' | 请求头,键名小写;''req.get('Authorization')'' 更直观 |
| ''req.method'' / ''req.originalUrl'' / ''req.path'' | 方法 / 含 query 的原始 URL / 纯路径 |
| ''req.ip'' | 客户端 IP;在反向代理后要设 ''trust proxy'' |
| ''req.cookies'' | 需 ''cookie-parser'' 中间件 |
| ''req.file'' / ''req.files'' | 需 ''multer'' 中间件 |
Express 5 中 ''req.body'' 在没有请求体时**可能是 undefined**(body-parser 2.x 的行为变化),取值前先兜底:''const body = req.body ?? {};''
==== 4.2 res 常用方法 ====
^ 方法 ^ 说明 ^
| ''res.status(201)'' | 设状态码,可链式 ''res.status(201).json(...)'' |
| ''res.json(obj)'' | 序列化并返回 JSON,自动设 ''Content-Type: application/json'' |
| ''res.send(str \\| Buffer \\| obj)'' | 通用发送,字符串默认 ''text/html'' |
| ''res.sendFile(absPath)'' | 发送文件,**必须是绝对路径** |
| ''res.download(absPath, '名字.zip')'' | 作为附件下载 |
| ''res.redirect('/login')'' | 重定向,默认 302 |
| ''res.set(name, value)'' / ''res.setHeader()'' | 设置响应头 |
| ''res.cookie(name, value, opts)'' | 需 ''cookie-parser'' |
| ''res.locals'' | 请求级共享数据,模板或日志可用 |
两个必须记住的点:
* **一个请求只能发送一次响应**,''res.json()'' 之后不能再写;
* 分支返回时用 ''return res.status(400).json(...)'',否则后面代码还会执行。
app.get('/api/users/:id', (req, res) => {
const id = Number(req.params.id);
if (!Number.isInteger(id)) {
return res.status(400).json({ error: 'id 必须是整数' });
}
res.set('X-Request-Id', req.get('x-request-id') ?? '');
res.json({ id, name: '张三' });
});
===== 5. 中间件:Express 的灵魂 =====
==== 5.1 签名与执行顺序 ====
中间件就是一个函数:
function middleware(req, res, next) {
// 做事
next(); // 交给下一个中间件
// next(err) // 直接跳到错误处理中间件
}
规则:
* **严格按注册顺序执行**,''app.use'' 写在前面的先跑;
* 调用 ''next()'' 才会继续;**既不 next 也不响应,请求就悬挂**(客户端一直转圈);
* ''next(err)''(err 为真值)会跳过所有普通中间件,直接找错误处理中间件;
* 中间件里同步抛出的错误,会被 Express 捕获并转成 ''next(err)''。
请求穿过中间件链的示意(洋葱模型):
请求 →
日志中间件 (前)
认证中间件 (前)
body 解析
路由处理函数 → 响应
(后)
(后)
错误中间件(只有 next(err) 或抛错时命中)→
// 一个可复用的耗时日志中间件
app.use((req, res, next) => {
const start = Date.now();
res.on('finish', () => {
console.log(`${req.method} ${req.originalUrl} ${res.statusCode} ${Date.now() - start}ms`);
});
next();
});
==== 5.2 app.use 与 app.get 的区别 ====
^ 写法 ^ 匹配规则 ^ 典型用途 ^
| ''app.use('/api', fn)'' | 前缀匹配,''/api''、''/api/users'' 都命中,且匹配所有方法 | 挂中间件、挂 Router |
| ''app.get('/api', fn)'' | 精确路径 + 指定方法 | 具体接口 |
| ''app.all('/api', fn)'' | 精确路径 + 所有方法 | 较少用,通常直接用 ''use'' |
''app.use'' 会把匹配到的前缀**剥掉**再交给子中间件/子 Router,所以 Router 里的路径是相对的。
==== 5.3 内置中间件 ====
^ 中间件 ^ 作用 ^
| ''express.json()'' | 解析 JSON 请求体,可用 ''limit'' 限制大小 |
| ''express.urlencoded({ extended: true })'' | 解析表单 ''application/x-www-form-urlencoded'' |
| ''express.raw()'' / ''express.text()'' | 原样接收 Buffer / 纯文本 body(Webhook 场景) |
| ''express.static('public')'' | 静态文件服务 |
| ''express.Router()'' | 路由容器(不是中间件,但同一套 API) |
app.use('/static', express.static('public', {
maxAge: '7d',
etag: true,
}));
===== 6. 错误处理 =====
==== 6.1 四参数错误中间件 ====
Express 通过**参数个数**识别错误处理中间件:必须有四个参数,且必须注册在所有路由**之后**。
export class HttpError extends Error {
constructor(status, message, details) {
super(message);
this.name = 'HttpError';
this.status = status;
this.details = details;
}
}
import { HttpError } from '../utils/HttpError.js';
// 404:放在所有路由之后、错误中间件之前
export function notFound(req, res, next) {
next(new HttpError(404, `未找到路由 ${req.method} ${req.originalUrl}`));
}
// 统一错误处理:四个参数不可省略,否则不会生效
export function errorHandler(err, req, res, next) {
const status = err instanceof HttpError ? err.status : (err.status ?? 500);
if (status >= 500) {
console.error('[500]', err); // 生产环境换成 pino 等结构化日志
}
// 已经发过响应就交回 Express 默认处理,避免 headers already sent
if (res.headersSent) return next(err);
res.status(status).json({
error: status >= 500 ? '服务器内部错误' : err.message,
details: err.details,
});
}
import { notFound, errorHandler } from './middlewares/errorHandler.js';
// ……所有路由之后
app.use(notFound);
app.use(errorHandler);
==== 6.2 异步错误怎么进错误中间件 ====
* **Express 5**:处理函数返回的 Promise 被 reject 时,会自动调用 ''next(err)'';''async'' 函数里 ''await'' 抛错即可被统一处理。
* **Express 4**:不会自动捕获,必须自己 ''try/catch'' 或包装。兼容两版的通用写法:
// 把 async 处理函数的拒绝转成 next(err)
export const wrap = (fn) => (req, res, next) => Promise.resolve(fn(req, res, next)).catch(next);
router.get('/x', wrap(async (req, res) => {
const data = await fetchSomething(); // 抛错会进 errorHandler
res.json(data);
}));
注意:''await'' 之外的回调(''setTimeout''、事件监听、第三方回调)里抛的错**不会**被捕获,会导致进程崩溃,需要单独处理。
==== 6.3 错误处理常见坑 ====
* 错误中间件写在路由**前面** → 永远不生效;
* 只写了三个参数 → 被当成普通中间件;
* 忘了判断 ''res.headersSent'',导致 ''Cannot set headers after they are sent'';
* 把数据库原始错误信息直接返回给前端(泄露表结构):5xx 应返回泛化文案,详细错误只写日志。
===== 7. 请求体解析与参数校验 =====
==== 7.1 只解析你需要的类型 ====
app.use(express.json({ limit: '1mb' })); // 普通 JSON 接口
app.use(express.urlencoded({ extended: true, limit: '1mb' })); // 表单
// 文件上传不要用 json,用 multer
''limit'' 一定要设,否则一个超大请求体就能吃掉内存。
==== 7.2 用 zod 做校验 ====
Express 没有内置校验,最省心的是 zod(或 joi、valibot)。
npm install zod
import { HttpError } from '../utils/HttpError.js';
// 用法:router.post('/', validate({ body: CreateUserSchema }), createUser)
export const validate = (schemas) => (req, res, next) => {
try {
for (const key of ['body', 'query', 'params']) {
if (!schemas[key]) continue;
const result = schemas[key].safeParse(req[key]);
if (!result.success) {
throw new HttpError(422, `${key} 校验失败`, result.error.issues.map((i) => ({
path: i.path.join('.'),
message: i.message,
})));
}
req[key] = result.data; // 用解析后的值覆盖,类型更可信
}
next();
} catch (err) {
next(err);
}
};
import { z } from 'zod';
const CreateUser = z.object({
name: z.string().min(1, '名字不能为空').max(32),
email: z.string().email('邮箱格式不正确'),
age: z.number().int().min(0).max(150).optional(),
});
router.post('/users', validate({ body: CreateUser }), (req, res) => {
res.status(201).json({ data: req.body });
});
===== 8. 静态资源与模板引擎 =====
import path from 'node:path';
app.use(express.static(path.join(import.meta.dirname, '..', 'public')));
如果同时要前端单页应用(SPA)的 history 路由回退:
// 注意:Express 5 不再支持 '*',要写 /*splat
app.get('/*splat', (req, res) => {
res.sendFile(path.join(import.meta.dirname, '..', 'public', 'index.html'));
});
模板引擎(服务端渲染)现在用得少了,需要时选 EJS 或 Pug:
npm install ejs
app.set('view engine', 'ejs');
app.set('views', path.join(import.meta.dirname, 'views'));
app.get('/about', (req, res) => {
res.render('about', { title: '关于' });
});
===== 9. 配置与运行时设置 =====
import 'dotenv/config';
function required(name) {
const value = process.env[name];
if (!value) throw new Error(`缺少环境变量 ${name}`);
return value;
}
export const config = {
port: Number(process.env.PORT ?? 3000),
env: process.env.NODE_ENV ?? 'development',
jwtSecret: required('JWT_SECRET'),
databaseUrl: required('DATABASE_URL'),
};
''app.set'' 常见设置:
^ 设置 ^ 作用 ^
| ''app.set('trust proxy', 1)'' | 部署在 Nginx/负载均衡后,让 ''req.ip'' 与 ''req.protocol'' 正确 |
| ''app.set('json spaces', 2)'' | 开发时 JSON 美化输出 |
| ''app.disable('x-powered-by')'' | 不暴露 Express 版本 |
| ''app.set('query parser', 'simple' \\| 'extended')'' | 查询串解析策略 |
| ''app.set('case sensitive routing', true)'' | 路径区分大小写(默认不区分) |
===== 10. 常用第三方中间件 =====
npm install cors helmet morgan compression cookie-parser express-rate-limit
import cors from 'cors';
import helmet from 'helmet';
import morgan from 'morgan';
import compression from 'compression';
import cookieParser from 'cookie-parser';
import rateLimit from 'express-rate-limit';
app.use(helmet()); // 安全响应头
app.use(cors({ origin: ['https://example.com'], credentials: true })); // 跨域
app.use(compression()); // gzip
app.use(morgan('tiny')); // 访问日志(生产可换 pino-http)
app.use(cookieParser());
// 限流:15 分钟内每个 IP 最多 100 次
app.use('/api', rateLimit({ windowMs: 15 * 60 * 1000, limit: 100 }));
^ 中间件 ^ 用途 ^ 注意 ^
| ''helmet'' | 设置 CSP、X-Frame-Options 等安全头 | 基本可以无脑开启 |
| ''cors'' | 跨域 | 不要用 ''origin: '*' '' 配 ''credentials: true'' |
| ''morgan'' / ''pino-http'' | 访问日志 | 生产环境用结构化日志 |
| ''compression'' | 响应压缩 | 反向代理已压缩时可能重复压缩 |
| ''express-rate-limit'' | 限流 | 多实例部署要用共享存储 |
| ''express-session'' | 会话 | 默认内存存储只适合开发 |
| ''multer'' | 文件上传 | 必须限制大小与类型 |
推荐顺序:''helmet'' → ''cors'' → 请求 ID → 日志 → 限流 → ''json'' 解析 → 业务路由 → 404 → 错误处理。
===== 11. 认证:JWT 中间件示例 =====
npm install jsonwebtoken
import jwt from 'jsonwebtoken';
import { config } from '../config.js';
export function requireAuth(req, res, next) {
const [scheme, token] = (req.get('Authorization') ?? '').split(' ');
if (scheme !== 'Bearer' || !token) {
return res.status(401).json({ error: '缺少 Bearer token' });
}
try {
req.user = jwt.verify(token, config.jwtSecret); // { sub, role, ... }
next();
} catch {
res.status(401).json({ error: 'token 无效或已过期' });
}
}
// 基于角色的授权
export const requireRole = (...roles) => (req, res, next) => {
if (!roles.includes(req.user?.role)) {
return res.status(403).json({ error: '权限不足' });
}
next();
};
router.delete('/users/:id', requireAuth, requireRole('admin'), removeUser);
注意:JWT 签发后无法主动作废,需要登出/强制下线时得配合服务端黑名单,或用短有效期 + refresh token。
===== 12. 文件上传(multer) =====
npm install multer
import multer from 'multer';
const upload = multer({
storage: multer.diskStorage({
destination: 'uploads/',
filename: (req, file, cb) => cb(null, `${Date.now()}-${file.originalname}`),
}),
limits: { fileSize: 5 * 1024 * 1024 }, // 5MB
fileFilter: (req, file, cb) => {
if (!file.mimetype.startsWith('image/')) {
return cb(new HttpError(400, '只允许上传图片'));
}
cb(null, true);
},
});
router.post('/avatar', requireAuth, upload.single('file'), (req, res) => {
res.json({ data: { file: req.file?.filename, size: req.file?.size } });
});
安全提示:''file.originalname'' 不要直接当存储名(可能含 ''../''),用随机名;上传目录不要放在可执行路径下。
===== 13. 统一响应格式与控制器写法 =====
import { HttpError } from '../utils/HttpError.js';
import * as userService from '../services/userService.js';
export async function listUsers(req, res) {
const { page = 1, size = 10 } = req.query;
const data = await userService.list({ page: Number(page), size: Number(size) });
res.json({ data: data.items, total: data.total, page: Number(page) });
}
export async function getUser(req, res) {
const user = await userService.findById(req.userId);
if (!user) throw new HttpError(404, '用户不存在');
res.json({ data: user });
}
export async function createUser(req, res) {
const user = await userService.create(req.body);
res.status(201).location(`/api/users/${user.id}`).json({ data: user });
}
约定:成功一律 ''{ data }'',失败一律 ''{ error, details }'',前端就不用为每个接口写不同的解析逻辑。
===== 14. 测试:supertest + node:test =====
Express 的 app 本质是 ''(req, res) => void'' 函数,可以直接交给 supertest,不必监听端口。
npm install -D supertest
import test from 'node:test';
import assert from 'node:assert/strict';
import request from 'supertest';
import app from '../src/app.js';
test('GET /health 返回 200', async () => {
const res = await request(app).get('/health');
assert.equal(res.status, 200);
assert.equal(res.body.ok, true);
});
test('POST /api/users 参数缺失返回 422', async () => {
const res = await request(app).post('/api/users').send({ name: '' });
assert.equal(res.status, 422);
assert.ok(res.body.details.length > 0);
});
node --test
===== 15. 生产部署要点 =====
const server = app.listen(port);
server.keepAliveTimeout = 65_000; // 大于反向代理的空闲超时,避免 502
let closing = false;
async function shutdown(signal) {
if (closing) return;
closing = true;
console.log(`收到 ${signal},开始优雅退出`);
server.close(async () => { // 停止接收新连接,等在途请求结束
await db.end(); // 关闭连接池
process.exit(0);
});
setTimeout(() => process.exit(1), 10_000).unref(); // 兜底强杀
}
process.on('SIGTERM', () => shutdown('SIGTERM'));
process.on('SIGINT', () => shutdown('SIGINT'));
生产清单:
* 前面挂 Nginx / 云负载均衡,并设 ''app.set('trust proxy', 1)'';
* ''NODE_ENV=production'',错误细节只进日志不进响应;
* 用 PM2 或容器编排管理进程;容器里不要再套一层 PM2;
* 健康检查走轻量路由 ''/health''(不查库),另设 ''/ready'' 查依赖;
* 日志(''pino-http'')+ 指标(''prom-client'')+ 链路(OpenTelemetry);
* Docker 用多阶段构建,''npm ci --omit=dev'',以非 root 用户运行。
===== 16. Express 5 的变化 =====
^ 变化 ^ Express 4 ^ Express 5 ^
| 路径通配 | ''/files/*'',''req.params[0]'' | ''/files/*splat'',''req.params.splat'' 数组 |
| 可选参数 | ''/users/:id?'' | ''/users{/:id}'' |
| 通配可空 | 不支持 | ''/files/{*splat}'' |
| async 错误 | 需手动 ''try/catch'' 或包装 | rejected Promise **自动** ''next(err)'' |
| ''req.body'' 无 body 时 | ''{}'' | 可能是 ''undefined'' |
| 查询解析默认 | extended(qs) | simple(''node:querystring'') |
| ''res.status()'' | 任意值 | 只接受 100–999 整数,否则抛错 |
| 已移除 API | — | ''app.del''、''res.sendfile''、''res.redirect('back')''、''res.json(status, obj)'' |
迁移建议:先升到 Express 5 跑测试,重点检查所有含 ''*''、''?'' 的路由字符串,以及依赖 ''req.body'' 一定存在的代码。
===== 17. 常见坑 =====
* **忘记 ''next()''**:请求永久挂起,没有报错,只能看到浏览器等待超时。
* **''res.json()'' 之后还写代码**:用 ''return'' 结束分支。
* **body 解析中间件写在路由之后**:''req.body'' 永远是 ''undefined''。
* **错误中间件写在路由前**,或参数个数不是 4:不生效。
* **''Cannot set headers after they are sent''**:某个分支已经响应过,又进了一次响应。
* **''app.get('*')'' 在 Express 5 报错**:改成 ''/*splat''。
* **反代后 ''req.ip'' 全是 127.0.0.1**:漏了 ''trust proxy''。
* **''express.static'' 放在路由之后**:静态文件被前面的路由拦住(顺序很重要)。
* **''origin: '*' '' 配 ''credentials: true''**:浏览器直接拒绝,要写具体域名。
* **把 Express 当同步框架用**:处理函数里同步读写大文件、''JSON.parse'' 巨型内容,会阻塞事件循环,全站变慢。
===== 18. 学习路径 =====
- **先会组装**:''express()'' + ''app.use'' + ''app.get'' + ''listen'',跑通一个接口;
- **吃透中间件**:顺序、''next''、''next(err)''、''app.use'' 与 Router 的差异;
- **再分层**:Router → Controller → Service,写 ''HttpError'' 与统一错误中间件;
- **补工程能力**:校验(zod)、日志(pino)、安全(helmet/cors/限流)、测试(supertest);
- **看源码**:Express 的中间件链实现非常短,读一遍 router 与 next 的调度逻辑,从此不再「玄学」。
----
返回 [[nodejs|Node.js 教程]]。