Express 框架从入门到生产实践：路由、中间件与安全配置

脚本专家

Node.js 的 Express 框架是目前最流行的 Web 框架之一，其简洁的路由机制和中间件体系为构建 RESTful API 和 Web 应用提供了坚实基础。本文从零开始，逐步深入，涵盖基础路由、模块化路由、中间件分类与自定义、统一错误处理、文件上传、安全防护以及性能优化等生产级实践，所有代码基于 Express 4.x 版本。

2. // 第一个 Express 应用
3. const express = require('express');
4. const app = express();
5. const PORT = 3000;
7. app.get('/', (req, res) => {
8.   res.send('Hello Express!');
9. });
11. app.listen(PORT, () => {
12.   console.log(`Server running on http://localhost:${PORT}`);
13. });

复制代码

核心解析：express() 创建应用实例，封装 HTTP 服务器逻辑；app.get(path, handler) 定义 GET 请求路由；res.send() 自动设置 Content-Type。

一、路由：HTTP 方法与参数处理
Express 支持所有标准 HTTP 方法：GET、POST、PUT、DELETE 等。路由参数通过冒号定义，存储在 req.params；查询字符串通过 req.query 获取。

2. // 基本路由示例
3. app.get('/users', (req, res) => { res.json({ users: ['Alice', 'Bob'] }); });
4. app.post('/users', (req, res) => { res.status(201).json({ message: 'User created' }); });
5. app.put('/users/:id', (req, res) => { res.json({ message: `User ${req.params.id} updated` }); });
6. app.delete('/users/:id', (req, res) => { res.json({ message: `User ${req.params.id} deleted` }); });
8. // 路由参数与查询字符串
9. app.get('/users/:id/posts', (req, res) => {
10.   const { id } = req.params;
11.   const { page = 1, limit = 10 } = req.query;
12.   res.json({ userId: id, page, limit });
13. });

复制代码

二、路由模块化：express.Router()
当路由增多时，使用 Router 将代码按模块拆分。

2. // routes/users.js
3. const express = require('express');
4. const router = express.Router();
6. router.get('/', (req, res) => res.json({ users: [] }));
7. router.get('/:id', (req, res) => res.json({ user: req.params.id }));
9. module.exports = router;
11. // app.js 主文件
12. const userRouter = require('./routes/users');
13. app.use('/users', userRouter);

复制代码

此外，app.route() 可对同一资源链式定义多个 HTTP 方法，减少重复代码。

三、中间件：Express 的灵魂
中间件函数可访问 req、res 和 next，按执行顺序分为应用级、路由级、错误处理、内置与第三方中间件。

1. 常用内置中间件
express.json() 解析 JSON 请求体，express.urlencoded() 解析 URL 编码请求体，express.static() 托管静态文件。

2. app.use(express.json());
3. app.use(express.urlencoded({ extended: false }));
4. app.use(express.static('public'));

复制代码

2. 自定义应用级中间件
通过 app.use() 定义全局或路径特定的中间件，一定调用 next() 否则请求挂起。

2. app.use((req, res, next) => {
3.   console.log(`${req.method} ${req.url} - ${new Date().toISOString()}`);
4.   next();
5. });

复制代码

3. 错误处理中间件
必须有 4 个参数 (err, req, res, next)，且位于所有中间件和路由之后。

2. app.get('/error', (req, res, next) => {
3.   const error = new Error('Something went wrong!');
4.   error.status = 500;
5.   next(error);
6. });
8. app.use((err, req, res, next) => {
9.   const status = err.status || 500;
10.   const message = err.message || 'Internal Server Error';
11.   res.status(status).json({ error: message });
12. });

复制代码

四、统一错误处理：同步与异步错误
Express 4.x 默认不捕获 async/await 中的错误，需手动包装。

定义统一错误类：

2. class AppError extends Error {
3.   constructor(message, statusCode) {
4.     super(message);
5.     this.statusCode = statusCode;
6.     this.isOperational = true;
7.     Error.captureStackTrace(this, this.constructor);
8.   }
9. }

复制代码

创建异步包装器：

2. const asyncWrapper = (fn) => {
3.   return (req, res, next) => {
4.     fn(req, res, next).catch(next);
5.   };
6. };

复制代码

使用示例：

2. app.get('/users/:id', asyncWrapper(async (req, res, next) => {
3.   const user = await User.findById(req.params.id);
4.   if (!user) throw new AppError('User not found', 404);
5.   res.json({ user });
6. }));

复制代码

错误处理中间件区分业务错误与系统错误，可仅在开发环境返回堆栈：

2. app.use((err, req, res, next) => {
3.   const { statusCode = 500, message, isOperational } = err;
4.   res.status(statusCode).json({
5.     error: isOperational ? message : 'Internal Server Error',
6.     ...(process.env.NODE_ENV === 'development' && { stack: err.stack })
7.   });
8. });

复制代码

五、RESTful API 设计实践
资源导向，HTTP 方法对应 CRUD。以用户管理为例：

2. let users = [
3.   { id: 1, name: 'Alice', email: 'alice@example.com' },
4.   { id: 2, name: 'Bob', email: 'bob@example.com' }
5. ];
7. app.get('/users', asyncWrapper(async (req, res) => {
8.   const { page = 1, limit = 10 } = req.query;
9.   const start = (page - 1) * limit;
10.   const end = start + parseInt(limit);
11.   const paginatedUsers = users.slice(start, end);
12.   res.json({ data: paginatedUsers, page: parseInt(page), limit: parseInt(limit), total: users.length });
13. }));
15. app.post('/users', asyncWrapper(async (req, res, next) => {
16.   const { name, email } = req.body;
17.   if (!name || !email) throw new AppError('Name and email are required', 400);
18.   const newUser = { id: users.length + 1, name, email };
19.   users.push(newUser);
20.   res.status(201).json({ data: newUser });
21. }));

复制代码

六、文件上传：Multer 中间件
Multer 处理 multipart/form-data。

2. const multer = require('multer');
3. const storage = multer.diskStorage({
4.   destination: (req, file, cb) => { cb(null, 'uploads/'); },
5.   filename: (req, file, cb) => { cb(null, `${Date.now()}-${file.originalname}`); }
6. });
7. const fileFilter = (req, file, cb) => {
8.   if (file.mimetype.startsWith('image/')) cb(null, true);
9.   else cb(new AppError('Only images are allowed', 400), false);
10. };
11. const upload = multer({ storage, fileFilter, limits: { fileSize: 5 * 1024 * 1024 } });
13. // 单文件上传
14. app.post('/upload/avatar', upload.single('avatar'), (req, res) => {
15.   res.json({ message: 'Avatar uploaded', file: req.file });
16. });
18. // 多文件上传
19. app.post('/upload/photos', upload.array('photos', 5), (req, res) => {
20.   res.json({ message: 'Photos uploaded', files: req.files });
21. });

复制代码

七、安全最佳实践
1. Helmet：设置安全 HTTP 头

2. const helmet = require('helmet');
3. app.use(helmet());

复制代码

2. CORS：跨域资源共享

2. const cors = require('cors');
3. // 允许所有来源（开发）
4. app.use(cors());
5. // 或限制特定来源（生产）
6. app.use(cors({ origin: 'https://your-frontend.com', methods: ['GET','POST','PUT','DELETE'] }));

复制代码

3. 速率限制：防止暴力攻击

2. const rateLimit = require('express-rate-limit');
3. const globalLimiter = rateLimit({ windowMs: 15*60*1000, max: 100 });
4. app.use(globalLimiter);
5. // 登录接口更严格
6. const loginLimiter = rateLimit({ windowMs: 15*60*1000, max: 5 });
7. app.post('/login', loginLimiter, (req, res) => res.json({ message: 'Login' }));

复制代码

4. 输入验证：使用 Joi

2. const Joi = require('joi');
3. const userSchema = Joi.object({
4.   name: Joi.string().min(2).max(30).required(),
5.   email: Joi.string().email().required(),
6.   age: Joi.number().integer().min(18).max(100)
7. });
9. app.post('/users', (req, res, next) => {
10.   const { error } = userSchema.validate(req.body);
11.   if (error) throw new AppError(error.details[0].message, 400);
12.   next();
13. }, (req, res) => {
14.   res.json({ message: 'User created' });
15. });

复制代码

八、性能优化
1. 压缩响应

2. const compression = require('compression');
3. app.use(compression());

复制代码

2. 静态文件缓存

2. app.use(express.static('public', { maxAge: '1d' }));

复制代码

3. 避免同步操作
所有 I/O 应使用异步方式（数据库查询、文件读写等），防止阻塞事件循环。

以上实践涵盖了从基础到生产级的 Express 开发要点，开发者可根据项目需求灵活组合各项中间件与配置。

热心网友4

感谢楼主分享这么详细的 Express 实践指南！从基础路由到模块化拆分，再到中间件和统一错误处理，结构清晰，代码也很规范。特别是 `asyncWrapper` 这部分，对于刚接触 Express 的新手来说非常实用，能避免很多异步错误漏捕获的问题。想请教下，在生产环境中处理文件上传时，除了 `multer` 中间件，还有没有推荐的安全检查或配置技巧？