目录

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 为准,版本差异见第 16 节。

把工程拆成 app.js(应用本身,导出 app)与 server.js(真正监听端口)两个文件,是为了让测试可以直接引入 app 而不占用端口。

src/app.js
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;
src/server.js
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 };
package.json
{
  "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

分层原则:

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

注意两点:

3.3 Router 模块化

express.Router() 是一个独立的「迷你 app」,有自己的中间件栈,最后挂到主 app 的某个前缀下。 这是 Express 项目里最重要的组织方式。

src/routes/users.js
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;
src/routes/index.js
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;
src/app.js
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 请求级共享数据,模板或日志可用

两个必须记住的点:

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)     // 直接跳到错误处理中间件
}

规则:

请求穿过中间件链的示意(洋葱模型):

请求 →
  日志中间件   (前)
    认证中间件 (前)
      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 通过参数个数识别错误处理中间件:必须有四个参数,且必须注册在所有路由之后。

src/utils/HttpError.js
export class HttpError extends Error {
  constructor(status, message, details) {
    super(message);
    this.name = 'HttpError';
    this.status = status;
    this.details = details;
  }
}
src/middlewares/errorHandler.js
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 异步错误怎么进错误中间件

// 把 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 错误处理常见坑

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
src/middlewares/validate.js
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. 配置与运行时设置

src/config.js
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
src/middlewares/auth.js
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. 统一响应格式与控制器写法

src/controllers/userController.js
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
test/users.test.js
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'));

生产清单:

16. Express 5 的变化

变化 Express 4 Express 5
路径通配 /files/,req.params[0] | /files/splat,req.params.splat 数组
可选参数 /users/:id? /users{/:id}
通配可空 不支持

17. 常见坑