3. 服务契约与接口设计：WSDL与RESTful API设计规范、版本管理策略、契约优先开发方法
服务契约，说白了就是服务提供者和消费者之间的「一纸合同」。
我见过太多项目，接口文档和实际代码完全对不上。服务端改了字段名，客户端还在用旧的。结果一上线，全线崩溃。
所以这一章，咱们就聊聊怎么把这「合同」写好、管好、落地好。
3.1 契约优先 vs 代码优先
先有契约，还是先有代码？
我个人习惯，永远选契约优先。为什么？
- 代码优先：先写接口实现，再生成文档。容易导致文档滞后、不一致。
- 契约优先：先定义接口规范，再分别生成服务端和客户端代码。双方并行开发，互不阻塞。
核心原则：契约是权威，代码是契约的实现。谁都不能私自改契约。
我在项目中遇到过，团队用代码优先方式开发，结果服务端改了接口参数名，客户端完全不知情。联调时花了三天排查，最后发现是字段名大小写不一致。嗯，从那以后，我强制团队必须契约优先。
3.2 WSDL 设计规范（SOAP 服务）
WSDL 是 SOAP 服务的契约语言。虽然现在 REST 更流行，但很多金融、电信核心系统还在用 SOAP。
一个规范的 WSDL 文件，应该包含以下核心元素：
| 元素 | 作用 | 注意事项 |
|---|---|---|
types |
定义数据类型（通常用 XSD） | 尽量复用已有 schema，不要重复造轮子 |
message |
定义请求/响应消息结构 | 每个操作对应一个 request 和一个 response |
portType |
定义操作集合（接口） | 操作名要体现业务语义，比如 submitOrder 而不是 doAction |
binding |
绑定协议和传输方式 | 常用 SOAP/HTTP，注意编码风格（document/literal 优先） |
service |
定义服务端点地址 | 地址不要硬编码，用配置或注册中心 |
我的经验：WSDL 文件最好用工具生成，比如 Eclipse 的 WSDL 编辑器或 IntelliJ 的插件。手写 WSDL 容易出错，尤其是命名空间和类型引用。
3.3 RESTful API 设计规范
REST 比 SOAP 轻量，但设计起来反而更容易「放飞自我」。我见过太多 REST API，说是 REST，其实就是 RPC 披了个 HTTP 的外衣。
好的 REST API 设计，应该遵循以下原则：
- 资源导向：URL 表示资源，而不是操作。比如
/orders而不是/getOrders。 - HTTP 动词语义化：GET 查、POST 增、PUT 全量更新、PATCH 部分更新、DELETE 删。
- 状态码准确：200 成功、201 创建成功、400 参数错误、404 资源不存在、500 服务端错误。
- 版本管理：URL 路径或请求头带版本号。
- 统一响应格式：所有接口返回结构一致，方便客户端统一处理。
推荐响应格式：
{
"code": 0,
"message": "success",
"data": { ... }
}错误时：
{
"code": 40001,
"message": "参数校验失败",
"data": null
}你想想看，如果每个接口返回格式都不一样，客户端得写多少适配代码？
3.4 版本管理策略
服务一旦上线，就可能有多个消费者。你改了接口，老客户端怎么办？
版本管理，就是解决这个问题的。
| 策略 | 实现方式 | 适用场景 | 缺点 |
|---|---|---|---|
| URL 路径版本 | /v1/orders、/v2/orders |
简单直接，容易理解 | URL 冗余，版本多了难维护 |
| 请求头版本 | Accept: application/vnd.myapp.v1+json |
URL 干净，适合 RESTful 风格 | 调试不方便，需要额外解析 |
| 查询参数版本 | /orders?version=1 |
临时过渡方案 | 容易被忽略，缓存不友好 |
| 语义化版本 | 主版本.次版本.修订号（如 2.1.0） | 精细控制，适合 SDK 类服务 | 管理成本高 |
避坑指南：我曾经在一个项目中，团队用查询参数做版本管理。结果前端开发忘了传 version 参数，默认走了最新版本，导致老页面全部报错。后来我们统一改成了 URL 路径版本，再也没出过类似问题。
3.5 契约优先开发流程
说了这么多理论，咱们看看实际怎么落地。
我习惯的流程是这样的：
- 业务分析：梳理服务边界，确定接口粒度。
- 契约定义：用 OpenAPI（REST）或 WSDL（SOAP）编写接口规范。
- 契约评审：服务端、客户端、测试一起评审，确认无误后签入代码库。
- 代码生成：用工具（如 Swagger Codegen、wsimport）生成服务端骨架和客户端桩代码。
- 并行开发：服务端实现业务逻辑，客户端基于桩代码开发。
- 契约测试：用契约测试框架（如 Pact）验证双方是否遵守契约。
- 持续集成：契约变更时，自动触发测试，防止破坏性变更。
工具推荐：
- REST：Swagger/OpenAPI + Swagger Codegen
- SOAP：WSDL + Apache CXF 或 Spring WS
- 契约测试：Pact（支持多种语言）
3.6 知识结构图
下面这张图，把服务契约设计的核心脉络串起来了：
3.7 总结
服务契约设计，是 SOA 落地的第一道关卡。契约没定好，后面全是坑。
我个人建议，不管团队大小，都坚持契约优先。哪怕前期多花点时间讨论，也比后期联调时发现问题再返工强得多。
嗯，这一章的内容就到这里。记住：好的契约，是服务稳定运行的基石。