技术英语 / 系统课时
描述一个 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 参考中定义,这段文字只演示描述方式,不代表可直接调用的真实服务。
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 描述让读者在真正发送请求之前,就能预测“调用它会发生什么”。做到这一点,比追求更正式或更复杂的英文更重要。