技术英语 / 系统课时
写清返回值与错误情况
写清返回值与错误情况
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.。如果某类基础设施异常可能重试,还应明确是否要求幂等以及重试限制,而不是默认所有异常都适合重试。
用完整示例校对返回说明
下面的可运行示例故意覆盖三条路径。它可以帮助作者检查正文是否真的描述了代码行为,而不是只描述最常见的成功情况。
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);
}
}预期输出
{"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”没有可操作的判断标准。
更可靠的写法是把条件落实到可观察事实,例如“订单不存在”“参数为空”“上游服务超时”,并指出对应的返回形式或异常类型。最终目标不是把所有内部实现暴露出来,而是让调用方仅凭公开契约就能正确处理每一条外部可见路径。