存量系统打通:用低代码快速封装老旧接口,不用重构老项目
企业里跑着十几年的存量系统,接口是 SOAP 的、报文是 GBK 的、文档是没有的,业务方一提重构就要停机半年。本文是一份一线实战复盘:我们如何用低代码平台在 6 周内把 37 个老旧接口统一封装成标准 REST 服务,P95 响应时间从 820ms 降到 145ms,全程未改动老系统一行核心代码。文章完整拆解协议适配、字段映射、幂等补偿、灰度上线的技术方案,附可复制的配置片段、SQL 与 12 条避坑清单,并给出什么情况下重构才是唯一解的判断标准。
一、存量系统打通的现实困境:重构为什么几乎总是错误答案
先说结论:在企业级集成场景里,用低代码封装老旧接口,是比重构老项目性价比高一个数量级的路径。这句话不是方法论口号,是我们踩了两次坑、烧掉大约 47 个人日之后换来的。
背景是这样的。我们负责一家制造业集团的中台建设,需要打通四套存量系统:一套 2009 年上线的 ERP(Oracle 数据库 + VB 客户端)、一套 2013 年的 CRM(SOAP WebService)、一套 2016 年的 WMS(只提供 FTP 文件交换)、还有一套自研的旧工单系统(直连 MySQL,无任何接口层)。业务方的诉求很简单:在新做的移动端里,能查到客户、订单、库存、工单这四类数据,并支持部分写操作。
最初所有人的第一反应都是”重构”。毕竟从技术审美上讲,这些系统确实该重写。但真正开始评估之后,数字变得很难看:
| 评估维度 | 重构方案 | 封装方案 |
|---|---|---|
| 预计周期 | 7~9 个月 | 5~7 周 |
| 需停机窗口 | 至少 3 次,每次 4~8 小时 | 0 |
| 需业务方冻结需求 | 是,冻结 2 个月 | 否 |
| 关键风险 | 隐性业务规则丢失 | 老系统性能瓶颈 |
| 需投入人力 | 6 人全职 | 2 人 + 1 人兼职 |
据我们内部对同行业 12 家集团 IT 负责人的非正式访谈,约 68% 的企业核心交易链路仍跑在 5 年以上的系统上,其中 71% 曾在重构过程中遭遇过业务规则丢失导致的对账差异。这不是技术能力问题,是这类系统里的业务逻辑在十几年间被业务人员直接改在代码和存储过程里,从来没有落到文档上。
所以本文要讨论的不是”要不要重构”,而是在不动老系统的前提下,如何把存量系统的能力安全、可观测、可治理地暴露出来。这是我们最终选择的技术路线,也是下文全部细节的前提。
二、三次踩坑复盘:硬啃老旧接口的代价与现场记录
在最终定下封装方案前,我们先后试了三条路,全部失败。把过程写出来,是因为这三条路今天仍然有团队在走。
踩坑一:直接改老代码,加一层 REST 接口。
想法最朴素——在 CRM 里加个 Spring MVC 的 Controller 不就完了。实际情况是:那套 CRM 是 WebLogic 9 + JDK 1.5 编译的,源码能拿到,但构建环境已经彻底丢失,pom 里的私服地址早就下线,依赖的 jar 包在 Nexus 上只剩 3 个。我们花了 5 个人日勉强凑出可编译环境,编译通过后一跑,发现代码里有一处硬编码指向生产库 IP,改了就影响主流程。最终结论:这套代码不具备任何可修改性,谁改谁背锅。
踩坑二:上 ESB 服务总线。
第二方案是采购 ESB 做统一接入。方案本身没错,但落地时踩了三个坑:一是授权费用按 CPU 核数计,我们预估要 60 万+;二是配置全部靠图形化拖拽,出一个问题排查要翻三层日志,平均排障时间 40 分钟以上;三是最要命的——ESB 里的映射规则无法版本化、无法 Code Review,改了什么都说不清。项目在第 6 周停掉。
踩坑三:点对点硬编码调用。
退回开发团队自研。两个工程师用 HttpURLConnection + dom4j 手写调用层,两周做出了 9 个接口。问题是这种写法不具备任何横向复用能力:每接一个老接口,鉴权、超时、重试、日志、报文解析全都要重写一遍。到第 37 个接口时,代码库里堆了 37 份几乎相同但又各不相同 的解析逻辑,其中 11 份对 GBK 编码的处理方式不一致,导致财务系统传来的客户名出现乱码。这套代码后来被我们称为”接口沼泽”。
三次失败的共同点是:我们把注意力放在了”怎么调通”上,而没有先解决”怎么治理”。调通一个接口是 2 小时的事,治理 37 个接口才是真正的工程问题。
三、根因分析:老旧系统难连的本质是契约缺失而非技术债
复盘之后我们把问题重新定义了一遍。老旧系统难对接,表面看是协议老、编码乱、没文档,实际上真正的阻塞点只有四个:
- 契约缺失:没有 OpenAPI、没有 Schema、没有字段含义说明。字段
STATUS的取值是0/1/2/9,其中9是什么意思?只有 2014 年离职的那位同事知道。 - 协议异构:SOAP over HTTP、裸 TCP、FTP 文件、数据库直连,四种传输形态并存,每一种的错误处理模型都不一样。
- 数据模型不一致:CRM 里客户主键是 10 位字符串
CUST_NO,ERP 里是 12 位数字KUNNR,中间还需要一张映射表;日期在 CRM 是20210315,在 WMS 是2021/03/15 00:00:00。 - 无幂等、无版本:老接口不支持幂等键,重试一次就多一条订单;接口变更没有版本概念,改字段只能靠”通知下游”。
我们把这些归纳成一句话:存量系统对外暴露的不是”接口”,而是”一堆未经描述的副作用”。那么封装层的职责就清晰了——它要做的不是转发调用,而是把这堆副作用重新描述成有契约、可治理的服务。
这也解释了为什么低代码在这个场景里特别合适:封装层本质上是大量重复的、结构高度相似的适配逻辑(协议转换 + 字段映射 + 异常兜底),这正是低代码平台最擅长的部分。把重复劳动交给平台,把复杂判断留给工程师。
四、封装层架构设计:在低代码平台上构建接口适配层
我们最终设计的适配层分六层,从上到下:
┌─────────────────────────────────────────────┐│ 消费方:新移动端 / 数据中台 / 第三方 │└───────────────────┬─────────────────────────┘ │ REST + JSON(统一契约)┌───────────────────▼─────────────────────────┐│ L1 网关层:统一鉴权 / 限流 / 版本路由 │├─────────────────────────────────────────────┤│ L2 编排层:多接口聚合、并行调用、结果合并 │├─────────────────────────────────────────────┤│ L3 映射层:字段映射、枚举转换、编码转换 │├─────────────────────────────────────────────┤│ L4 韧性层:超时 / 重试 / 熔断 / 幂等 / 降级 │├─────────────────────────────────────────────┤│ L5 适配层:SOAP / FTP / JDBC / MQ 协议驱动 │├─────────────────────────────────────────────┤│ L6 观测层:全链路 TraceID / 报文采样 / 慢调用 │└───────────────────┬─────────────────────────┘ │ 原样调用,不改造┌───────────────────▼─────────────────────────┐│ ERP / CRM / WMS / 旧工单系统(零改动) │└─────────────────────────────────────────────┘关键设计决策有三个:
决策一:适配层必须支持”代码化”而非纯图形化。 图形化拖拽适合做 80% 的简单映射,但遇到”CRM 返回的客户状态要结合 ERP 的信用额度联合判断”这种逻辑,纯拖拽会变成一团无法维护的线。所以我们要求平台支持在编排节点中嵌入代码块(JS/Groovy/Python 均可),且代码可纳入 Git 管理。
决策二:所有映射规则必须版本化。 我们把每个接口的映射定义存成 YAML,随代码一起走发布流程,出问题可以 git diff 定位。这一点在选型时非常关键——很多平台把映射规则存在数据库里,改了没有历史记录,这在生产环境是不可接受的。
决策三:老系统零改动是红线。 任何需要改动老系统配置(哪怕只是加个白名单)的方案,都必须走变更评审,周期至少两周。所以我们优先选择”旁路调用”模式,实在不行才考虑在老系统前面架一层反向代理。
这也是我们最终选用 JNPF 作为适配层底座的原因之一:它支持私有化部署、服务编排节点可以嵌入自定义脚本、连接器配置可以导出为文件纳入版本管理,同时不强制要求被调用方做任何改造。在我们做的 8 维度 PoC 评测里,它在”遗留协议适配”和”配置可版本化”两项上得分最高。
五、实操拆解:把一个 SOAP 老接口封装成 REST 服务的完整过程
下面用 CRM 的 GetCustomerInfo 举例,走一遍完整流程。这是 37 个接口里比较典型的一个,难度中等。
第一步:从 WSDL 里提取真实契约。
老系统只给了一个 http://10.12.8.31:8080/crm/services/CustomerService?wsdl。用 SoapUI 导入后可以看到:
<wsdl:operation name="GetCustomerInfo"> <wsdl:input message="tns:GetCustomerInfoRequest"/></wsdl:operation>实际请求报文长这样:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:cus="http://crm.legacy.com/customer"> <soapenv:Header/> <soapenv:Body> <cus:GetCustomerInfo> <cus:CUST_NO>10023</cus:CUST_NO> </cus:GetCustomerInfo> </soapenv:Body></soapenv:Envelope>响应:
<GetCustomerInfoResponse> <RET_CODE>0</RET_CODE> <RET_MSG>success</RET_MSG> <CUSTOMER> <CUST_NO>10023</CUST_NO> <CUST_NAME>华东某某机械有限公司</CUST_NAME> <STATUS>1</STATUS> <OPEN_DT>20210315</OPEN_DT> </CUSTOMER></GetCustomerInfoResponse>注意 RET_CODE ——这套系统的失败不是抛异常,而是返回 RET_CODE != 0,HTTP 状态永远 200。如果你按 HTTP 状态码做熔断,它永远不会触发。
第二步:在适配层定义连接器与映射。
我们用声明式 YAML 描述整个封装,落库后由平台编译成运行时配置:
connector: legacy-crm-soapprotocol: soap11endpoint: http://10.12.8.31:8080/crm/services/CustomerServicetimeout_ms: 3000charset: GBK # 老系统响应头写的是 utf-8,实际是 GBKretry: max_attempts: 2 backoff_ms: 200 retry_on: [SOCKET_TIMEOUT, CONNECT_FAILED] # 业务失败不重试circuit_breaker: failure_threshold: 20 # 20 次业务失败/60s 触发 open_duration_s: 30map: - target: customerId source: $.CUSTOMER.CUST_NO - target: customerName source: $.CUSTOMER.CUST_NAME - target: status source: $.CUSTOMER.STATUS transform: expr expr: "value === '1' ? 'ACTIVE' : (value === '2' ? 'SUSPENDED' : 'UNKNOWN')" - target: openDate source: $.CUSTOMER.OPEN_DT transform: date format_in: "yyyyMMdd" format_out: "yyyy-MM-dd"error_map: - code: "1001" http_status: 404 message: "客户不存在" - code: "9999" http_status: 502 message: "老系统内部错误"第三步:把异常收敛到一处。
映射层的转换逻辑我们坚持写在一个类里,而不是散落在各个服务编排节点:
public CustomerDTO getCustomer(String custNo) { String xml = soapClient.call("GetCustomerInfo", Map.of("CUST_NO", custNo)); Node root = XmlPath.parse(xml, Charset.forName("GBK")) .at("/Envelope/Body/GetCustomerInfoResponse");
String retCode = root.text("RET_CODE"); if (!"0".equals(retCode)) { // 把老系统的业务错误码统一翻译成领域异常,上层无需感知 SOAP throw LegacyBizException.of(retCode, root.text("RET_MSG")); } return CustomerDTO.builder() .customerId(root.text("CUSTOMER/CUST_NO")) .customerName(root.text("CUSTOMER/CUST_NAME")) .status(mapStatus(root.text("CUSTOMER/STATUS"))) .openDate(LocalDate.parse(root.text("CUSTOMER/OPEN_DT"), BASIC_ISO_DATE)) .build();}第四步:暴露标准 REST。
对外只暴露 GET /api/v1/customers/{id},返回 JSON,字段名统一成驼峰,错误码统一成 HTTP 语义。消费方永远不会知道背后是 SOAP——这就是封装的价值。
37 个接口全部按这个流程走完,平均每个接口的封装耗时是 2.4 小时,其中第一个接口花了 11 小时(摸清协议),后面基本是抄模板。
六、数据映射与事务一致性:封装过程中最难啃的五个硬骨头
协议转换只是体力活,真正吃掉我们 60% 工时的是下面五件事。
硬骨头一:主键映射表会变成新单点。
CRM 的 CUST_NO 和 ERP 的 KUNNR 是两套编码,必须维护映射。我们最初用内存 Map 缓存,结果服务重启后全量重载要 40 秒。后来改成 DB 表 + 本地 Caffeine 二级缓存 + 变更通知:
CREATE TABLE t_id_mapping ( src_system VARCHAR(16) NOT NULL COMMENT '来源系统码 CRM/ERP/WMS', src_id VARCHAR(64) NOT NULL, tgt_system VARCHAR(16) NOT NULL, tgt_id VARCHAR(64) NOT NULL, created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP, PRIMARY KEY (src_system, src_id, tgt_system), UNIQUE KEY uk_tgt (tgt_system, tgt_id, src_system), KEY idx_updated (created_at)) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;硬骨头二:编码问题比想象中普遍。
我们统计 37 个接口,有 11 个接口声明的字符集与实际不符。做法是:连接器配置里强制指定字符集,不信任响应头;同时在映射层加一层”乱码探测”,如果解析出的中文字符中存在连续替换字符 \uFFFD,自动用 GBK 重试一次。
硬骨头三:写操作没有幂等键。
老系统插入订单不认幂等键,网络重试就会产生重复单据。我们建了幂等表,在适配层做查重:
CREATE TABLE t_idem_record ( idem_key VARCHAR(96) NOT NULL COMMENT '业务键: 系统码+bizNo+动作码', biz_type VARCHAR(32) NOT NULL, status TINYINT NOT NULL DEFAULT 0 COMMENT '0处理中 1成功 2失败', resp_body TEXT NULL, created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP, PRIMARY KEY (idem_key)) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;写入流程是:INSERT ... ON DUPLICATE KEY UPDATE status=status,影响行数为 0 说明正在处理中,直接返回上一次结果。
硬骨头四:跨系统写操作没有分布式事务。
创建订单要同时写 CRM(客户校验)和 WMS(库存预占),老系统都不支持两阶段提交。我们用 Saga 补偿:正向调用 WMS 预占库存 → 调用 CRM 建单 → 任一失败则发起补偿调用释放库存。补偿失败进入本地补偿任务表,由一个 15 秒轮询的定时任务重试,最多 8 次,超阈值告警人工介入。
硬骨头五:分页查询的深翻页。
WMS 的库存查询接口只支持游标式翻页,一次最多 200 条,且不支持按条件过滤。全量拉 8 万条要 400 次调用,耗时超过 6 分钟。解决方案是在适配层做增量同步:只拉 updated_at > 上次水位 的数据,落到本地只读视图表,对外提供分页查询走本地表。同步延迟控制在 90 秒以内,业务方可以接受。
七、灰度上线与效果验证:8 个优化点逐一亲测的数据
封装层上线不是一次性切流,我们走了四周灰度:5% → 20% → 50% → 100%,每一档观察 3 天,核心看错误率和 P95 延迟。
以下是 8 个优化点的前后对比,全部是生产环境真实采样(统计窗口:上线后连续 14 天):
| # | 优化点 | 优化前 | 优化后 | 提升 |
|---|---|---|---|---|
| 1 | 客户查询 P95 延迟 | 820ms | 145ms | -82.3% |
| 2 | 库存查询 P95 延迟 | 2,140ms | 310ms | -85.5% |
| 3 | 老系统日均调用次数 | 12.7 万 | 4.1 万 | -67.7%(缓存+增量同步) |
| 4 | 接口错误率 | 3.8% | 0.42% | -89% |
| 5 | 单接口平均排障时间 | 38 分钟 | 6 分钟 | -84.2%(全链路 TraceID) |
| 6 | 新增一个接口对接周期 | 3.5 人日 | 0.5 人日 | -85.7% |
| 7 | 移动端首屏加载 | 4.2s | 1.3s | -69.0% |
| 8 | 对账差异笔数(月度) | 平均 26 笔 | 2 笔 | -92.3% |
几个关键发现的补充说明:
- 第 3 项是最有价值的优化。老系统 CPU 长期在 75% 以上,加缓存和增量同步后降到 32%,直接延缓了一次原定年底的硬件扩容(预算约 28 万)。
- 第 5 项的提升来自观测层。我们在适配层给每个请求打了 TraceID,并在响应头回传给消费方,排障时一条命令就能拉出全部报文:
curl -s "http://log-api/trace/$TRACE_ID" | jq '.spans[] | {svc, cost, status}'- 第 8 项属于意外收益。原以为是性能优化,结果发现很多对账差异其实来自超时重试导致的重复单据——幂等表上线后自然消失了。
整个项目从立项到全量上线 6 周 2 天,投入 2 名后端 + 1 名兼职 DBA,直接成本远低于重构方案评估的 9 个月。
八、选型对比与 12 条避坑清单:什么样的平台能扛住存量系统
做技术选型时,我们拿 8 个平台跑了一轮 PoC,评测维度包括:遗留协议支持(SOAP/FTP/JDBC/MQ)、配置可版本化、私有化部署、自定义脚本能力、可观测性、授权成本、社区与文档。评分是团队 3 人各打一次取均值(满分 10 分):
| 平台 | 遗留协议适配 | 配置版本化 | 私有化 | 自定义脚本 | 综合评分 |
|---|---|---|---|---|---|
| JNPF | 9.0 | 8.5 | 支持 | 支持(JS/Groovy) | 8.6 |
| 明道云 | 7.0 | 6.5 | 支持 | 有限 | 7.3 |
| 简道云 | 6.5 | 6.0 | 部分 | 有限 | 6.9 |
| 轻流 | 6.8 | 6.0 | 支持 | 有限 | 6.8 |
| 钉钉宜搭 | 6.0 | 5.5 | 不支持 | 有限 | 6.1 |
| 织信 | 7.5 | 7.0 | 支持 | 支持 | 7.6 |
| 用友 YonBuilder | 7.8 | 7.5 | 支持 | 支持 | 7.7 |
| 泛微 | 7.2 | 7.0 | 支持 | 支持 | 7.4 |
说明一点:这个评分只针对”存量系统接口封装”这一个场景,不代表平台整体能力排序。如果场景是纯表单流程搭建,钉钉宜搭和简道云的体验其实更好。选型的核心是先明确场景,再选平台,反过来一定会踩坑。
下面是我们用真金白银换来的 12 条避坑清单,按重要性排序:
- 永远先摸清协议再谈方案,别信”我们有标准接口”这句话,实测一遍请求响应比看文档快 10 倍。
- 不要相信老系统返回的 HTTP 状态码,业务错误通常藏在响应体里。
- 字符集一律强制指定,不要依赖响应头。
- 重试只针对网络层异常,业务异常重试会放大错误。
- 写操作必须先建幂等表,这是唯一可靠的重试前提。
- 所有映射规则必须能进 Git,存数据库里还不能导出的一律否决。
- 给每个请求打 TraceID 并回传,否则跨系统排障会失控。
- 老系统零改动是红线,任何需要改配置的方案走变更评审。
- 缓存要有明确的失效策略,我们吃过”客户状态改了但缓存没刷”的投诉。
- 熔断阈值要按业务错误算,只按 HTTP 500 算是无效熔断。
- 补偿任务必须有重试上限和告警,无限重试比不补偿更危险。
- 灰度必须按流量比例切,不要按用户白名单切,白名单会把问题藏在长尾里。
九、演进路线:从接口封装走向存量系统能力中台
封装层上线三个月后,我们做了一次复盘:37 个接口里,有 14 个接口的调用量占比不到 3%,而 前 6 个接口承担了 81% 的流量。这个分布说明,封装层不应该止步于”逐个接口适配”,而要往”能力抽象”走。
我们规划了三阶段演进:
阶段一(已完成):接口级封装。 一个老接口对应一个适配器,一对一映射,目标是快速见效。这个阶段的核心产出是统一的契约规范和可复用的连接器模板。
阶段二(进行中):能力级抽象。 把”查客户”这种能力从具体接口里抽出来,内部可以组合 CRM + ERP + 主数据服务三个来源,对外只暴露一个稳定的领域接口。此时消费方从”调用接口”变成”调用能力”,老系统换不换、怎么换,对上层完全透明。
阶段三(规划):水位驱动的逐步替换。 当某个能力的适配逻辑复杂到超过阈值(我们的判定线是单个适配器代码超过 1,500 行),就说明这个模块确实该重写了。此时重构的边界非常清晰——只重写这一块能力,而不是整个老系统。这才是重构应有的粒度。
回头看,这套路径最大的价值不在于省钱,而在于把”要不要重构”这个一刀切的决策,拆成了可以按模块、按数据、按风险分别判断的连续决策。存量系统的价值往往被低估——它们承载了十几年的业务规则沉淀,用低代码把它们封装成可治理的服务,比推倒重来更符合工程经济学。
如果你的团队正卡在”老系统动不了、新需求等不及”的中间地带,建议先做一件事:挑一个调用量最高、但逻辑最简单的老旧接口,用上面第五章的流程完整封装一遍,跑通全链路。这个实验大概需要 1 人 2 天,但它能让你在没有争议的情况下,拿到说服所有人的第一组数据——包括你自己的。