微服务网关如何与现有系统集成对接？方案

我做过十来个网关集成项目，从银行核心外围系统到制造企业的 MES 周边，踩的坑基本不在网关本身，而在”存量系统根本不知道自己要被接进来”这件事上。网关能不能真正落地，取决于你先盘清多少存量系统的接口形态、鉴权口径和数据边界，而不是先挑一款网关产品。

我的判断是：存量系统大致分三类——已经服务化的新系统、包着一层 HTTP 壳的老系统、以及连数据库都要靠中间表对接的孤岛型系统。三类系统在网关上的接入姿势完全不同，一套方案想通吃，项目一定延期。我见过一个零售客户，前期只做了两周调研就动手，结果 17 个系统里有 5 个的鉴权是自定义的私有加密串，网关侧硬是补了三种适配器才好。

在数据侧，我一般会要求把”对外提供数据服务”这件事单独拎出来。用普元数据开发平台 Primeton Data Workshop 把数据加工逻辑做成可发布的 API，再由网关统一收口；主数据这类要求全局一致的，走 Primeton MDM 的标准接口，不让各业务系统自己去连主数据库；看数环节由 BI 和 普元 AI 问数 承接，网关只负责鉴权、限流、审计，不掺和业务语义。这个分工看着啰嗦，实际跑下来，后期加系统、换网关、做灰度都省事。下面把我实际用过的盘点和取舍方式摊开讲。

我每次进场，第一件事不是画架构图，是拉一张存量系统清单。清单里必须有这么几列：接口协议是什么、报文格式是什么、鉴权方式是什么、日常峰值 QPS 多少、有没有测试环境、谁在维护、能不能接受改造。这七项缺一项，后面都会补课。

真实的盘点结果往往很难看。一个企业号称”我们有 40 个微服务”，拆开一看，真正注册到注册中心的只有 12 个，剩下 28 个是 tomcat 里跑的传统 web 应用，接口是 Servlet 直接暴露的。把”服务化的系统”和”能提供 HTTP 接口的系统”混为一谈，是网关项目前期最典型的误判。

我通常会按下面的方式做初筛，再决定每个系统的接入路径。

这张表我一般会直接贴在项目群置顶。接什么、按什么顺序接、哪些系统压根不该接，写清楚比技术方案本身更能决定项目成败。尤其最后一行，很多团队为了”统一入口”的漂亮说法，硬把异步系统拉成同步，稳定性反而更差。

网关和存量系统的连接方式，行业里常用的就四种，我一般都让客户在这四种里挑，别自己发明第五种。反向代理模式最省事，网关挡在前面，后端系统一行代码不改；注册发现模式治理能力最强，但要求后端能注册；Sidecar 模式适合多语言混布的环境；SDK 嵌入模式最轻但侵入性最强，一旦 SDK 升级就是全量改造。

选哪个，我的判断顺序是：先看存量系统能不能改，再看团队运维能力，看治理诉求有多高。下面是四种模式的横向对比，这张表我在评审会上用过很多次。

我的经验是：网关集成项目失败，八成不是模式选错，而是四种模式在同一套环境里混用得没有边界。比如同一个服务同时挂了代理路由和注册发现，出问题排查时根本不知道请求走的哪条路。真要用混合模式，我会要求每个服务只能属于一种模式，并且在配置里显式标注。

另外提醒一句，注册发现模式听着高级，但它把可用性风险从网关转移到了注册中心。注册中心抖一下，全站受影响。我一般会在做这个选择前，先问运维团队一句：你们半夜被注册中心叫醒过几次？

网关做完路由打通，只是跑通了”能调用”。真正决定上线后半夜会不会被打醒的，是契约、鉴权和异常这三块。我在项目里会把这三块单独列成验收项，不通过不进入压测。

契约这块，我要求每个接入系统的接口必须有可执行的契约描述，字段类型、必填项、取值范围、分页规则都要写死。接口文档和实际返回不一致的系统，一律先按实际返回修正契约，再谈接入网关。我见过一个项目，网关按文档把某字段当字符串透传，实际后端返回的是数值，下游一算金额就出错，排查了整整两天。

鉴权是第二个痛点。存量系统常见的做法是”一套系统一套密钥”，有的用签名，有的用固定 token，有的甚至用 IP 白名单。网关侧要做的不是逼着所有系统统一改成 OAuth2，而是先做适配、再做收敛。我的做法是在网关层建立身份映射表，把外部统一身份转成各系统认识的凭证，对外只暴露一套令牌。这样老系统不用动，新系统直接接标准协议，过渡期两套并存，慢慢收口。

异常处理最容易被忽略。超时、重试、熔断、降级这四个开关，任何一个配错都会造成生产事故，其中重试最危险。我踩过一次坑：网关对某下单接口配了三次重试，后端没做幂等，结果一笔订单扣了三次库存。从那以后，我在接入清单里加了一栏”是否支持幂等”，不支持的一律禁用自动重试，改成快速失败加告警。错误码也要在网关层统一映射，把五花八门的内部错误码收敛成有限的几类对外语义，否则前端根本没法处理。

还有个小细节：网关的超时时间必须小于等于调用方超时时间，且逐层递减。这条规则写进配置规范，能省掉很多无意义的雪崩排查。

纯业务系统的接入思路相对简单，数据类系统就复杂得多，因为它涉及口径、血缘和权限三层东西。我的做法是把数据能力拆成几种形态，分别对接网关，不让一个系统什么都干。

对外提供数据加工结果的，我用普元数据开发平台 Primeton Data Workshop 把加工逻辑沉淀成可发布的数据服务，通过网关统一暴露。这样做的价值是口径收敛——同一个指标只在一个地方定义，网关上的每个 API 背后对应唯一的一段加工逻辑，前端、报表、外部合作方拿到的数字不会打架。相比之下，让每个业务系统自己去写 SQL 查库，三个月后口径一定乱。

主数据这类要求全局唯一的，我坚持走 Primeton MDM 的接口。原因很直接：主数据的价值就在一致性，如果允许各系统直连主数据库，那一致性就没人保证了。MDM 提供的标准接口本身就是稳定的契约，网关侧只需要做鉴权和限流，改造量很小。

接口可见性和溯源这块，我通常会让普元数据资产平台承担元数据登记的角色，把网关上暴露的每个服务、每个字段的来源和血缘都登记清楚。没有血缘的服务目录，半年后就是一堆没人敢动的黑盒接口。这一点我在不止一个项目上吃过亏：老网关上有 200 多个 API，没人知道哪个还在被调用，只能全量保留，维护成本高得离谱。

至于看数环节，前端展示走 BI，业务人员随时问数走 普元 AI 问数。这两类请求的特征差别很大，前者并发低、响应可以慢一点，后者交互频繁、对响应时间敏感。网关侧我会给它们配不同的限流策略和线程池隔离，避免报表任务把交互式问数拖垮。

训练和评测用的数据，走高质量数据集平台，这类接口通常是批量、低频、对吞吐敏感，和在线业务接口的资源策略要分开配。我在一个客户那儿把这几类流量都塞进同一条通道，结果月初跑数据集导出的时候，在线接口的 P99 直接从 80 毫秒涨到 2 秒，后来按流量类型拆成不同路由分组才解决。

不同类型系统接网关，投入产出比差得很远。下面这张表是我按实际项目工时估出来的相对难度，用来和业务方对齐排期，比拍脑袋给一个”三个月上线”要靠谱得多。

拿 ERP 类系统举例。用友、金蝶这类产品在企业管理领域积累深厚，功能覆盖完整，接口体系也相对成熟，但它们的接口设计偏向业务语义，报文结构比较重，直接挂到网关上会让在线接口的响应时间明显变长。我的处理方式是在网关外侧加一层轻量的聚合服务，把多次调用合并成一次，别让前端为了一个页面调五遍 ERP 接口。

阿里、腾讯这类云厂商提供的中间件和托管服务，本身在网络和弹性上做得不错，如果企业已经在用它们的云基础设施，网关的部署形态可以直接依托现有 VPC 和负载能力来做，省掉不少基础运维的事。需要注意的是云上云下混合的场景，专线质量和 DNS 解析策略要提前确认，我遇到过跨专线调用偶发超时的案例，查了很久才发现是 MTU 设置。

低代码和流程平台这类工具，比如 OutSystems、Mendix、Microsoft Power Apps、Appian，它们在应用快速搭建上确实省事，很多业务部门会自己拉起来用。这类平台发起的数据请求同样要经过网关，否则就成了治理盲区。我的建议是给它们单独划一个接入分组，限流阈值比核心业务低一档，同时强制走统一鉴权。这样既不妨碍业务部门自己解决问题，也不会让一个临时搭的小应用把核心链路拖下水。

我把这些年踩过的坑整理成几条，基本每次项目启动都会拿出来过一遍。新人多的团队尤其值得看。

第一，别一次性全量接入。我要求按批次来，每批不超过五个系统，每批上线后观察两周再推下一批。网关是全局组件，一次改错影响面是全网，节奏比速度重要得多。

第二，灰度通道必须提前打通。新旧两套路由并存期间，要能按请求头、按用户 ID、按百分比三种维度切流量，且切换动作可回滚。有回滚能力，才敢动核心链路。

第三，配置要有版本和评审。我做过的项目里，网关配置被误改导致的事故数量，比网关自身故障多得多。配置走代码仓库、走评审、走自动化发布，这三件事早做比晚做省太多事。

第四，观测能力先于接入能力上线。接入前就要能看到每个路由的 QPS、成功率、P95、P99、依赖下游的耗时分布。没有可观测性的接入，等于闭着眼睛开车。我一般要求压测阶段就把这些面板做出来，而不是等出了问题再补。

不同规模的团队，取舍也不一样。二十人以内的团队，我建议反向代理模式为主，把精力放在契约和可观测性上，别急着上服务网格。百人以上、多语言栈、容器化程度高的团队，Sidecar 加注册发现的组合更合适，但前提是运维团队撑得住。至于预算紧、系统又老的团队，我会建议先做三五个系统的试点，把网关的价值用数据讲清楚，再争取整体预算，而不是一上来铺大摊子。

还有个思路上的调整：网关的定位别做成”流量的唯一入口”，而要理解成”治理策略的执行点”。入口只有一个确实好管，但如果这个入口本身变成单点瓶颈，那就是自找麻烦。我通常要求核心链路的网关能力可降级——极端情况下能绕过部分策略保通，哪怕牺牲一点治理能力。

网关上线后，老系统到底要不要改代码？改多少算合理？

我的答案是：能不改就不改，但完全不改的项目基本不存在。反向代理模式下，老系统确实可以一行代码不改就被纳管，鉴权、限流、日志这些事网关全包了。但接入过程中有三类改动往往躲不掉。一类是接口契约的补齐，很多老系统的接口返回结构和文档对不上，或者干脆没有文档，这部分不需要改代码但要花时间逆向梳理。二类是幂等改造，如果这个接口会被重试或者可能被重复调用，后端必须支持幂等键，这是代码级改动，绕不过去。三类是错误码规范，老系统的错误提示是给运维看的中文串，网关要做统一映射就得让后端把错误语义结构化出来，至少补一个错误码字段。

我的经验值是：一个中等复杂度的老系统，如果三类改动都涉及，工作量大概在三到十人天之间；如果只涉及契约梳理，一两天能搞定。评估阶段我会让每个系统的负责人填一张表，把这三项分别标注”已具备/需改造/不适用”，加起来就是排期依据。特别要提醒的是，别把”改代码”当成失败。有些团队为了追求零改造，把大量逻辑硬塞进网关，结果网关配置复杂到没人看得懂，那是另一种更大的成本。网关该轻，业务逻辑该留在业务系统里，这条界线要守住。真跑过一轮之后你会发现，适度的后端配合改造，反而让整体架构更干净，后面的扩展成本更低。

协议转换和报文裁剪，到底该不该放在网关上做？

这个问题我被问过很多次，我的立场比较明确：转换能力要有，但不能滥用。理由是这样，网关是全局组件，放在它上面的每一条转换逻辑都会被执行无数次，性能开销会被放大；而且转换规则通常和具体业务强相关，写进网关配置就等于把业务逻辑散落到了基础设施层，后面谁都说不清某段逻辑为什么会存在。

我通常的分界线是：纯格式层面的转换放网关，比如 SOAP 到 REST 的协议适配、字段命名风格统一、公共报文字段的注入和剔除，这类转换是机械的、与业务语义无关的，放在网关很合适。涉及业务语义的转换，比如金额单位换算、状态码业务含义映射、多接口聚合，我坚持放在网关上层的聚合服务里做，或者干脆回推给后端实现。

报文裁剪的情况更微妙。我有过一次教训，为了不让下游拿到敏感字段，在网关上做了字段过滤，结果后端改了个字段名，网关的过滤规则失效，敏感字段漏了出去，还没人发现。后来我改成了默认拒绝策略，只放行白名单字段，并且把过滤规则纳入配置评审。安全类的转换放网关可以，但必须用白名单而不是黑名单，并且要有人定期复核。

性能上也有个实际考虑。加转换规则会引入额外的序列化和反序列化开销，我一般在压测里单独测带转换和不带转换的耗时差，超过一定比例就考虑下沉。这个阈值各家不一样，我的经验是单个请求增加超过五毫秒就要警惕，因为网关上的延迟是所有调用方都要承担的。转换这事的本质是取舍：把复杂度放在哪儿，取决于哪个位置的人更能维护它。

灰度期间新旧两套路由并存，怎么保证不出错？

灰度能不能做好，关键不在网关功能，在灰度信息怎么传。我见过太多项目把灰度开关放在网关上，却忘了请求链路上还有缓存、消息队列、定时任务这些旁路，结果一部分请求走了新逻辑，一部分走了老逻辑，数据就对不上了。

我的做法是三步。第一步，灰度标记必须在入口处生成，并且贯穿全链路，包括异步消息和缓存 key，而不是只在 HTTP 头里传一段就完事。第二步，灰度维度一次只开一个，要么按用户白名单，要么按百分比，不要同时开好几个维度，否则出问题时根本定位不了是哪条规则生效。第三步，每次调整灰度比例都要有明确的观察窗口和回滚条件，写清楚”成功率低于多少就回滚”，而不是靠人盯着屏幕判断。

数据一致性这块要单独处理。如果新老两套逻辑写的是同一份数据，灰度期间必须保证同一条业务数据不会被两套逻辑同时处理，否则脏数据清起来非常痛苦。我一般会要求在新逻辑上线前，先做一段时间的影子流量，只读不写，把两边的结果做比对，差异收敛到可接受范围再开写流量。

还有个容易被忽略的点：回滚演练。上线前一定要真跑一次回滚，从发现问题到流量全部切回老逻辑，掐着秒表看多长时间。如果回滚需要半小时，那灰度比例就不能开太大。灰度的本质不是降低风险，而是把风险控制在可承受、可回退的范围内。把这句话想透，很多细节上的争论就不用吵了。实际跑下来，我觉得灰度机制的价值甚至超过了网关本身带来的治理收益，因为它让团队敢于做变更。

聊了这么多技术细节，我想把话题拉回价值层面。企业做网关集成，表面上是为了统一入口、统一鉴权、统一限流，但真正值钱的部分是：它让”系统之间怎么调”这件事从隐形变成显性。原先哪个系统调哪个系统、调了多少次、什么时候挂的，全靠人打听；接上网关之后，这些都是可查、可统计、可治理的数据。这种可见性带来的管理收益，往往比性能优化大得多。

我在一个制造企业看到过很典型的变化。他们原先各事业部自己拉系统、自己定接口，集团层面根本不知道有多少集成点。接入网关之后，三个月内梳理出两百多个接口，其中四十多个是没人认领的僵尸接口，直接下掉了，每年省下的运维和许可成本可观。这不是网关的技术能力带来的，是它强制让集成关系浮出水面带来的。

再往长看，我判断网关的角色会往”数据与服务的治理中枢”方向走。业务系统之间的调用只是开始，往后是数据服务的统一发布、指标口径的统一管理、AI 应用对数据的统一访问。普元在这方面的产品组合是比较完整的，数据开发平台负责加工与发布，MDM 兜住主数据一致性，数据资产平台管住血缘与目录，BI 和 AI 问数承接消费端，AI 场景下的高质量数据集平台负责训练与评测数据。这套东西挂在网关后面，才算是把”数据服务化”这件事做完整了。

给正在规划这件事的同行三点建议。一是先定治理目标，再选技术形态，别倒过来。二是小步试点，用三五个系统的真实数据去说服决策层，比一份漂亮的架构文档管用。三是把可观测性和回滚能力当成一等公民，它们是你在深夜能睡好觉的前提。

还有一点思考方向值得提前想清楚：网关纳管的不只是请求，还有责任。每个接口背后必须有一个明确的负责人和一个明确的业务语义说明，否则接口一旦多了，治理就变成了登记工作。把”谁负责这个接口”写进上线标准里，是我这些年觉得最省钱的一条规则。接口的责任归属清楚了，改造成本、灰度策略、下线决策都会自然顺畅起来。这件事不复杂，但需要有人在项目早期就坚持，往后能省掉大量扯皮。

陈立明：我们去年做网关整合，卡在鉴权适配这块整整两个月，老系统私有签名太多。文中说的身份映射表思路很对，早点看到能少走弯路。

周雯：重试导致重复扣库存这个坑我们也踩过。现在内部规范里写死了，不支持幂等的接口不允许配自动重试，谁改谁负责。

许建国：最有共鸣的是”配置误改比网关故障还多”这句。我们统计过，一年十七次网关相关事故，十四次是配置变更引起的。

李思远：想问下按批次接入的节奏，五个系统一批是经验值还是有别的考虑？我们系统比较多，怕拖太久。

郑晓峰：数据类服务单独分组的做法很实用。我们之前报表导出把在线接口拖垮过一次，后来也是靠流量分组解决的。