# API 里的每个字段，都是对客户 ERP 的承诺

> 先定谁能调用，再按调用方选 REST 或 GraphQL，先写契约后写代码，因为端点比模型活得更久。

原文: https://fdetimes.net/zh/guides/contract-first-api-design-handover/

项目进入第三周，货运风险模型已经跑起来，演示也很顺利。这时客户的 ERP 负责人提了三个问题：他们的系统调用哪里？返回什么数据？你们那边有变更时，怎么通知他们？

这三个问题决定了你离开之后方案的命运。模型可以换成别的。ERP 团队已经写好代码去调用的端点，却很难再改。

你的任务，是把这层 API 设计好，让客户团队能自己完成集成、运维和升级，不必再回头找你。

## API 是契约，不是技术细节

IBM 把 API 定义为一种契约，让一个软件能够访问另一个软件提供的数据或调用其功能。对前线部署工程师（FDE）来说，“契约”二字要按字面理解。响应里的每个字段都是一项承诺，对面的团队会在上面搭建业务逻辑。

所以首先要定的是谁有权调用这个 API，REST 还是 GraphQL 是之后的事。IBM 按访问级别给 API 分类：公开 API 完全对互联网开放，合作伙伴 API 和私有 API 则限制使用者范围。

一个只服务内部 ERP 和几家物流合作伙伴的风险评分方案，几乎肯定不需要公开。一开始就定对，后面能省下和安全团队的不少会议。

## REST 还是 GraphQL：看调用方

据 IBM 介绍，REST 是当今最流行的 Web API 架构；SOAP 则是基于 XML 的消息协议，对消息结构和传输有严格标准。如果客户的 ERP 只支持 SOAP，那就用 SOAP。对新设计来说，现实的选择通常是 REST 或 GraphQL。

GraphQL 官方文档的描述是：基于强类型系统，构建灵活、无需版本的 API。schema 定义数据的形状，客户端只请求自己需要的字段。

有一个细节容易忽略：GraphQL 规范有意不定义网络传输、授权和分页，这三样都得由你的团队自己设计。

如果 ERP 集成团队只需要几个固定操作，交接时 REST 通常风险更低。如果主要使用方是多个前端，各自需要不同的数据切片，GraphQL 更合适。

## 实例：货运风险 API

以开头的物流客户为例（假设案例）。团队的初稿通常是这样的：一个端点 `POST /getRiskScore`，返回 `{"shp_id": 8812, "rsk_v2": 0.83, "flg_manual": 1}`。能用，但有三个错误，交接后会惹麻烦。

第一，URI 里用了动词。Microsoft 的指南建议用名词（资源）而不是动词（对资源的操作）来命名 URI。

第二，`rsk_v2` 和 `flg_manual` 直接来自表的列名。Microsoft 建议不要把 API 设计成数据库内部结构的镜像。哪天你改了列名，所有客户端都会跟着出错。

第三个最难发现。ERP 发送货运数据，遇到超时后自动重试。如果写操作端点用的是 POST，每次重试都可能多生成一条记录。

Microsoft 指出，PUT 必须是幂等的：同一个请求发送多次，仍然只修改同一个资源，且值相同。POST 和 PATCH 没有这种保证。

修订版在写任何代码之前先写成契约。Microsoft 称之为契约优先（contract-first）：先设计契约，也就是接口，再写实现它的代码。契约的第一部分声明写操作：

```yaml
openapi: 3.0.3
info:
  title: Shipment Risk API
  version: 1.0.0
paths:
  /v1/shipments/{shipmentId}:
    put:
      summary: 创建或更新一条货运记录（幂等，可安全重试）
```

接下来在同一个 `paths` 部分下，描述读操作以及 ERP 将收到的响应结构：

```yaml
  /v1/shipments/{shipmentId}/risk-assessment:
    get:
      summary: 获取最新的风险评估
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                required: [shipmentId, riskLevel, score]
                properties:
                  shipmentId: { type: string }
                  riskLevel: { type: string, enum: [low, medium, high] }
                  score: { type: number, minimum: 0, maximum: 1 }
                  reasons: { type: array, items: { type: string } }
```

看看变了什么。资源现在是 `shipments` 和 `risk-assessment`，ERP 那边的人一看就懂。写操作用 PUT，以 ERP 提供的 `shipmentId` 为键，无论重试多少次，都只有一条货运记录。

在内部，映射层把 `rsk_v2` 转成 `score`，这样你可以修改数据库表结构，契约保持不变。

**要点:** OpenAPI 文件就是交接文档。在写第一行代码之前与集成团队一起评审，因为代码写完再改，代价要高得多。

## 什么时候需要版本？

六个月后，客户想加一个新字段 `estimatedDelayHours`。新增字段通常不会破坏客户端，旧代码会直接忽略不认识的字段。把 `riskLevel` 从字符串改成数字，或者删掉 `reasons`，才是破坏性变更。

针对破坏性变更，Microsoft 列出四种策略：把版本放在 URI、查询字符串、请求头或媒体类型里。Microsoft 认为 `/v1/` 这样的 URI 版本是简单的方案，但也提醒，随着 API 经历多轮变更、服务端要同时维护多个版本，它会变得难以管理。

GraphQL 走的是另一条路：类型系统随时间演进，不设版本。实践中，就是添加新字段、保留旧字段，等确认没有客户端还在使用旧字段时再删除。

无论选哪种，都把规则写进交接文档，让客户团队知道字段何时会被删除，以及会如何提前得到通知。

## 下一个项目可以照做的流程

先列出客户在对话中使用的业务名词，比如货运、订单、评估，它们就是候选资源。然后针对每个写操作，问集成团队：你们的客户端超时后会不会重试？

如果会，就把这个操作设计成以客户端提供的 ID 为键的 PUT。必须保留 POST 时，常见做法是要求客户端在请求头里带一个幂等键，服务端据此识别重复请求，返回先前的结果，而不是新建记录。

接着编写 OpenAPI 契约或 GraphQL schema，与真正调用 API 的人一起评审。如果选了 GraphQL，把授权和分页也拿到评审会上，因为规范不会替你处理。双方达成一致后，再写映射层和处理代码。

最常见的错误都来自为了赶进度走的捷径：在响应里直接返回 ORM 实体；所有写操作都用 POST；改了字段类型却不升版本；合作伙伴访问就够了，却把 API 做成公开；以为 GraphQL 自带授权而选了它。

每一条都能在写代码时省一个下午，却让客户在交接后付出几周的代价。

## 求职时如何展示这项能力

阅读 FDE 岗位描述时，留意“integration”“API design”或“customer-facing technical delivery”这类说法，它们说明这个岗位正好要用到这项能力。

简历上不要只写“开发过 REST API”，要具体：编写契约优先的 OpenAPI 规范，与合作方集成团队一起评审，设计幂等的写操作端点，让客户端可以安全重试。

面试前，准备好这样一个场景的回答：客户需要修改一个有多个系统调用的字段，你怎么办？有说服力的回答，从第一天就写下来的那份契约讲起。

**本周动手试试:**

- 挑一个你写过的端点，不看代码，重写它的 OpenAPI 契约。记下契约与生产环境中代码不一致的地方。
- 梳理当前项目中的写操作端点，标出客户端可能在超时后重试的那些。逐个检查：同一个请求发两次，会不会生成重复记录。
- 在你的 API 响应里找一个带数据库列名的字段，写一层映射，把它改名为业务术语。

## 信源

- [What is an API (application programming interface)? | IBM](https://www.ibm.com/think/topics/api)

- [Learn | GraphQL](https://graphql.org/learn/)

- [GraphQL Best Practices | GraphQL](https://graphql.org/learn/best-practices/)

- [Web API Design Best Practices - Azure Architecture Center | Microsoft Learn](https://learn.microsoft.com/en-us/azure/architecture/best-practices/api-design)
