将遗留的SOAP服务接入现代API网关，核心矛盾在于协议模型差异。SOAP基于XML信封和WSDL契约，强调严格的结构与操作描述；而主流网关多以REST风格或纯HTTP路由为设计起点。要让外部调用方以更简单的方式使用旧接口，就必须在网关或相邻层完成协议转换、报文校验以及异常处理。
为什么SOAP直接暴露给网关会有问题
多数API网关对REST和JSON的支持是开箱即用的，内置了参数校验、限流、鉴权等能力。但SOAP请求必须包含Envelope、Header、Body等XML节点，且服务端通常根据WSDL文件来约束方法名与字段类型。如果网关只是做透传，调用方就需要自己拼装复杂XML，失去了网关简化入口的意义。
另一个隐藏问题是错误模型不同。SOAP通过fault节点返回错误，HTTP状态码可能仍是200；而网关的熔断、监控往往依赖HTTP状态或特定响应体。若不转换，运维平台很难准确感知后端异常，导致告警失真。
方案一：网关内置协议转换插件
部分网关提供SOAP到REST的转换模块，思路是预先上传WSDL，网关自动生成外部RESTful路径，并将JSON参数映射为SOAP请求体。下面以伪配置展示转换规则：
<gateway-route>
<path>/api/order</path>
<soap-backend>http://192.168.0.1:8080/ws/order</soap-backend>
<wsdl>file://order.wsdl</wsdl>
<map>
<json-field>orderId</json-field>
<soap-param>OrderID</soap-param>
</map>
</gateway-route>
这种方式的优点是改动小，旧系统无需重写。但缺点也很明显：WSDL变更时要同步更新网关配置，且复杂嵌套结构容易映射出错。对于接口稳定、调用量中等的内部系统较为合适。
在实际落地时，建议先对WSDL做裁剪，只暴露必要操作，减少网关解析负担。同时开启网关的XML校验，防止畸形信封穿透到后端造成解析阻塞。
方案二：前置轻量代理做协议适配
当网关不支持SOAP插件，或后端服务过多、契约混乱时，可以写一个独立的适配服务。它接收网关转发的JSON，拼装SOAP报文，调用旧服务，再把结果转回JSON。示例代码如下：
import requests
def call_soap(order_id):
envelope = '''<?xml version="1.0"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<GetOrder><OrderID>{oid}</OrderID></GetOrder>
</soap:Body>
</soap:Envelope>'''
resp = requests.post('http://192.168.0.1:8080/ws/order',
data=envelope.format(oid=order_id),
headers={'Content-Type': 'text/xml'})
return parse_xml(resp.text)
def parse_xml(text):
# 简化示例：真实场景用lxml提取Body内容
return {'raw': text}
该方案把协议细节隔离在代理里，网关只做路由和限流，稳定性更高。代价是多了一次网络跳转和开发量，需要专门维护适配层。
代理层还应统一处理超时与重试。SOAP后端常基于旧容器，响应慢，应在代理设短超时，并返回标准错误码给网关，避免线程堆积。
鉴权与监控的衔接
网关一般用JWT或API Key鉴权，而SOAP旧系统可能用IP白名单或WS-Security。集成时可由网关验证外部身份，代理层再附加后端所需凭证，做到前后端鉴权解耦。
监控方面，网关记录REST入口指标，代理层记录SOAP调用成功率与耗时。两者通过traceId串联，就能在统一面板看到从外部请求到旧服务的全链路状态，方便定位瓶颈。
选型建议
| 维度 | 网关插件 | 前置代理 |
|---|---|---|
| 改造成本 | 低 | 中 |
| 灵活性 | 弱 | 强 |
| 运维复杂度 | 依赖网关版本 | 多一个服务 |
如果团队网关能力新且接口少，优先用插件；若旧系统繁杂、契约多变，轻量代理更可控。无论哪种，都应在测试环境用真实WSDL跑通异常分支，再上线。
SOAPAPI_gatewayprotocol_transform修改时间：2026-08-07 18:03:25