技术英语 / 系统课时

描述一个 API 到底做什么

描述一个 API 到底做什么

API 说明最常见的问题不是语法错,而是读完仍不知道接口会产生什么结果。本篇把接口描述压缩成“目的、触发条件、核心行为”三部分,并用可复核的英文句式避免重复接口名称或写成空泛宣传语。

学习目标

  • 用明确动词写出 API 的核心行为,而不是改写接口名称
  • 在一句到两句描述中补齐触发条件、返回结果和必要副作用
  • 区分接口实际保证的行为与实现细节,避免文档过度承诺

从接口名称写到接口行为

接口名只能告诉读者“它大概和什么有关”,不能替代行为说明。比如 CreatePayment 已经包含 create 和 payment,如果正文只写 “Creates a payment.”,读者仍不知道创建的是什么、何时创建、创建后会发生什么。

一条有效描述通常回答三个问题:它操作什么对象;在什么前提下触发;调用后可观察到什么结果。只有其中某项对理解没有帮助时,才可以省略。

写法 问题 更好的方向
This API is used to create a payment. 重复接口名称,没有结果信息 说明创建的对象和后续状态
Handles payment creation. handles 过于模糊 改成具体动作,如 creates、returns
Creates a payment and returns its ID. 行为和结果都可验证 可按需补充触发条件

用具体动词承担主要信息

技术参考优先使用能直接对应系统行为的动词,例如 creates、returns、lists、updates、deletes、starts、stops、validates。避免用 handles、processes、manages 这类范围过大的词,除非接口确实包含多个不可再拆的动作。

片段示例:下面假设端点、资源名和状态语义已经在同一份 API 参考中定义,这段文字只演示描述方式,不代表可直接调用的真实服务。

text
POST /payments

Creates a payment for the specified order and returns the new payment ID.
If the order has already been paid, the request fails without creating another payment.

验证这段说明时,不要只看英语是否通顺,而要逐句对照实现或接口契约:第一句是否真的创建资源并返回 ID;第二句是否真的拒绝重复付款;失败时是否确实不会产生新资源。文档中的每个动词都应有可验证依据。

把条件和副作用写在行为附近

条件如果决定接口“会不会做这件事”,应紧跟核心行为,而不是藏在远处的注意事项里。常见条件包括资源当前状态、调用者权限、请求幂等键是否重复,以及是否满足前置配置。

副作用也应只写调用者需要知道的部分。例如接口除了更新订单,还会异步发送通知,那么只有当通知会影响调用者的重试、时序或业务判断时,才值得写进主描述;内部缓存刷新、日志记录等实现细节通常不需要出现。

可复用的句式是:动词 + 对象 + 条件 + 可观察结果。例如:“Cancels an unpaid order and returns the updated order.” 比 “Processes order cancellation.” 更容易让读者预测调用结果。

不要写出接口没有保证的事情

API 描述不是产品宣传语。若服务只把任务放入队列,就不要写 “Completes the export”;更准确的是 “Starts an export job and returns the job ID.”。若返回值只是当前快照,也不要暗示调用后数据永久不变。

还要区分“验证请求格式”和“保证业务成立”。例如接口检查邮箱格式,不等于它能保证邮箱真实存在。文档应使用与实际保证级别一致的动词,必要时用 attempts to、starts、requests 等表达异步或非最终状态。

写完后做三项检查

先删掉所有只是重复接口名的句子,再检查主句是否有明确动词,最后确认每个结果和限制都能由接口契约或实现验证。如果一句描述需要连续解释多个分支,应该把主行为保留在首句,把失败条件或例外另起一句,而不是把所有信息塞进一个超长句子。

好的 API 描述让读者在真正发送请求之前,就能预测“调用它会发生什么”。做到这一点,比追求更正式或更复杂的英文更重要。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

描述一个 API 到底做什么

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通