soap 是一套基于 xml 的消息协议规范，核心用 soap envelope 包裹请求/响应、强制 wsdl 描述接口；现少手写因其客户端冗长、调试难、http 语义弱化（如 get 也需 post）、xml 膨胀 2–3 倍且易出 400 错误或 jdk 11+ 缺 jax-ws 等问题。
SOAP 是什么，为什么现在很少直接手写
SOAP 不是某种语言或框架，而是一套基于 XML 的消息协议规范，核心是用 SOAP Envelope 包裹请求/响应，强制要求 WSDL 描述接口，依赖 HTTP（或其他传输层）但不绑定它。现在少有人手写，因为生成的客户端代码冗长、调试困难、HTTP 语义被弱化——比如一个 GET 请求在 SOAP 里也得走 POST + SOAPAction 头，徒增理解成本。
常见错误现象：400 Bad Request 但响应体是空的；java.lang.NoClassDefFoundError: javax.xml.ws.Service（JDK 11+ 默认移除了 JAX-WS）；WSDL 导入后生成的类里一堆 getXXXResponse 嵌套，改字段要同步动三处。
- 使用场景：银行、医保、政务等强契约、需 WS-Security / WS-ReliableMessaging 的老系统对接
- 参数差异：所有参数必须包装进
Body的命名空间元素里，不能像 REST 那样用 URL 路径或查询参数传简单值 - 性能影响：每次请求都要解析整块 XML，比 JSON 膨胀 2–3 倍，移动端或高并发下明显拖慢
REST 是什么，别把“用 HTTP 动词”当成全部
REST 是一种架构风格，不是协议。它的关键不是“用了 GET 和 POST”，而是是否遵守统一接口、无状态、可缓存、分层系统等约束。现实中大多数所谓“RESTful API”只是 HTTP-based API——用 /users/123 而不是 /getUser?id=123，返回 JSON，这就够日常用了。
容易踩的坑：DELETE /api/v1/users 却删了全部用户（没带 ID）；PUT /users 本该全量更新却设计成局部更新；用 200 OK 返回创建成功的资源，却不带 Location 头，违反 REST 的自描述性。
- 使用场景：前后端分离、微服务间通信、第三方开放平台（如 GitHub API、Stripe）
- 参数差异：支持路径参数（
/users/{id}）、查询参数（?sort=name&limit=10）、请求体（JSON/XML）、Header（Authorization）多种方式混合 - 兼容性影响：不依赖固定 schema，前端可只取响应里需要的字段，后端加字段不破坏旧客户端
XML vs JSON：不只是格式，是设计哲学差异
SOAP 强制 XML，是因为它需要 Schema（XSD）做严格校验、支持复杂类型嵌套、命名空间隔离——比如两个供应商都定义了 Address，但通过 ns1:Address 和 ns2:Address 就能共存。JSON 没命名空间，靠字段名和文档约定，轻快但松散。
本文档主要讲述的是基于REST架构的Web Service设计；REST（Representational State Transfer）是一种轻量级的Web Service架构风格，其实现和操作明显比SOAP和XML-RPC更为简洁，可以完全通过HTTP协议实现，还可以利用缓存Cache来提高响应速 度，性能、效率和易用性上都优于SOAP协议。希望本文档会给有需要的朋友带来帮助；感兴趣的朋友可以过来看看
典型错误：Content-Type: application/json 却发了 XML；用 xml2js 解析 REST 接口返回的 JSON，报 Invalid character；在 SOAP 客户端里手动拼接 XML 字符串，导致特殊字符（&、）未转义而解析失败。
- 性能影响：XML 解析器普遍比 JSON 解析器重，Node.js 的
fast-xml-parser仍比JSON.parse慢 3–5 倍 - 工具链差异：XML 有 XSLT、XPath、XQuery；JSON 有 jq、JSONPath，但生态简单得多
- 调试成本：XML 错一位标签闭合，整个请求就废；JSON 少个逗号或引号，现代浏览器控制台能准确定位
什么时候该选 SOAP，什么时候该绕开
别被“企业级”“标准”这类词带偏。SOAP 只在三个条件同时满足时才值得用：对方系统只提供 WSDL、业务要求 WS-Security（比如签名+加密+时间戳）、你团队有现成且维护良好的 SOAP 工具链（如 Apache CXF + wsdl2java）。其余情况，优先用 REST + JSON。
真实项目里更常见的选择是“混用”：新模块用 REST，老模块用 SOAP 客户端封装一层代理，对外暴露统一 JSON 接口。这时候要注意：SOAP 响应里的时间字段（xs:dateTime）可能带时区，JSON 里得转成 ISO 8601 标准格式；SOAP 的空值常表示为 xsi:nil="true"，JSON 里就是 null，映射时别漏判。
- 兼容性陷阱：.NET 的
DateTimeOffset序列化成 XML 是2023-01-01T12:00:00+08:00，Java 的LocalDateTime解析会失败，得用OffsetDateTime - 测试难点：SOAP 接口没法直接用 curl 测，得先生成请求 XML，再补全
SOAP-ENV:Envelope和命名空间头，手工太容易出错 - 部署注意：某些云网关（如 AWS API Gateway）不原生支持 SOAP，需用 Lambda 做 XML/JSON 转换桥接
真正难的不是选协议，是搞清对方 WSDL 里哪个 complexType 实际对应业务上的“订单”，以及那个 string 类型字段到底允不允许为空——这些细节，文档里往往不会写清楚。
