FDE Times 数据在招 FDE 职位 924▲33 近 7 天在招职位数的变化(同口径比较):不计入本周新开始追踪的公司的职位近 7 天新增 80在招公司 196支持远程 25%美国薪资中位数 $200k招聘最多 Databricks 107
ENVI

前线部署工程师(FDE)的专业媒体

技能指南 · 指南

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

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

分享微博

要点速览

  • 对客户的系统来说,API 就是一份契约。先写契约(OpenAPI 或 GraphQL schema),再写代码。
  • 不要让 API 照搬数据库。用业务名词命名资源,可能被重试的写操作都要做成幂等。
  • 新增字段很少会破坏客户端。破坏性变更无法避免时,选定一种版本策略,并在交接文档里写清楚。
三行对照的前后对比图。第一行:URI /getRiskScore 改为 /v1/shipments/{id},用名词代替动词。第二行:取自数据库列名的字段 rsk_v2、flg_manual 改为 score、riskLevel。第三行以橙色突出:写操作从 POST 改为 PUT,无论重试多少次,都只产生一条货运记录。
货运风险评分 API 草稿中的三处缺陷,以及契约优先的 OpenAPI 规范如何逐一修正。最难发现的是写操作用了 POST。来源:文中的假设场景,依据 Microsoft 的 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 规范,与合作方集成团队一起评审,设计幂等的写操作端点,让客户端可以安全重试。

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

这篇文章对你有帮助吗?

4 个信源
路线图上的下一篇 · 阶段 2: 全栈工程能力直连 ERP 数据库,为何是 FDE 最贵的捷径用防腐层隔开旧 schema,读写分走不同入口,下次 ERP 升级时新产品才不会被一起拖垮。