告别Try-Catch：Express中的智能异步错误处理

作者头像东城·2026-01-31 23:20:18·
当使用Node.js和Express构建后端时，我们很可能使用async/await来处理数据库查询或API调用等操作。
但有一个问题——如果我们不正确处理错误，我们的服务器可能会崩溃或表现不可预测。😬
在这篇文章中，你将学习在Express中处理异步错误的清洁、可扩展的方法：
为什么在每个路由中使用try-catch很痛苦
如何用可重用的asyncHandler()修复它
如何使用外部库简化这个过程
如何使用我自己的包：express-error-toolkit
如何定义自定义错误类
以及如何设置全局错误处理器
🚨 到处使用Try-Catch的问题
这是我们通常处理错误的方式：
  1. app.get('/api/users/:id', async (req, res, next) => {
  2. try {
  3. const user = await User.findById(req.params.id);
  4. if (!user) return res.status(404).json({ message: 'User not found' });
  5. res.json(user);
  6. } catch (error) {
  7. next(error);
  8. }
  9. });
javascript
在每个路由中重复这样做是：
冗余的
丑陋的
容易忘记
让我们修复这个问题。
✅ 选项1：编写自定义asyncHandler
  1. // utils/asyncHandler.js
  2. const asyncHandler = (fn) => {
  3. return (req, res, next) => {
  4. Promise.resolve(fn(req, res, next)).catch(next);
  5. };
  6. };

  8. module.exports = asyncHandler;
javascript
像这样使用它：
  1. const asyncHandler = require('../utils/asyncHandler');

  3. app.get('/api/users/:id', asyncHandler(async (req, res) => {
  4. const user = await User.findById(req.params.id);
  5. if (!user) throw new Error('User not found');
  6. res.json(user);
  7. }));
javascript
清洁。可重用。没有try-catch。
📦 选项2：使用库（强烈推荐）
🔹 express-error-toolkit — 在npm上查看
我构建了这个包来使Express应用中的错误处理变得更加容易。它包括：
一个asyncHandler()函数
预定义的错误类（NotFoundError、BadRequestError等）
一个全局错误处理中间件
开发环境中的清洁堆栈跟踪
安装
  1. npm install express-error-toolkit
bash
使用
  1. const { asyncHandler } = require('express-error-toolkit');

  3. app.get('/api/users/:id', asyncHandler(async (req, res) => {
  4. const user = await User.findById(req.params.id);
  5. if (!user) throw new Error('User not found');
  6. res.json(user);
  7. }));
javascript
🧱 定义自定义错误类
如果你不使用包，你可以定义自己的：
  1. // utils/ApiError.js
  2. class ApiError extends Error {
  3. constructor(statusCode, message) {
  4. super(message);
  5. this.statusCode = statusCode;
  6. Error.captureStackTrace(this, this.constructor);
  7. }
  8. }

  10. module.exports = ApiError;
javascript
使用：
  1. const ApiError = require('../utils/ApiError');

  3. if (!user) throw new ApiError(404, 'User not found');
javascript
或者使用express-error-toolkit的内置错误
  1. const { NotFoundError } = require('express-error-toolkit');

  3. if (!user) throw new NotFoundError('User not found');
javascript
🌍 全局错误处理中间件
在你的中间件链的末尾添加这个：
  1. app.use((err, req, res, next) => {
  2. const status = err.statusCode || 500;
  3. const message = err.message || 'Internal Server Error';

  5. res.status(status).json({
  6. success: false,
  7. message,
  8. stack: process.env.NODE_ENV === 'production' ? null : err.stack,
  9. });
  10. });
javascript
或者使用express-error-toolkit的内置处理器：
  1. const { globalErrorHandler } = require('express-error-toolkit');

  3. app.use(globalErrorHandler);
javascript
🧪 完整示例
  1. const express = require('express');
  2. const mongoose = require('mongoose');
  3. const {
  4. NotFoundError,
  5. asyncHandler,
  6. globalErrorHandler,
  7. } = require('express-error-toolkit');

  9. const app = express();
  10. app.use(express.json());

  12. app.get('/api/users/:id', asyncHandler(async (req, res) => {
  13. const user = await User.findById(req.params.id);
  14. if (!user) throw new NotFoundError('User not found');
  15. res.json(user);
  16. }));

  18. app.use(globalErrorHandler);

  20. app.listen(3000, () => console.log('Server running on port 3000'));
javascript
🧠 最终思考
✅ 使用asyncHandler避免在每个路由中使用try-catch
📦 使用express-error-toolkit获得功能完整、清洁的设置
🧱 使用自定义类抛出有意义的错误
🌍 在一个全局中间件中捕获和格式化所有错误
遵循这种方法，你的Express后端将是清洁、可扩展和生产就绪的。🚀
详细实现指南
1. 基础asyncHandler实现
  1. // utils/asyncHandler.js
  2. const asyncHandler = (fn) => {
  3. return (req, res, next) => {
  4. Promise.resolve(fn(req, res, next)).catch(next);
  5. };
  6. };

  8. module.exports = asyncHandler;
javascript
2. 高级asyncHandler（带错误类型检查）
  1. // utils/asyncHandler.js
  2. const asyncHandler = (fn) => {
  3. return (req, res, next) => {
  4. Promise.resolve(fn(req, res, next))
  5. .catch((error) => {
  6. // 检查是否是已知的API错误
  7. if (error.statusCode) {
  8. return next(error);
  9. }
  11. // 处理未知错误
  12. console.error('Unexpected error:', error);
  13. next(new Error('Internal Server Error'));
  14. });
  15. };
  16. };

  18. module.exports = asyncHandler;
javascript
3. 完整的错误类系统
  1. // utils/errors.js

  3. // 基础API错误类
  4. class ApiError extends Error {
  5. constructor(statusCode, message, isOperational = true) {
  6. super(message);
  7. this.statusCode = statusCode;
  8. this.isOperational = isOperational;
  9. Error.captureStackTrace(this, this.constructor);
  10. }
  11. }

  13. // 特定错误类
  14. class NotFoundError extends ApiError {
  15. constructor(message = 'Resource not found') {
  16. super(404, message);
  17. }
  18. }

  20. class BadRequestError extends ApiError {
  21. constructor(message = 'Bad request') {
  22. super(400, message);
  23. }
  24. }

  26. class UnauthorizedError extends ApiError {
  27. constructor(message = 'Unauthorized') {
  28. super(401, message);
  29. }
  30. }

  32. class ForbiddenError extends ApiError {
  33. constructor(message = 'Forbidden') {
  34. super(403, message);
  35. }
  36. }

  38. class ValidationError extends ApiError {
  39. constructor(message = 'Validation failed') {
  40. super(422, message);
  41. }
  42. }

  44. class ConflictError extends ApiError {
  45. constructor(message = 'Conflict') {
  46. super(409, message);
  47. }
  48. }

  50. module.exports = {
  51. ApiError,
  52. NotFoundError,
  53. BadRequestError,
  54. UnauthorizedError,
  55. ForbiddenError,
  56. ValidationError,
  57. ConflictError,
  58. };
javascript
4. 高级全局错误处理器
  1. // middleware/errorHandler.js
  2. const { ApiError } = require('../utils/errors');

  4. const errorHandler = (err, req, res, next) => {
  5. let error = { ...err };
  6. error.message = err.message;

  8. // 记录错误
  9. console.error(err);

  11. // Mongoose错误处理
  12. if (err.name === 'CastError') {
  13. const message = 'Resource not found';
  14. error = new ApiError(404, message);
  15. }

  17. // Mongoose重复键错误
  18. if (err.code === 11000) {
  19. const message = 'Duplicate field value entered';
  20. error = new ApiError(400, message);
  21. }

  23. // Mongoose验证错误
  24. if (err.name === 'ValidationError') {
  25. const message = Object.values(err.errors).map(val => val.message).join(', ');
  26. error = new ApiError(400, message);
  27. }

  29. // JWT错误
  30. if (err.name === 'JsonWebTokenError') {
  31. const message = 'Invalid token';
  32. error = new ApiError(401, message);
  33. }

  35. // JWT过期错误
  36. if (err.name === 'TokenExpiredError') {
  37. const message = 'Token expired';
  38. error = new ApiError(401, message);
  39. }

  41. res.status(error.statusCode || 500).json({
  42. success: false,
  43. error: error.message || 'Internal Server Error',
  44. ...(process.env.NODE_ENV === 'development' && { stack: err.stack }),
  45. });
  46. };

  48. module.exports = errorHandler;
javascript
5. 完整的Express应用示例
  1. // app.js
  2. const express = require('express');
  3. const mongoose = require('mongoose');
  4. const asyncHandler = require('./utils/asyncHandler');
  5. const {
  6. NotFoundError,
  7. BadRequestError,
  8. ValidationError,
  9. } = require('./utils/errors');
  10. const errorHandler = require('./middleware/errorHandler');

  12. const app = express();

  14. // 中间件
  15. app.use(express.json());

  17. // 用户模型（示例）
  18. const User = mongoose.model('User', {
  19. name: String,
  20. email: String,
  21. age: Number,
  22. });

  24. // 路由示例
  25. app.get('/api/users', asyncHandler(async (req, res) => {
  26. const users = await User.find();
  27. res.json({
  28. success: true,
  29. data: users,
  30. });
  31. }));

  33. app.get('/api/users/:id', asyncHandler(async (req, res) => {
  34. const user = await User.findById(req.params.id);
  36. if (!user) {
  37. throw new NotFoundError('User not found');
  38. }
  40. res.json({
  41. success: true,
  42. data: user,
  43. });
  44. }));

  46. app.post('/api/users', asyncHandler(async (req, res) => {
  47. const { name, email, age } = req.body;
  49. // 验证
  50. if (!name || !email) {
  51. throw new ValidationError('Name and email are required');
  52. }
  54. if (age && (age < 0 || age > 150)) {
  55. throw new ValidationError('Age must be between 0 and 150');
  56. }
  58. const user = await User.create({ name, email, age });
  60. res.status(201).json({
  61. success: true,
  62. data: user,
  63. });
  64. }));

  66. app.put('/api/users/:id', asyncHandler(async (req, res) => {
  67. const { name, email, age } = req.body;
  69. const user = await User.findByIdAndUpdate(
  70. req.params.id,
  71. { name, email, age },
  72. { new: true, runValidators: true }
  73. );
  75. if (!user) {
  76. throw new NotFoundError('User not found');
  77. }
  79. res.json({
  80. success: true,
  81. data: user,
  82. });
  83. }));

  85. app.delete('/api/users/:id', asyncHandler(async (req, res) => {
  86. const user = await User.findByIdAndDelete(req.params.id);
  88. if (!user) {
  89. throw new NotFoundError('User not found');
  90. }
  92. res.json({
  93. success: true,
  94. message: 'User deleted successfully',
  95. });
  96. }));

  98. // 404处理
  99. app.use('*', (req, res) => {
  100. throw new NotFoundError(`Route ${req.originalUrl} not found`);
  101. });

  103. // 全局错误处理（必须在最后）
  104. app.use(errorHandler);

  106. // 启动服务器
  107. const PORT = process.env.PORT || 3000;
  108. app.listen(PORT, () => {
  109. console.log(`Server running on port ${PORT}`);
  110. });
javascript
6. 使用express-error-toolkit的完整示例
  1. // app-with-toolkit.js
  2. const express = require('express');
  3. const mongoose = require('mongoose');
  4. const {
  5. asyncHandler,
  6. NotFoundError,
  7. BadRequestError,
  8. ValidationError,
  9. globalErrorHandler,
  10. } = require('express-error-toolkit');

  12. const app = express();

  14. // 中间件
  15. app.use(express.json());

  17. // 用户模型
  18. const User = mongoose.model('User', {
  19. name: String,
  20. email: String,
  21. age: Number,
  22. });

  24. // 路由
  25. app.get('/api/users', asyncHandler(async (req, res) => {
  26. const users = await User.find();
  27. res.json({
  28. success: true,
  29. data: users,
  30. });
  31. }));

  33. app.get('/api/users/:id', asyncHandler(async (req, res) => {
  34. const user = await User.findById(req.params.id);
  36. if (!user) {
  37. throw new NotFoundError('User not found');
  38. }
  40. res.json({
  41. success: true,
  42. data: user,
  43. });
  44. }));

  46. app.post('/api/users', asyncHandler(async (req, res) => {
  47. const { name, email, age } = req.body;
  49. if (!name || !email) {
  50. throw new ValidationError('Name and email are required');
  51. }
  53. const user = await User.create({ name, email, age });
  55. res.status(201).json({
  56. success: true,
  57. data: user,
  58. });
  59. }));

  61. // 404处理
  62. app.use('*', () => {
  63. throw new NotFoundError('Route not found');
  64. });

  66. // 全局错误处理
  67. app.use(globalErrorHandler);

  69. // 启动服务器
  70. const PORT = process.env.PORT || 3000;
  71. app.listen(PORT, () => {
  72. console.log(`Server running on port ${PORT}`);
  73. });
javascript
7. 测试错误处理
  1. // test-error-handling.js
  2. const request = require('supertest');
  3. const app = require('./app');

  5. describe('Error Handling Tests', () => {
  6. test('should return 404 for non-existent user', async () => {
  7. const response = await request(app)
  8. .get('/api/users/nonexistentid')
  9. .expect(404);
  11. expect(response.body).toEqual({
  12. success: false,
  13. error: 'User not found',
  14. });
  15. });

  17. test('should return 400 for invalid user data', async () => {
  18. const response = await request(app)
  19. .post('/api/users')
  20. .send({ name: 'John' }) // 缺少email
  21. .expect(400);
  23. expect(response.body).toEqual({
  24. success: false,
  25. error: 'Name and email are required',
  26. });
  27. });

  29. test('should return 404 for non-existent route', async () => {
  30. const response = await request(app)
  31. .get('/api/nonexistent')
  32. .expect(404);
  34. expect(response.body).toEqual({
  35. success: false,
  36. error: 'Route /api/nonexistent not found',
  37. });
  38. });
  39. });
javascript
最佳实践总结
1. 使用asyncHandler
避免在每个路由中重复try-catch
保持代码清洁和可读
确保所有异步错误都被正确捕获
2. 定义有意义的错误类
使用HTTP状态码
提供清晰的错误消息
区分操作错误和系统错误
3. 实现全局错误处理
统一错误响应格式
在开发环境显示堆栈跟踪
在生产环境隐藏敏感信息
4. 使用库简化开发
express-error-toolkit提供完整解决方案
减少样板代码
提供预定义的错误类
5. 测试错误处理
确保错误响应格式正确
验证状态码和消息
测试边界情况