# 客户 API 不是 REST？先要契约文件，别急着啃文档

> SOAP、gRPC 和 GraphQL 都有严格的契约文件，拿到它，一天内就能跑通第一次调用。

原文: https://fdetimes.net/zh/guides/call-soap-grpc-graphql-first-day/

上午 9 点，你第一天到客户现场，申请订单系统的 API 权限。你可能听到“我们用的是 SOAP”“有个内部 gRPC 服务”，或者“直接调 /graphql 就行”。

REST 是一种架构风格，请求是无状态的：每个请求都带齐服务器理解和处理它所需的全部信息。如果你只熟悉 REST，这三种协议听起来都像要读三周文档。

实际上用不了那么久。三种协议都建立在结构严格的契约之上，这份契约就是捷径。只要要对文件、做最简单的调用，当天就能跑通一次成功的调用。

对前线部署工程师（FDE）来说，这项能力值得在去现场之前就练好。越早能调用客户系统，就越早拿到真实数据开工，而不是干等。

## 一天结束时，你手里应该有什么？

目标是为每个系统写一页“集成卡片”：记录协议、契约文件、一个能跑通的示例调用、你选定的超时，以及错误长什么样。同时，代码库里要有一个小函数，供团队其他人调用。

前期准备不多：能访问客户测试环境的网络、凭证，以及一门你写得快的语言。gRPC 允许客户端和服务端用不同语言编写，只要 gRPC 支持这些语言即可。无论客户服务端用什么语言，你都不必换技术栈。

下表汇总了每种协议的做法。最后一列是三种协议通用的实用建议：先故意发一次错误调用，亲眼看到错误响应，再动手写处理代码。

| 协议 | 要哪份契约 | 第一次调用做什么 | 测试错误时看什么 |
|---|---|---|---|
| SOAP | WSDL 文件 | 一个参数少的只读操作 | body 中的 Fault 元素 |
| gRPC | .proto 文件 | 一个一元 RPC | 故意发一次错误调用，记下客户端返回的错误 |
| GraphQL | Schema（类型系统） | 只查两三个字段的 query | 发一个错误的 query，记下响应 |

## 第 1 步：别问“API 在哪”，要问“契约在哪”

第一个问题决定了一整天的走向。对 SOAP 而言，据 SmartBear 介绍，服务必须有一个 WSDL 文件，定义所有操作及其输入输出。对 gRPC 而言，Protocol Buffers 既是序列化格式，也是接口定义语言（IDL），所以 .proto 文件就是契约。

GraphQL 稍有不同：API 围绕类型和字段组织，而不是围绕端点。每个 GraphQL 服务都定义了一套类型系统，工具可以借此在执行前检查 query 的语法。你要的是 schema，外加端点地址。

继续之前先确认：契约文件已经到手，并且能从中找到至少一个只读操作。如果客户发来的是 PDF 指南而不是 WSDL 或 .proto 文件，就再要一次。PDF 会过时，契约文件才是线上系统真正在用的东西。

## 第 2 步：SOAP，先看信封，再看信

SOAP 是一种标准化、结构严格的协议，消息用 XML 编写。根据 W3C 的 SOAP 1.2 Primer，每条消息都装在一个信封（envelope）里，body 是信封的必需部分，错误通过 Fault 元素报告。骨架如下（简化示意，命名空间和操作名以客户的 WSDL 为准）：

```xml
<env:Envelope xmlns:env="（客户 SOAP 版本对应的命名空间）">
  <env:Body>
    <GetOrder>
      <OrderId>A-1024</OrderId>
    </GetOrder>
  </env:Body>
</env:Envelope>
```

命名空间处的占位符写的是“客户 SOAP 版本对应的命名空间”。在 WSDL 中挑一个参数最少的只读操作，传入测试环境里真实存在的订单 ID，这样能拿回真实数据。

检查：响应带有信封，body 里有数据。然后故意传一个错误 ID，看看 Fault 长什么样，把这个样例贴进集成卡片。之后写错误处理代码时，要用的正是这个结构。

## 第 3 步：gRPC，先做一元调用，流式留到以后

根据 gRPC 文档，客户端可以像调用本地函数一样，直接调用另一台机器上服务端的方法。gRPC 有四类方法，最简单的是一元（unary）调用：客户端发一个请求，拿回一个响应。第一次就调它。

打开 .proto 文件，找一行请求和响应都不带 `stream` 关键字的 `rpc`。下面是一个假设的示例，帮你辨认：

```proto
// 简化示意；服务名和消息名均为假设
service OrderService {
  rpc GetOrder (GetOrderRequest) returns (Order);              // 一元调用：先调这个
  rpc WatchOrders (stream Filter) returns (stream OrderEvent);  // 留到以后
}
```

（注释的意思是：这是简化示意，服务名和消息名均为假设；先调一元方法；流式方法留到以后。）双向流是难点：双方通过一个读写流各自发送一系列消息。第一天用不到它。

用 .proto 文件为你的语言生成客户端代码，然后打开一个 channel。在 gRPC 里，channel 指与特定主机和端口上服务端的连接。每次调用附带的信息，比如认证头，放在 metadata 里。

检查：一元调用返回一个 `Order` 类型的对象。如果调用被拒绝，先查认证 metadata，再怀疑自己的代码。

## 第 4 步：GraphQL，只要你需要的

GraphQL 既是 API 查询语言，也是服务端运行时。由于 API 围绕类型和字段构建，响应的结构由你在 query 里决定。第一个 query 要写得小（下面的字段名是假设的，请用 schema 里的真实字段名）：

```graphql
query {
  order(id: "A-1024") {
    id
    status
  }
}
```

探索客户的 schema 时，最大的好处是执行前校验。类型系统能让工具在请求到达服务端之前就标出写错的 query。让工具指出错误，比从头到尾读 schema 学得快得多。

检查：响应恰好包含你请求的两个字段，不多不少。之后按用例需要，一次加一个字段。

## 第 5 步：加上超时，再说完成

在笔记本上能跑通的调用，还不算集成。客户的服务可能响应很慢，甚至挂住，你的代码不该无限等待。gRPC 允许客户端设置 deadline，即愿意等待一次 RPC 完成的最长时间。对 SOAP 和 GraphQL，在所用的 HTTP 客户端上设置等效的超时。

写一个像 `get_order(order_id)` 这样的函数，把底层协议藏起来：接收简单参数，返回你自己的对象，并抛出统一类型的错误，不管起因是 SOAP Fault 还是 gRPC 客户端返回的错误。

下面是一个简化的 Python 骨架。函数 `_call_client_system`（“调用客户系统”）就是放入第 2、3 或 4 步中真实 SOAP、gRPC 或 GraphQL 调用的地方。5 秒只是示例值：

```python
# 简化示意：把 _call_client_system 换成你的真实调用
class IntegrationError(Exception):
    pass

def get_order(order_id: str, timeout_s: float = 5.0) -> dict:
    try:
        raw = _call_client_system(order_id, timeout=timeout_s)
    except Exception as e:  # SOAP Fault、gRPC 错误、HTTP 错误、超时……
        raise IntegrationError(f"get_order({order_id}) 调用失败：{e}") from e
    return {"id": raw["id"], "status": raw["status"]}
```

（注释的意思是：把 `_call_client_system` 换成你的真实调用；这里的异常涵盖 SOAP Fault、gRPC 错误、HTTP 错误和超时。错误信息为“get_order(...) 调用失败”。）

检查：用有效 ID 和错误 ID 各调用一次 `get_order`。第一次应返回一个干净的两字段 dict；第二次应抛出 `IntegrationError`，附带可读的错误信息，而不是一整页的 XML 堆栈。团队不需要知道底层是 XML 还是 Protocol Buffers。

**要点:** 别通读文档：拿到契约，做最简单的调用，然后封装。

## 把一天拖成一周的三个错误

最常见的错误是从最难的部分入手。客户提到“实时事件流”，你就一头扎进双向流，其实一个一元 RPC 就足以验证连通性，并拉到演示用的数据。

第二个错误是忽略错误。很多工程师只测成功路径，到了演示当天，撞上一个没见过的 SOAP Fault，代码处理不了。第一天故意发一个错误请求只要五分钟，却可能保住整场演示。

第三个错误是调用不设时限。没有 deadline 或超时，一个服务挂住，整条数据管道跟着挂住，你会浪费一下午在错误的地方找 bug。

## 这项技能怎么写进简历？

当 FDE 岗位描述提到“对接遗留系统”或“客户内部 API”时，别只在技能栏里写“SOAP、gRPC、GraphQL”。

改写成一句讲结果的话，比如“通过 WSDL 对接 SOAP 服务，并封装成带超时和 Fault 处理的客户端”。或者附上一个小仓库链接：里面有三种协议的客户端，调用的是你自己搭的服务端。

在客户现场，真正赢得信任的，不是能背出 SOAP 1.2 规范的人，而是第一天午饭前就在共享频道里发出一句话的人：“GetOrder 跑通了，这是样例数据。”

**本周动手试试:**

- 写一个模拟的 .proto 文件，只含一个一元 RPC，用一种语言实现服务端，再用另一种语言写客户端调用它
- 找一个公开的 GraphQL API，读它的 schema，写一个只取两个字段的 query
- 起草一页“集成卡片”模板：协议、契约、示例调用、超时、错误样例

## 信源

- [Introduction to gRPC](https://grpc.io/docs/what-is-grpc/introduction/)

- [Core concepts, architecture and lifecycle | gRPC](https://grpc.io/docs/what-is-grpc/core-concepts/)

- [GraphQL | The API language for humans and agents](https://graphql.org/)

- [SOAP vs. REST: What API Testers and Developers Need to Know | SmartBear Learn](https://smartbear.com/learn/api-design/soap-vs-rest-apis/)

- [SOAP Version 1.2 Part 0: Primer (Second Edition)](https://www.w3.org/TR/soap12-part0/)

- [What is REST?: REST API Tutorial](https://restfulapi.net/)
