API 里的每个字段,都是对客户 ERP 的承诺
先定谁能调用,再按调用方选 REST 或 GraphQL,先写契约后写代码,因为端点比模型活得更久。
要点速览
- 对客户的系统来说,API 就是一份契约。先写契约(OpenAPI 或 GraphQL schema),再写代码。
- 不要让 API 照搬数据库。用业务名词命名资源,可能被重试的写操作都要做成幂等。
- 新增字段很少会破坏客户端。破坏性变更无法避免时,选定一种版本策略,并在交接文档里写清楚。
项目进入第三周,货运风险模型已经跑起来,演示也很顺利。这时客户的 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 规范有意不定义网络传输、授权和分页,这三样都得由你的团队自己设计。
REST
- 最流行的 Web API 架构,ERP 团队几乎肯定熟悉
- 资源用名词命名,行为由 HTTP 方法决定
- 破坏性变更靠版本处理:URI、查询字符串、请求头或媒体类型
GraphQL
- 客户端只取需要的字段,适合数据需求各不相同的多个页面
- schema 随时间演进,而不是做版本管理
- 授权、分页和网络传输都要自己设计,因为规范没有定义
如果 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):先设计契约,也就是接口,再写实现它的代码。契约的第一部分声明写操作:
openapi: 3.0.3
info:
title: Shipment Risk API
version: 1.0.0
paths:
/v1/shipments/{shipmentId}:
put:
summary: 创建或更新一条货运记录(幂等,可安全重试)
接下来在同一个 paths 部分下,描述读操作以及 ERP 将收到的响应结构:
/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,这样你可以修改数据库表结构,契约保持不变。
什么时候需要版本?
六个月后,客户想加一个新字段 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 规范,与合作方集成团队一起评审,设计幂等的写操作端点,让客户端可以安全重试。
面试前,准备好这样一个场景的回答:客户需要修改一个有多个系统调用的字段,你怎么办?有说服力的回答,从第一天就写下来的那份契约讲起。
这篇文章对你有帮助吗?
感谢你的反馈!