[Docs] Add comprehensive middleware execution order and error handling examples
### Description
## Issue Description
The current Express.js documentation covers middleware basics, but lacks comprehensive examples demonstrating:
1. **Middleware execution order** with multiple middleware functions
2. **Error-handling middleware** best practices and common patterns
3. **Async/await middleware** with proper error propagation
4. **Router-level vs application-level** middleware interactions
5. **Built-in middleware** execution timing and order
## Current State
The existing docs at https://expressjs.com/en/guide/using-middleware.html provide basic examples, but developers (especially beginners) often struggle with:
- Understanding when `next()` should be called
- How error-handling middleware differs from regular middleware
- Execution order when combining app.use(), router.use(), and route-specific middleware
- Common mistakes that lead to hanging requests or uncaught errors
## Proposed Improvement
Add a dedicated section or expand the existing middleware guide with:
### 1. Visual Execution Flow Diagram
Show the order of execution with a clear diagram or flowchart
### 2. Complete Working Examples
```javascript
// Example: Middleware execution order
const express = require('express');
const app = express();
// Application-level middleware
app.use((req, res, next) => {
console.log('1. App-level middleware');
next();
});
// Router with its own middleware
const router = express.Router();
router.use((req, res, next) => {
console.log('2. Router-level middleware');
next();
});
router.get('/api/users',
(req, res, next) => {
console.log('3. Route-specific middleware');
next();
},
(req, res) => {
console.log('4. Final route handler');
res.json({ users: [] });
}
);
app.use('/api', router);
// Error-handling middleware (must be last)
app.use((err, req, res, next) => {
console.error('5. Error handler:', err);
res.status(500).json({ error: err.message });
});
```
### 3. Common Patterns Section
- Authentication middleware
- Request validation
- Async error handling wrapper
- Response time logging
### 4. Troubleshooting Guide
- "Request hangs" → forgot to call next() or send response
- "Error not caught" → error handler not defined or placed incorrectly
- "Middleware skipped" → route matched before middleware executed
## Benefits
- Reduces support questions and Stack Overflow posts about middleware
- Helps developers avoid common pitfalls
- Provides copy-paste ready examples for common use cases
- Improves onboarding for new Express users
## Related
This complements issue expressjs/express#6917 about async/await error handling best practices.
### Expectations
The updated documentation should include:
1. A dedicated page or expanded section on middleware execution order
2. Interactive examples showing console output to visualize execution flow
3. Side-by-side comparison of correct vs incorrect patterns
4. Clear warnings about common mistakes (e.g., placing error handlers before routes)
5. Best practices for structuring middleware in larger applications
Developers should be able to:
- Understand middleware execution order without trial and error
- Copy working examples for authentication, logging, and error handling
- Debug middleware-related issues using the troubleshooting guide
- Confidently build applications with complex middleware chains
2 条评论