====== 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 教程]]。