构建生产级 Express.js 服务时：用中间件…

适用于开发生产可用的 Express.js REST API、微服务或 Web 应用，并需要健壮的中间件架构、安全加固、测试策略与部署方案。

适用场景

解决思路

1. 安装基础与生产依赖：运行 npm install express；生产栈运行 npm install express helmet cors express-rate-limit express-validator morgan winston compression dotenv；开发工具运行 npm install -D nodemon supertest jest；可选数据库与认证运行 npm install mongoose jsonwebtoken bcrypt。
2. 创建最小 Express 服务器：引入 express，创建 app，设置 PORT=process.env.PORT || 3000，使用 express.json() 和 express.urlencoded({ extended: true })，定义 / 和 /health 路由，添加 (err, req, res, next) 错误处理器，用 app.listen 监听端口，并在 SIGTERM 时调用 server.close 优雅关闭。
3. 开发时使用 nodemon：执行 npm install -D nodemon；用 npx nodemon server.js 启动；或在 package.json 添加 dev 脚本。
4. 采用生产就绪目录结构：src/app.js 作为 app 工厂；src/server.js 作为入口；src/config/ 包含配置与 logger.js；src/middleware/ 包含 errorHandler.js、validation.js、auth.js、rateLimiter.js；src/routes/ 包含 index.js、users.js、api/；src/controllers/、src/models/、src/services/、src/utils/ 包含 AppError.js 和 catchAsync.js；src/tests/ 包含 unit/ 和 integration/；根目录放 ecosystem.config.js、.env.example、nodemon.json、package.json。
5. 按正确顺序注册中间件：1 用 helmet() 设置安全头；2 用 cors() 配置跨域；3 在解析前用 express-rate-limit 做速率限制；4 用 express.json({ limit: '10mb' }) 和 express.urlencoded({ extended: true, limit: '10mb' }) 解析请求；5 用 compression() 压缩；6 开发用 morgan('dev')、生产用 morgan('combined') 记录日志；7 用 express.static('public') 提供静态文件；8 加载自定义中间件如 requestId、timing；9 挂载路由；10 在所有路由后加 404 处理器；11 最后加错误处理器。
6. 避免错误中间件顺序：不要把路由放在安全中间件之前；不要把错误处理器放在路由之前；不要把请求解析放在路由之后。
7. 实现请求 ID 中间件：从 req.headers['x-request-id'] 读取或使用 uuidv4 生成，赋值给 req.id，通过 res.setHeader('X-Request-ID', req.id) 返回，并调用 next()。
8. 实现请求计时中间件：在中间件开始时记录 Date.now()；在 res.on('finish') 中计算耗时，并打印或记录 req.method、req.path、duration。
9. 实现认证中间件：从 req.headers.authorization 中按空格拆分取第二个 token；无 token 时 next(new AppError('No token provided', 401))；用 jwt.verify(token, process.env.JWT_SECRET) 解码并设置 req.user；验证失败时 next(new AppError('Invalid token', 401))。
10. 实现授权中间件：创建 authorize(...roles) 返回中间件；检查 req.user 是否存在，不存在返回 401；检查 req.user.role 是否在 roles 中，不在返回 403；通过则 next()。
11. 在路由中应用认证与授权：公开路由直接使用；需认证路由加 authenticate；角色路由加 authenticate 和 authorize('admin', 'moderator') 等。
12. 正确处理异步中间件：创建 utils/catchAsync.js，导出 (fn) => (req, res, next) => fn(req, res, next).catch(next)；在异步路由中用 catchAsync(async (req, res) => {...}) 包装，避免未捕获拒绝。
13. 不要写无错误处理的异步路由：避免直接 app.get('/users', async (req, res) => { const users = await User.find(); ... }) 而不包装或捕获。
14. 实现中间件组合：创建 compose(...middleware) 函数，按顺序执行中间件，遇到同步错误调用 next(err)；用于组合 authenticate、authorize('admin')、validateRequest 等。
15. 实现条件中间件：创建 conditionalMiddleware(condition, middleware)，当 condition(req) 为真时执行 middleware，否则 next()；例如仅开发环境使用 morgan('dev')。
16. 创建自定义错误类 AppError：继承 Error，constructor(message, statusCode) 中调用 super(message)，设置 this.statusCode、this.status（4xx 为 'fail'，否则 'error'）、this.isOperational=true，并调用 Error.captureStackTrace(this, this.constructor)。
17. 创建错误层次：定义 ValidationError extends AppError(400, errors=[])、AuthenticationError extends AppError(401)、AuthorizationError extends AppError(403)、NotFoundError extends AppError(404)、ConflictError extends AppError(409)，并统一导出。
18. 实现集中错误处理器：设置 err.statusCode 默认 500、err.status 默认 'error'；用 logger.error 记录 message、statusCode、stack、path、method、ip、userId；开发环境返回 status、error、message、stack；生产环境若 err.isOperational 返回 status、message、可选 errors；否则记录并返回 500 通用消息 'Something went wrong'。
19. 处理特定错误类型：CastError 转为 400 Invalid path/value；重复键 code 11000 转为 400 Duplicate field；ValidationError 合并 errors 消息为 400；JsonWebTokenError 转为 401 Invalid token；TokenExpiredError 转为 401 token expired；然后发送错误响应。
20. 在控制器中使用 catchAsync 和自定义错误：异步控制器用 catchAsync 包装；找不到资源时调用 next(new NotFoundError('User'))；创建成功返回 201 和 { user }。
21. 处理进程级未处理错误：在 server.js 监听 process.on('unhandledRejection') 和 process.on('uncaughtException')，记录错误名和消息，调用 server.close 后 process.exit(1)；监听 SIGTERM 记录并优雅关闭。
22. 配置 Helmet 安全头：使用 helmet 配置 contentSecurityPolicy 的 directives：defaultSrc 为 'self'，styleSrc 为 'self' 和 'unsafe-inline'，scriptSrc 为 'self'，imgSrc 为 'self'、data:、https:，connectSrc 为 'self'，fontSrc 为 'self'，objectSrc 为 'none'，mediaSrc 为 'self'，frameSrc 为 'none'；配置 hsts maxAge 31536000、includeSubDomains true、preload true；frameguard action deny；noSniff true；xssFilter true；referrerPolicy policy 'strict-origin-when-cross-origin'；然后 app.use(securityConfig)。
23. 配置 CORS：从 process.env.ALLOWED_ORIGINS 按逗号拆分为 whitelist；corsOptions.origin 函数允许无 origin 请求，检查 origin 是否在白名单，允许则 callback(null, true)，否则 callback(new Error('Not allowed by CORS'))；设置 credentials: true、methods: ['GET','POST','PUT','DELETE','PATCH','OPTIONS']、allowedHeaders: ['Content-Type','Authorization','X-Requested-With']、exposedHeaders: ['X-Total-Count','X-Page-Number']、maxAge: 86400。
24. 配置速率限制：使用 express-rate-limit 和 rate-limit-redis，创建 Redis client；generalLimiter 使用 RedisStore 前缀 rl:general:，windowMs 15*60*1000，max 100，standardHeaders true，legacyHeaders false；authLimiter 前缀 rl:auth:，windowMs 15*60*1000，max 5，skipSuccessfulRequests true；apiKeyLimiter windowMs 60*60*1000，max 1000，keyGenerator 用 x-api-key 或 req.ip，skip 无 x-api-key；将 generalLimiter 挂到 /api/，authLimiter 挂到登录和注册路由。
25. 实现输入验证与清理：使用 express-validator 的 body、param、query、validationResult；创建 validate 中间件，若无错误则 next()，否则把 errors.array() 映射为 { field, message, value } 并 next(new ValidationError('Validation failed', extractedErrors))。
26. 定义用户验证规则：createUserRules 验证 email isEmail().normalizeEmail()；password isLength({ min: 8 }) 且 matches(/^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)/)；name trim().notEmpty().isLength({ max: 100 }).escape()；age optional().isInt({ min: 0, max: 150 })；updateUserRules 验证 param('id').isMongoId()，email optional().isEmail().normalizeEmail()，name optional().trim().notEmpty().escape()；在路由中应用规则和 validate。
27. 防止 SQL 注入：不要用字符串拼接查询；使用参数化查询如 'SELECT * FROM users WHERE email = ?' 并传数组 [req.body.email]；或使用 ORM/Query Builder 如 User.findOne({ email: req.body.email }) 或 db('users').where('email', req.body.email).first()。
28. 进行 XSS 防护：安装 xss-clean，app.use(xss())；在模板中封装 escapeHtml，将 & 转 &amp;、< 转 &lt;、> 转 &gt;、双引号转 &quot;、单引号转 &#039;。
29. 保护环境变量：使用 dotenv；定义 requiredEnvVars 列表并在缺失时抛错；校验 JWT_SECRET 长度至少 32；导出 config 对象，解析 PORT、REDIS_PORT 等数字；提供 .env.example 包含 NODE_ENV、PORT、DATABASE_URL、DB_POOL_MIN/MAX、REDIS_HOST/PORT/PASSWORD、JWT_SECRET、JWT_EXPIRES_IN、JWT_REFRESH_EXPIRES_IN、ALLOWED_ORIGINS、RATE_LIMIT_WINDOW_MS、RATE_LIMIT_MAX、LOG_LEVEL、LOG_FILE。
30. 编写 Supertest 测试设置：用 MongoMemoryServer.create() 启动内存 MongoDB，mongoose.connect(uri)；afterEach 遍历 mongoose.connection.collections 并 deleteMany；afterAll 断开 mongoose 并停止 mongoServer。
31. 编写用户 API 集成测试：使用 request(app) 测试 POST /api/users 创建用户返回 201 且不返回 password；无效 email 返回 400 且含 errors；重复 email 返回 409；GET /api/users/:id 返回 200 或不存在 404；PUT 更新返回 200；DELETE 返回 204 且数据库查询为 null。
32. 编写认证测试：beforeEach 创建测试用户并登录获取 authToken；测试 POST /api/auth/login 有效凭证返回 200 含 token 和 user，错误密码返回 401；GET /api/auth/me 带 Bearer token 返回 200，无 token 返回 401，无效 token 返回 401。
33. 使用测试工厂：创建 tests/factories/userFactory.js，导出 createUser(overrides) 生成唯一 email、name、password 并支持覆盖；导出 createUsers(count, overrides) 批量创建；在测试中用来创建 5 个用户或 admin 用户。
34. 配置测试覆盖率：在 package.json 添加 scripts：test、test:watch、test:coverage、test:unit、test:integration；配置 jest testEnvironment: 'node'，coveragePathIgnorePatterns 忽略 /node_modules/，collectCoverageFrom 包含 src/**/*.js 且排除 src/tests/**，coverageThreshold.global 设置 branches/functions/lines/statements 均为 80。
35. 管理环境配置：创建 config/index.js，读取并导出 env、port、database.url、database.poolMin、database.poolMax、redis.host/port/password、jwt.secret/expiresIn/refreshExpiresIn、cors.origins、rateLimit.windowMs/max、logging.level/file；校验 database.url 和 jwt.secret 必填。
36. 配置结构化日志：使用 Winston 定义 logLevels（error/warn/info/http/debug）和颜色；format 组合 timestamp、errors({ stack: true })、splat、json；transports 写 logs/error.log 仅 error，写 logs/combined.log，maxsize 5242880、maxFiles 5；非生产加 Console 彩色输出；创建 logger 并记录 info、error、debug。
37. 实现请求日志中间件：创建 middleware/requestLogger.js，在请求开始时记录 start；res.on('finish') 时计算 duration，并用 logger.http 记录 method、url、statusCode、duration、ip、userAgent、userId。
38. 实现健康检查端点：GET /health 返回 status、uptime、timestamp；GET /health/detailed 检查 MongoDB readyState、Redis ping、内存 rss/heapUsed/heapTotal，正常 200，degraded 503；GET /ready 检查 mongoose.connection.db.admin().ping()，成功 200，失败 503；GET /live 返回 200。
39. 实现优雅关闭：在 server.js 中监听 SIGTERM、SIGINT、uncaughtException、unhandledRejection；收到信号后 server.close 停止新连接；关闭 MongoDB 连接 mongoose.connection.close(false)；关闭 Redis redis.quit()；完成后 process.exit(0)；设置 30 秒超时强制 process.exit(1)。
40. 配置 PM2 集群：创建 ecosystem.config.js，apps 数组包含 name: 'express-api'、script: './src/server.js'、instances: 'max'、exec_mode: 'cluster'；设置 env 和 env_production 的 NODE_ENV/PORT；autorestart: true、max_restarts: 10、min_uptime: '10s'、max_memory_restart: '500M'；kill_timeout: 5000、wait_ready: true、listen_timeout: 10000；配置 error_file、out_file、log_date_format、merge_logs、instance_var、watch: false；配置 deploy.production 的 user、host、ref、repo、path、post-deploy。
41. 使用 PM2 命令：pm2 start ecosystem.config.js --env production；pm2 reload express-api 零停机重载；pm2 monit 监控；pm2 logs express-api 查看日志；pm2 scale express-api 4 扩缩容；pm2 stop/restart/delete express-api；pm2 save；pm2 startup；pm2 deploy production。
42. 配置 Nodemon：在 nodemon.json 设置 watch: ['src']，ext: 'js,json'，ignore 测试、node_modules、logs；exec: 'node src/server.js'；env NODE_ENV=development、PORT=3000；delay: 1000；verbose: false；restartable: 'rs'；signal: 'SIGTERM'。
43. 配置 package.json 脚本：添加 dev、dev:debug、start、test、test:watch、test:coverage、lint、lint:fix、format、prod、reload、stop、logs 等脚本，分别对应 nodemon、node --inspect、jest、eslint、prettier、pm2。
44. 按决策树选择中间件：安全头用 helmet；CORS 用 cors；速率限制用 express-rate-limit；输入验证用 express-validator；JSON 解析用 express.json()；表单用 express.urlencoded()；multipart 用 multer；开发日志用 morgan('dev')；生产日志用 winston + morgan('combined')；压缩用 compression()；会话认证用 express-session + connect-redis；令牌认证用 jsonwebtoken。
45. 按决策树处理错误：操作错误分别返回 400 验证、401 认证、403 授权、404 未找到、409 冲突；编程错误在开发返回完整错误和堆栈，在生产记录并返回通用消息；外部服务错误使用重试指数退避或熔断快速失败。
46. 按决策树选择测试：API 端点用 Supertest 集成测试；业务逻辑用 Jest 单元测试；数据库操作用 MongoMemoryServer 集成测试；认证测试令牌流程；错误处理测试错误用例。
47. 按决策树选择部署：本地开发用 nodemon；单服务器小应用用 node server.js，生产用 PM2 单实例；多核服务器用 PM2 cluster mode；容器单容器用 Docker + node，编排用 Docker + Kubernetes；Serverless 用 AWS Lambda + API Gateway。
48. 解决端口占用：用 lsof -ti:3000 | xargs kill -9 查找并杀进程；或 PORT=3001 npm run dev；或在 package.json 添加 predev 脚本 kill-port 3000 || true。
49. 解决中间件顺序问题：按安全、速率限制、解析、压缩、日志、自定义中间件、路由、404、错误处理器的顺序排查；确保错误处理器在最后。
50. 解决未处理 Promise rejection：用 catchAsync 包装异步路由；或监听 process.on('unhandledRejection')，记录错误并 server.close 后退出。
51. 解决集群模式 session 丢失：使用 express-session 配合 connect-redis 的 RedisStore，配置 secret、resave: false、saveUninitialized: false。
52. 解决内存泄漏：用 pm2 start server.js --max-memory-restart 500M；用 node --inspect server.js 配合 Chrome DevTools 分析；用 clinic doctor -- node server.js 诊断。
53. 避免反模式：不要把业务逻辑写在路由里，应分离到 controller 和 service；路由只做 validate 和 controller.create 等调用。
54. 避免反模式：不要使用同步文件操作如 fs.readFileSync，改用 await fs.promises.readFile。
55. 避免反模式：不要信任用户输入直接 User.create(req.body)，必须经过 validate(createUserRules) 等验证和清理。
56. 使用最小生产中间件栈：引入 express、helmet、cors、compression、morgan、express-rate-limit；依次 app.use(helmet())；app.use(cors())；app.use(rateLimit({ windowMs: 15*60*1000, max: 100 }))；app.use(express.json({ limit: '10mb' }))；app.use(express.urlencoded({ extended: true }))；app.use(compression())；app.use(morgan('combined'))；挂载 /api/v1 路由；最后挂载错误处理器。
57. 使用常用命令：开发用 npm run dev、npm test、npm run test:watch、npm run lint；生产用 npm start、pm2 start ecosystem.config.js、pm2 reload app、pm2 logs app、pm2 monit；测试用 npm test、npm run test:unit、npm run test:integration、npm run test:coverage。
58. 查阅详细参考文档：middleware-patterns.md 看高级中间件组合；security-hardening.md 看安全检查清单；testing-strategies.md 看完整测试指南；production-deployment.md 看部署架构与策略。

适用边界 · 注意事项

• 需要极致性能或基于 schema 的验证时，可优先考虑 Fastify 而不是 Express。
• 团队偏好 TypeScript 优先、强约定和企业级模式时，可优先考虑 NestJS。
• 只需极简原型、不需要生产级中间件、安全、测试和部署体系时，完整方案可能过重。