企业官网建设流程全解析

• 后端
• API网关

导读

本文基于官方 recipes 文档 async-response.md 展开，聚焦 http-proxy-middleware 中最容易被忽视的能力：如何在代理后端响应返回客户端之前异步修改响应头，以及如何在代理请求真正发出之前异步准备好请求头。读完本文，你将掌握selfHandleResponse开关的正确用法、proxyRes异步回调的编写方式，以及通过前置中间件在proxyReq阶段注入异步数据的完整链路，可直接用于需要注入动态令牌、时间戳、追踪 ID 等真实业务场景。

为什么需要"异步"处理代理响应

中间件模式下，http-proxy-middleware 默认会替开发者完成"把后端响应转发回客户端"的收尾工作。但在某些场景下，我们需要在响应转发前插入自己的处理逻辑：

• 后端响应头中需要携带一个动态生成的值（如签名、会话标识），而这个值只能通过异步 IO（查询数据库、调用远程服务、setTimeout模拟延迟）获取；
• 请求头中的某些字段同样依赖异步计算的中间结果，而这些结果在proxyReq事件触发时才能写入目标请求。

原文档给出了两套对应解法：在proxyRes回调里直接使用async处理响应头；在代理之前插入一个异步前置中间件，把结果暂存到req对象上，供后续proxyReq使用。

前置知识：事件链与 selfHandleResponse

proxyReq与proxyRes是中间件基于httpxy（原 http-proxy 的 TypeScript 重写版）代理服务器的两个核心事件：

• proxyReq：在出站请求（发往目标服务器）创建之后、写入之前触发，此时可以修改目标请求的请求头；
• proxyRes：在收到目标服务器响应之后触发，此时可以读取/修改响应，并把响应转发给客户端。

事件订阅通过options.on对象声明，由 proxy-events.ts 中的proxyEventsPlugin统一注册到内部代理服务器上。其类型签名定义在 types.ts：

proxyRes?: (proxyRes: TReq, req: TReq, res: TRes) => void | Promise<void>;

注意proxyRes回调允许返回 Promise，这正是"在回调内直接await异步任务"的类型依据；而proxyReq回调签名是(proxyReq, req, res, options) => void，不支持等待异步结果，所以请求头方向的异步化要另寻出路（见下文方案二）。

另一个关键配置是selfHandleResponse。README 中 option.selfHandleResponse 的说明为：置为true后，httpxy 不再自动调用res.end()，由开发者自行监听proxyRes事件并把响应返回给客户端。只要你在proxyRes里自行处理了响应，就必须开启它，否则会出现"你处理完响应头，中间件又把响应自动结束"的重复写入问题。

方案一：异步修改响应头（proxyRes 内 await）

原文档的第一个示例完整展示了解法：开启selfHandleResponse: true，在proxyRes回调中先await一个异步任务，再设置动态响应头，最后把后端响应pipe给客户端：

const myProxy = createProxyMiddleware({ target: 'http://www.example.com/api', changeOrigin: true, selfHandleResponse: true, on: { proxyReq: (proxyReq, req, res) => { // before proxyReq.setHeader('mpth-1', 'da'); }, proxyRes: async (proxyRes, req, res) => { const da = await new Promise((resolve, reject) => { setTimeout(() => { resolve({ wei: 'wei' }); }, 200); }); // add your dynamic header res.setHeader('mpth-2', da.wei); // now pipe the response proxyRes.pipe(res); }, }, }); app.use('/api', myProxy);

拆解这段代码的关键点：

1. proxyRes回调声明为async：得益于 types.ts 中void | Promise<void>的签名，await不会造成类型错误；
2. 异步计算放在await之后：这里用setTimeout模拟 200ms 的异步 IO，真实场景可替换为await fetch(...)、数据库查询等；
3. res.setHeader('mpth-2', da.wei)：res是传给客户端的最外层http.ServerResponse，在此设置的头部会随响应一起返回；
4. proxyRes.pipe(res)是"最后一公里"：既然selfHandleResponse关闭了自动结束，若不执行pipe（或手动res.end()），客户端将一直等待响应而挂起。

proxyReq阶段同步写入的mpth-1头、proxyRes阶段异步写入的mpth-2头，最终都会出现在客户端收到的响应中。

方案二：异步修改请求头（前置中间件 + req.locals）

请求头方向的异步化不能直接在proxyReq内完成——事件回调是同步派发的，即使把回调写成async，httpxy 也不会等待其中的 Promise。原文档给出的解法是：在挂载代理之前，先挂一个异步中间件，把计算结果暂存到req对象上，之后proxyReq回调再同步读取：

const entryMiddleware = async (req, res, next) => { const foo = await new Promise((resolve, reject) => { setTimeout(() => { resolve({ da: 'da' }); }, 200); }); req.locals = { da: foo.da, }; next(); }; const myProxy = createProxyMiddleware({ target: 'http://www.example.com/api', changeOrigin: true, selfHandleResponse: true, on: { proxyReq: (proxyReq, req, res) => { // before // get something async from entry middleware before the proxy kicks in console.log('proxyReq:', req.locals.da); proxyReq.setHeader('mpth-1', req.locals.da); }, proxyRes: async (proxyRes, req, res) => { const da = await new Promise((resolve, reject) => { setTimeout(() => { resolve({ wei: 'wei' }); }, 200); }); // end: res.setHeader('mpth-2', da.wei); proxyRes.pipe(res); }, }, }); app.use('/api', entryMiddleware, myProxy);

方案二的核心差异：

• 挂载顺序：app.use('/api', entryMiddleware, myProxy)保证请求先经过entryMiddleware完成异步计算，再进入代理中间件。entryMiddleware中await结束并调用next()之后，代理才会接管请求，因此req.locals.da在proxyReq触发时一定已就绪；
• 数据传递载体：req.locals是挂在http.IncomingMessage上的自定义属性（Express 生态惯用命名），也可以是req.customData等任意属性，只要前后两个中间件约定一致；
• 职责分离：异步逻辑集中在入口中间件，proxyReq内只做同步的setHeader，时序清晰、可测试。

从实现上看，这种"先跑前置中间件、再进入代理"的时序与 http-proxy-middleware.ts 中middleware的执行模型完全吻合：代理中间件是标准的三参/两参中间件，只有next()被调用后（或直接返回）才会继续；而prepareProxyRequest阶段本身也支持router、pathRewrite等异步操作，说明整个请求准备链路是异步友好的。

两个方案的选型对比

两者可同时使用（如上例所示），覆盖"请求头、响应头都需要异步增强"的完整闭环。

常见坑与最佳实践

1. 忘记pipe导致客户端挂起

selfHandleResponse: true意味着 httpxy 不再替你结束响应。若proxyRes中只改头不pipe也不res.end()，连接将一直悬置直至超时。务必在异步逻辑完成后执行proxyRes.pipe(res)。

2. 不要在proxyReq内依赖未就绪的异步数据

proxyReq事件派发是同步的，写在里面的await不会被等待。异步数据必须像方案二一样由前置中间件保证在next()之前就绪，proxyReq里只做同步读取。

3. 注意与responseInterceptor的分工

如果需求是"修改响应体"而不是单纯的响应头，官方提供了更完善的封装responseInterceptor（见 response-interceptor.ts 与 response-interceptor.md）。它同样要求selfHandleResponse: true，但会自动完成 brotli / gzip / deflate / zstd 解压、拦截 Buffer 回写、重新计算content-length、处理无响应体（HEAD、1xx、204、304）等细节。手动proxyRes.pipe(res)属于"原样透传 + 头部增强"的精简路线，改 body 时应优先考虑responseInterceptor。

4. 异步回调内的错误处理

async回调中的异常不会自动传递给 Express 的错误中间件，建议在回调内try/catch并在出错时res.end()或委托on.error事件处理；httpxy 的 Promise 式 API 在网络错误时也不会自动 emiterror，需要手动兜底（http-proxy-middleware.ts 中即通过this.proxy.emit('error', ...)兼容旧插件）。

5.target必填

无论哪种方案，target（或router）都是必需的，configuration.ts 中的verifyConfig会在缺失时抛出[HPM] Missing "target" option错误。

仓库内的相关资源

• 完整可运行示例：examples/response-interceptor/index.js（展示了selfHandleResponse+ 修改状态码与 content-type 的组合用法，可直接node运行在 3000 端口）
• 类型与配置定义：src/types.ts、src/configuration.ts
• 事件注册实现：src/plugins/default/proxy-events.ts
• 中间件主流程：src/http-proxy-middleware.ts
• 测试佐证：test/e2e/response-interceptor.spec.ts（覆盖压缩响应解压、无响应体 204/304、trailer 头处理等边界）
• 相关进阶文档：recipes/response-interceptor.md、recipes/proxy-events.md

原文档还附带了一个基于 Express 的在线可运行示例（支持通过 Server Control Panel 重启服务器并观察日志），可在本地以同样的createProxyMiddleware配置自行复现本文的两个示例，验证mpth-1、mpth-2头的实际注入效果。

小结

http-proxy-middleware 的异步能力体现在两个层面：proxyRes回调原生支持async/await，可以"先异步计算、再写响应头、最后 pipe 转发"；而proxyReq阶段的异步化则依赖前置中间件 +req对象暂存的标准中间件组合拳。掌握selfHandleResponse的语义与这两条链路，即可从容应对动态响应头、动态请求头、甚至两者叠加的真实生产需求。

• 后端
• API网关