后端API网关【免费下载链接】http-proxy-middleware:zap: The one-liner node.js http-proxy (httpxy) middleware for connect, express, next.js and more项目地址https://gitcode.com/gh_mirrors/ht/http-proxy-middleware点击查看免费下载http-proxy-middleware的 v3 版本对配置模型做了一次系统性重构挂载路径处理、pathRewrite语义、日志配置与代理事件订阅方式均发生破坏性变更。本文以仓库内官方迁移文档 MIGRATION_V3.md 为主线逐项拆解每一条 breaking change 的「前后对比、迁移步骤与影响范围」并结合 src 目录下的实际源码实现与 CHANGELOG.md 佐证底层原理。读完本文你将能够把基于 v2 编写的代理配置createProxyMiddleware调用、context参数、logLevel/logProvider选项、onError/onProxyReq等事件回调完整升级到 v3 语法并理解其背后为什么这样改的设计动机。一、v3 变更全景一次面向可组合性的重构v3.0.0 的破坏性变更不是零散的 API 调整而是围绕「配置职责更清晰、扩展方式更统一」这一目标展开的系列重构。从 CHANGELOG.md 的 v3.0.0 发布记录可以看到这批变更的完整清单其中与迁移强相关的破坏性变更包括context参数重构为pathFilter选项PR #722移除 shorthand 用法PR #716服务挂载server mounting行为变更PR #731——即本文档中的「移除req.url修补」handlers 重构为插件机制PR #745日志系统重构PR #749——即移除logProvider/logLevel新增ejectPlugins选项PR #750与legacyCreateProxyMiddleware适配器PR #754/#756。官方迁移文档将上述变更归纳为六类破坏性变更下文逐一展开。每一条都给出 v2「before」与 v3「after」的对照代码并尽量标注仓库内的源码依据。二、v2 → v3 适配器legacyCreateProxyMiddleware如果你希望以最小改动升级到 v3官方提供了兼容适配器legacyCreateProxyMiddleware。它的定位是沿用 v2 的写法获得 v3 的运行时兼容。// before const { createProxyMiddleware } require(http-proxy-middleware); createProxyMiddleware(...); // after const { legacyCreateProxyMiddleware } require(http-proxy-middleware); legacyCreateProxyMiddleware(...);TypeScript 场景下选项类型也一并提供了对应的 legacy 版本// before import { createProxyMiddleware, Options } from http-proxy-middleware; createProxyMiddleware(...); // after import { legacyCreateProxyMiddleware, LegacyOptions } from http-proxy-middleware; legacyCreateProxyMiddleware(...);使用适配器时有两个要点见 MIGRATION_V3.md运行时迁移提示当使用legacyCreateProxyMiddleware时程序运行期会向控制台打印迁移指引消息告诉你每处 legacy 配置应该如何改写为 v3 语法生命周期有限官方明确说明legacyCreateProxyMiddleware将在未来版本移除。事实上从 CHANGELOG.md 可以确认后续 v4 版本的 changelog 已记录remove legacyCreateProxyMiddleware()这一破坏性变更。因此它只适合作为临时过渡不建议长期依赖。三、移除req.url修补挂载路径需显式写入 target这是 v3 中最容易踩坑的一条变更。v2 中当代理通过app.use(/user, proxy)这类带路径的挂载方式使用时中间件会自动把挂载路径/user拼接到转发请求上即自动修补req.url。v3 移除了这一自动行为挂载路径必须由你自己写进target。// before app.use(/user, proxy({ target: http://www.example.org })); // after app.use(/user, proxy({ target: http://www.example.org/user }));原因在于v3 认为挂载路径属于服务端路由的职责目标路径属于代理配置的职责二者不应隐式耦合。这一设计也使代理行为在 connect、express、hono、next.js 等不同服务器框架间保持一致各框架示例见 examples 目录。这条变更也与 README.md 中 v4 的推荐用法一脉相承——v4 示例里app.use(/api, proxyMiddleware)与target: http://www.example.org/api需要成对配置注释明确写着proxy and keep the same base path /api。四、pathRewrite潜在行为变化只重写挂载点之后的路径pathRewrite的语义变化与上一条直接相关。v3 中pathRewrite只作用于挂载点之后的 path 部分在 Express 中即相对 mount-point 的路径不再能看到完整的、包含挂载前缀的 URL。v2 中常见的用pathRewrite重写 basePath的写法需要改写为把重写结果直接放进target。// before app.use( /user, proxy({ target: http://www.example.org, pathRewrite: { ^/user: /secret }, }), ); // after app.use(/user, proxy({ target: http://www.example.org/secret }));有一种情况不受影响当代理直接挂载在根路径root时pathRewrite行为与 v2 完全一致仍然可以匹配并重写完整路径// not affected app.use( proxy({ target: http://www.example.org, pathRewrite: { ^/user: /secret }, }), );从源码实现看pathRewrite的对象形式会把每个 key 编译为RegExp并缓存规则命中第一条规则即替换见 src/path-rewriter.ts而applyPathRewrite重写的是req.url本身见 src/http-proxy-middleware.ts。由于 v3 不再为req.url预拼接挂载前缀pathRewrite自然只能匹配到挂载点之后的路径——这就是潜在行为变化的源码级原因。此外src/types.ts 中的PathRewriteConfig类型还支持函数形式含异步函数函数签名新增了res与options参数v4.1.0 起并注明 WebSocket upgrade 流程中res为undefined。五、移除 shorthand 用法target必须显式指定v2 允许把目标地址字符串直接作为第一个参数传入// before createProxyMiddleware(http://www.example.org); // after createProxyMiddleware({ target: http://www.example.org });v3 起所有配置必须统一走options对象。这一约束在源码层面得到了强制校验verifyConfig会在target与router都缺失时抛出ERR_CONFIG_FACTORY_TARGET_MISSING错误见 src/configuration.ts提示信息即为[HPM] Missing target option. Example: {target: http://www.example.org}。换句话说从 v3 开始没有 target 的代理是不合法的配置除非提供了动态路由router。六、移除context参数迁移至pathFilter选项v2 的第一个位置参数context承担了匹配哪些请求的职责v3 将其正式化为pathFilter选项功能完全不变// before createProxyMiddleware(/path, { target: http://www.example.org }); // after createProxyMiddleware({ target: http://www.example.org, pathFilter: /path, });pathFilter是一个比context更强大的过滤器支持字符串、字符串数组、glob 通配符以及自定义函数四种形态完整用法见 recipes/pathFilter.mdpathFilter: /api匹配以/api开头的路径pathFilter: [/api, /rest]多路径匹配命中其一即代理pathFilter: /api/**/*.jsonglob 通配匹配由micromatch实现pathFilter: (pathname, req) ...自定义函数返回布尔值决定是否代理。其底层实现在 src/path-filter.ts对字符串路径使用indexOf(pathFilter) 0的前缀匹配对 glob 使用micromatch对函数则传入pathname通过new URL(uri, ...).pathname解析见 src/path-filter.ts与req对象。值得注意的实现细节是同一数组中不能混用普通字符串路径与 glob 通配符否则会抛出HPM_INVALID_PATH_FILTER_ARRAY_CONFIG错误见 src/path-filter.ts。在 src/http-proxy-middleware.ts 的中间件主流程中shouldProxy会先调用matchPathFilter判断请求是否命中未命中时直接调用next()放行命中的请求才进入后续的路由、路径重写与转发阶段。七、移除logProvider与logLevel改用外部日志库的logger选项v2 通过logProvider指定日志实现、logLevel控制日志级别v3 将两者一并移除改为将你的外部日志库实例直接注入logger选项由外部库负责日志输出与级别控制。// new createProxyMiddleware({ target: http://www.example.org, logger: console, });这里有一个重要的兼容性约定内部只会使用info、warn、error三个方法见 MIGRATION_V3.md这是为了兼容不同日志库而设计的最小公共接口。在 src/logger.ts 的兼容矩阵中可以看到日志库loginfowarnerror字符串插值%s/%o/%Oconsole✅✅✅✅✅bunyan❌✅✅✅✅pino❌✅✅✅✅winston❌✅✅✅✅需手动开启log4js❌✅✅✅✅矩阵揭示了两个关键点主流日志库pino、bunyan、winston、log4js都没有通用的log方法因此 v3 内部统一使用info/warn/error若使用winston必须显式开启字符串插值format.splat()否则%s、%o等占位符不会被替换。winston 的完整配置示例见 recipes/logger.md。未配置logger时src/logger.ts 会注入一个noopLogger空实现三个方法均为空函数保证在任何环境下都不会因日志调用而崩溃。此外与logLevel被移除相对应v3 引入了基于环境变量的DEBUG调试机制DEBUGhttp-proxy-middleware* node server.js用于排查转发过程中的细节日志见 README.md。八、代理事件重构从扁平回调到on选项v3 将分散的onError、onProxyReq、onProxyRes、onProxyReqWs、onOpen、onClose六个回调统一收纳进on选项对象事件名从「驼峰前缀」改为「小写事件名」与底层httpxy的事件名一一对应// before createProxyMiddleware({ target: http://www.example.org, onError: () {}, onProxyReq: () {}, onProxyRes: () {}, onProxyReqWs: () {}, onOpen: () {}, onClose: () {}, }); // after createProxyMiddleware({ target: http://www.example.org, on: { error: () {}, proxyReq: () {}, proxyRes: () {}, proxyReqWs: () {}, open: () {}, close: () {}, }, });事件回调的完整签名与用法见 recipes/proxy-events.md可用事件包括error、proxyReq、proxyReqWs、proxyRes、open、close以及start、end、econnreset。各事件回调的 TypeScript 类型定义在 src/types.ts 中error(err, req, res, target)代理出错可自定义错误响应如res.writeHead(500)proxyReq(proxyReq, req, res, options)转发前修改请求如proxyReq.setHeader(x-added, foobar)proxyReqWs(proxyReq, req, socket, options, head)WebSocket 转发前钩子proxyRes(proxyRes, req, res)响应返回后修改响应头如delete proxyRes.headers[x-removed]open(proxySocket)/close(res, socket, head)WebSocket 连接建立/断开。需要说明的是on选项本身也是 v3 插件化架构plugins的一部分它由默认插件proxyEventsPlugin实现见 src/plugins/default/proxy-events.ts。若你通过ejectPlugins: true弹出了默认插件就必须手动把proxyEventsPlugin加回plugins数组on选项才会生效——完整示例见 README.md。同时v3 也开放了definePlugin帮助函数用于编写自定义插件见 src/plugins/define-plugin.ts 与 README.md。九、源码视角v3 配置的校验与执行顺序理解了以上六条变更后再从源码层面串一遍 v3 的完整执行链路有助于写出符合新语义的配置实现集中在 src/http-proxy-middleware.ts构造阶段HttpProxyMiddleware构造器首先调用verifyConfig校验target/router必须至少存在其一src/configuration.ts然后创建httpxy代理服务器、注册插件、预编译pathRewrite规则src/http-proxy-middleware.ts过滤阶段中间件执行时先用shouldProxymatchPathFilter判断是否代理不匹配则next()放行src/http-proxy-middleware.ts准备阶段prepareProxyRequest依次应用router动态目标→pathRewrite路径重写顺序固定——路由基于原始路径判定不受 pathRewrite 改写结果影响src/http-proxy-middleware.ts。这一顺序注释明确写在源码注释中Router uses original path for routing; NOT the modified path转发阶段调用proxy.web(req, res, options)转发网络错误时手动emit(error)以兼容插件与on.error监听器src/http-proxy-middleware.ts。这套链路解释了为什么 v3 要求挂载路径写入 target因为路径重写发生在req.url上而req.url不再包含挂载前缀所有与目标路径相关的定制都必须前移到target配置中完成。十、v2 → v3 迁移检查清单最后把官方迁移文档中的要点汇总成一份可直接对照执行的清单检查项v2 写法v3 写法是否破坏性目标地址传入方式createProxyMiddleware(http://...)createProxyMiddleware({ target: http://... })是shorthand 已移除请求匹配createProxyMiddleware(/path, options)createProxyMiddleware({ pathFilter: /path, ... })是context已移除带路径挂载app.use(/user, proxy({ target: http://... }))app.use(/user, proxy({ target: http://.../user }))是req.url不再被修补basePath 重写pathRewrite: { ^/user: /secret }直接写入target如target: http://.../secret是根挂载时不受影响日志配置logProvider/logLevellogger: console或 winston/pino 等内部只用 info/warn/error是两个选项已移除代理事件onError/onProxyReq/onProxyRes/onProxyReqWs/onOpen/onCloseon: { error, proxyReq, proxyRes, proxyReqWs, open, close }是事件已重构平滑过渡—legacyCreateProxyMiddlewareLegacyOptions注意未来版本将移除非破坏性过渡手段迁移顺序建议先全局替换legacyCreateProxyMiddleware跑通运行时提示 → 按提示逐条改写target/pathFilter/on/logger→ 全部改写完成后换回createProxyMiddleware并运行测试验证。仓库中现成的集成测试如 test/e2e/http-proxy-middleware.spec.ts、test/unit/path-filter.spec.ts、test/unit/path-rewriter.spec.ts、test/unit/configuration.spec.ts可以作为迁移后回归验证的参考用例。赞分享后端API网关【免费下载链接】http-proxy-middleware:zap: The one-liner node.js http-proxy (httpxy) middleware for connect, express, next.js and more项目地址https://gitcode.com/gh_mirrors/ht/http-proxy-middleware点击查看免费下载相关推荐Actix Web 4.0 升级迁移完全指南从 v3 到 v4 的 Breaking Changes 逐项解析与实战迁移Actix Web 4.0 升级迁移完全指南从 v3 到 v4 的 Breaking Changes 逐项解析与实战迁移 导读 本文以 actix web/M后端Web框架ahooks v2 到 v3 升级完整指南全新 useRequest、SSR 支持与 Breaking Changes 逐项解读ahooks v2 到 v3 升级完整指南全新 useRequest、SSR 支持与 Breaking Changes 逐项解读 本文基于官方 upgrade前端http-proxy-middleware 版本迁移指南从v2升级到v3的最佳实践http proxy middleware 版本迁移指南从v2升级到v3的最佳实践 前言 http proxy middleware 是一个功能强大的 Nod后端API网关创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考