Express 是 Node.js 上最老牌、使用最广的 Web 框架(2010 年开源,现由 OpenJS 基金会维护)。 它的设计哲学可以用一句话概括:
**Express 只做两件事:路由(routing)和中间件(middleware)。其余一切交给中间件和你自己的代码。**
理解这一句,就理解了 Express 的全部:它不规定目录结构、不内置 ORM、不做参数校验、不管日志, 但正因为如此它极其灵活,几乎能和任何库自由组合。学 Express 的本质是学中间件模型。
| 特点 | 说明 |
|---|---|
| 极简核心 | 核心代码很小,能力靠中间件叠加 |
| 中间件模型 | 请求像洋葱一样层层穿过函数链 |
| 路由能力 | 方法 + 路径 + 参数 + Router 模块化 |
| 生态最大 | 几乎所有 Node 教程、示例、中间件都先支持 Express |
| 不适合 | 需要极致性能时考虑 Fastify,需要强约束与类型安全可看 NestJS |
npm init -y npm install express
当前主流版本是 Express 5(express@^5),本教程以 Express 5 + ESM 为准,版本差异见第 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
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
分层原则:
req/res,方便复用与单测;路由 = 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。
// 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 | 同上,但可匹配空路径 |
| 查询串 | /users?page=2 | req.query.page |
注意两点:
req.query 里的值类型是字符串(或字符串数组),数字、布尔要自己转换;?a[b]=1 不再解析成嵌套对象;要旧行为需显式 app.set('query parser', 'extended')。
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(); });
| 成员 | 说明 |
|---|---|
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 ?? {};
| 方法 | 说明 |
|---|---|
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: '张三' }); });
中间件就是一个函数:
function middleware(req, res, next) { // 做事 next(); // 交给下一个中间件 // next(err) // 直接跳到错误处理中间件 }
规则:
app.use 写在前面的先跑;next() 才会继续;既不 next 也不响应,请求就悬挂(客户端一直转圈);next(err)(err 为真值)会跳过所有普通中间件,直接找错误处理中间件;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(); });
| 写法 | 匹配规则 | 典型用途 |
|---|---|---|
app.use('/api', fn) | 前缀匹配,/api、/api/users 都命中,且匹配所有方法 | 挂中间件、挂 Router |
app.get('/api', fn) | 精确路径 + 指定方法 | 具体接口 |
app.all('/api', fn) | 精确路径 + 所有方法 | 较少用,通常直接用 use |
app.use 会把匹配到的前缀剥掉再交给子中间件/子 Router,所以 Router 里的路径是相对的。
| 中间件 | 作用 |
|---|---|
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, }));
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);
next(err);async 函数里 await 抛错即可被统一处理。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、事件监听、第三方回调)里抛的错不会被捕获,会导致进程崩溃,需要单独处理。
res.headersSent,导致 Cannot set headers after they are sent;app.use(express.json({ limit: '1mb' })); // 普通 JSON 接口 app.use(express.urlencoded({ extended: true, limit: '1mb' })); // 表单 // 文件上传不要用 json,用 multer
limit 一定要设,否则一个超大请求体就能吃掉内存。
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 }); });
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: '关于' }); });
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) | 路径区分大小写(默认不区分) |
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 → 错误处理。
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。
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 不要直接当存储名(可能含 ../),用随机名;上传目录不要放在可执行路径下。
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 },前端就不用为每个接口写不同的解析逻辑。
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
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'));
生产清单:
app.set('trust proxy', 1);NODE_ENV=production,错误细节只进日志不进响应;/health(不查库),另设 /ready 查依赖;pino-http)+ 指标(prom-client)+ 链路(OpenTelemetry);npm ci –omit=dev,以非 root 用户运行。| 变化 | Express 4 | Express 5 |
|---|---|---|
| 路径通配 | /files/,req.params.splat 数组 | |
| 可选参数 | /users/:id? | /users{/:id} |
| 通配可空 | 不支持 |
next():请求永久挂起,没有报错,只能看到浏览器等待超时。res.json() 之后还写代码:用 return 结束分支。req.body 永远是 undefined。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 的调度逻辑,从此不再「玄学」。
—-
返回 Node.js 教程。