技术英语 / 系统课时

写清返回值与错误情况

写清返回值与错误情况

API 说明不能只写“返回结果”或“失败时抛错”。调用方真正需要知道的是:哪些结果代表成功,哪些属于可预期的业务失败,哪些才是异常,以及每一种情况应该继续处理、提示用户还是进入重试或故障路径。

学习目标

  • 区分成功返回、业务失败和异常三类结果,并写清各自语义
  • 用稳定的返回结构、错误标识和处理建议描述调用契约
  • 检查文档是否让调用方无需阅读实现代码就能处理失败路径

先把三类结果分开写

成功返回表示操作按约定完成,文档应说明返回值包含什么以及关键字段何时存在。业务失败表示程序本身仍正常工作,只是业务条件不满足,例如订单不存在、余额不足或状态不允许操作。这类结果通常应该有稳定、可判断的错误码,而不是只给自然语言消息。

异常则表示调用无法按正常契约继续,例如参数类型错误、依赖服务不可用或内部状态损坏。文档需要明确异常类型、触发条件,以及调用方是否适合捕获、重试或直接上报。

成功返回、业务失败与异常的处理分支

文档中不要把三者混成一句模糊的 Returns the order or an error.。更清楚的写法是分别说明正常返回、可预期失败和抛出的异常,因为它们要求调用方采用不同控制流。

把契约写成调用方可以执行的动作

错误说明至少回答三个问题:如何识别、什么时候发生、收到后怎么办。其中错误码应保持稳定;错误消息可以用于展示或诊断,但调用方不应依赖消息文本做分支判断。

例如可以写成:Returns { ok: false, code: "ORDER_NOT_FOUND" } when the order does not exist. The caller may show a not-found message and should not retry the request.。这句话同时给出了识别方式、触发条件和建议动作。

对于异常,也应避免只写 May throw an error.。如果契约能够确定,应具体到异常类型和条件,例如:Throws TypeError when orderId is not a non-empty string.。如果某类基础设施异常可能重试,还应明确是否要求幂等以及重试限制,而不是默认所有异常都适合重试。

用完整示例校对返回说明

下面的可运行示例故意覆盖三条路径。它可以帮助作者检查正文是否真的描述了代码行为,而不是只描述最常见的成功情况。

js
function getOrder(orderId) {
  // 参数错误属于调用契约被违反,因此直接抛出异常。
  if (typeof orderId !== "string" || orderId.length === 0) {
    throw new TypeError("INVALID_ORDER_ID");
  }

  if (orderId === "A100") {
    return {
      ok: true,
      value: { id: "A100", status: "paid" }
    };
  }

  // 查无订单是可预期的业务结果,不需要用异常表达。
  return { ok: false, code: "ORDER_NOT_FOUND" };
}

for (const id of ["A100", "B200", ""]) {
  try {
    console.log(JSON.stringify(getOrder(id)));
  } catch (error) {
    console.log(error.message);
  }
}

预期输出

text
{"ok":true,"value":{"id":"A100","status":"paid"}}
{"ok":false,"code":"ORDER_NOT_FOUND"}
INVALID_ORDER_ID

据此,参考说明就应明确:成功时读取 value;不存在时检查 ORDER_NOT_FOUND 并进入业务分支;空字符串则违反参数约束并抛出 TypeError。如果文档只覆盖其中一条路径,就还没有完整描述这个接口。

避免让调用方猜测

Returns null on failure. 往往信息不足,因为读者不知道“失败”包含哪些情况,也不知道 null 是否可重试。Throws on invalid requests. 同样过于宽泛,因为“invalid”没有可操作的判断标准。

更可靠的写法是把条件落实到可观察事实,例如“订单不存在”“参数为空”“上游服务超时”,并指出对应的返回形式或异常类型。最终目标不是把所有内部实现暴露出来,而是让调用方仅凭公开契约就能正确处理每一条外部可见路径。

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

目录与阅读设置

阅读设置

17

记录一个想法

写清返回值与错误情况

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

登录哪都通