企业官网建设流程全解析

• 文档
• 教程
• 后端

本文基于 Node.js 最佳实践清单（nodebestpractices）错误处理章节第 2.5 条展开：REST API 不仅要以 HTTP 状态码返回结果，还必须让 API 的使用者提前知道"可能遇到哪些错误"；如果你的端点已采用 GraphQL，则可以直接利用 schema 本身与注释完成错误契约。读完本文，你将掌握在 REST 场景下用 Swagger/OpenAPI 文档化错误码、在 GraphQL 场景下借助标准错误结构表达失败原因的具体方法，并理解这套做法与集中式错误处理、操作型/程序员错误分类的衔接关系。

为什么"告诉调用方会发生什么错误"是刚需

REST API 通过 HTTP 状态码返回执行结果，但对 API 使用者而言，仅仅了解 API 的 schema（请求/响应结构）是远远不够的——他们还必须了解潜在的错误形态，这样调用方才能捕获错误并做出妥善处理，而不是因为收到一个看不懂的错误就崩溃、重试或误报。

一个典型场景：假设你的 API 负责注册新用户，当客户名称已存在时返回409 Conflict。如果 API 文档提前声明了这一行为，调用方就能据此渲染最佳的用户体验（例如提示"该用户名已被占用"），而不是把 409 当成系统故障。

这正是该项目在 README.korean.md 中给出的核心原则：

핵심요약（核心要义）：提前告知 API 调用方可能会收到哪些错误，使其能够在无崩溃的前提下谨慎处理。RESTful API 通常通过 Swagger 这类 API 文档化框架实现；GraphQL 则可以利用 schema 与注释达到同样目的。

그렇게 하지 않을 경우（若不这样做）：API 客户端可能仅仅因为收到了无法理解的错误就决定崩溃并重启。注意，调用你 API 的人很可能就是你自己——这在微服务环境中尤为常见。

在微服务架构下，服务之间互相调用是常态，"你的调用者是你自己"意味着：错误文档化不完善，最终受害的是整个系统链路的稳定性。

REST 场景：用 Swagger（OpenAPI）文档化错误

Swagger 是定义 API 文档 schema 的标准，它背后是一整套工具生态，让你可以在线轻松生成、维护并共享 API 文档。通过这种文档化框架，你可以把"什么输入会产生什么错误码"这种契约显式地固定下来。

如何在文档中声明错误码

沿用开篇的注册用户例子，在 Swagger/OpenAPI 规范中，你可以在操作（operation）的响应定义里为每个错误码补充描述：

paths: /users: post: summary: 注册新用户 requestBody: required: true content: application/json: schema: type: object required: [name] properties: name: type: string responses: '201': description: 注册成功 '409': description: 客户名称已存在（唯一性冲突） '400': description: 请求参数缺失或非法

当文档中包含这样的声明后，调用方开发者可以提前编写对应逻辑：捕获409时提示"名称已被占用"，捕获400时提示"请检查输入"，而不是把所有非 2xx 响应一律当成未知故障。

文档化错误与"仅记录成功路径"的区别

很多团队的 API 文档只描述成功响应，把错误响应留给调用方"自行猜测"。这一做法的后果在该项目的 "Otherwise" 说明中被直接点破：调用方无法理解的错误，可能导致客户端做出崩溃并重启这类极端反应。在微服务环境里，这种不确定的错误传播会被成倍放大。因此，错误码文档化应当与请求/响应 schema 文档化同等重要。

GraphQL 场景：schema 本身就是错误契约

如果你的 API 端点已经采用 GraphQL，那么错误结构由 GraphQL 规范本身严格保证（规范中对错误的外形、如何处理有明确要求），客户端工具链也会据此解析错误。在此基础上，你还可以用注释（comment-based documentation）为 schema 补充人类可读的说明。

GraphQL 错误示例：从查询到响应

下面是一个真实的失败查询示例（取自 Star Wars API——SWAPI）：

# should fail because id is not valid { film(id: "1ZmlsbXM6MQ==") { title } }

由于传入的 id 不是合法值，这次查询会失败，服务端返回的响应体如下：

{ "errors": [ { "message": "No entry in local cache for https://swapi.co/api/films/.../", "locations": [ { "line": 2, "column": 3 } ], "path": [ "film" ] } ], "data": { "film": null } }

注意这个响应体的三个关键结构：

• errors数组：错误统一挂在顶层errors下，每项至少包含message；locations给出查询文本中出错的位置（第 2 行第 3 列），path指明错误发生在哪个字段（film）上。
• data字段：对应字段被置为null，而不是整次请求失败，这让客户端工具能够精确地把错误定位到具体字段。
• 结构与 schema 双重约束：由于 GraphQL 规范固定了errors的外形，客户端工具链可以写出通用的错误解析与展示逻辑，无需为每个端点定制错误解析器。

你还可以在 schema 中用注释补充错误语义，例如：

""" 按 id 查询电影。 当 id 无法解析为合法记录时，返回 null，并在 errors 中给出说明。 """ type Query { film(id: ID!): Film }

这样，GraphQL 的 schema 既提供了强类型保证，又通过注释承载了错误语义，形成"结构 + 注释"的双重文档。

与集中式错误处理的衔接

错误文档化解决的是"对外告知"的问题，而集中式错误处理解决的是"对内处置"的问题，二者同属该项目的错误处理最佳实践家族：

• 集中式错误处理（centralizedhandling）：所有入口（API 路由、定时任务、消息队列订阅者、未捕获异常）把错误统一交给一个专门的 error handler 对象，由它负责记录日志、发送监控指标、决定进程是否崩溃或向响应流写出错误响应。典型的流程是：某模块抛出错误 → API 路由捕获 → 转发给错误中间件 → 调用集中式错误处理器。
• 操作型错误 vs 程序员错误（operationalvsprogrammererror）：通过isOperational标记区分"可预期的操作型错误"（如连接失败、输入非法）与"原因不明的程序员错误"。操作型错误通常记录日志即可，程序员错误则往往意味着进程状态不可信。

把它们串起来，就构成了一条完整的错误治理链路：集中式处理器把错误分类、记录并转成可预测的响应 → Swagger/GraphQL 文档把"哪些错误码/错误形态会返回"提前告知调用方 → 调用方按文档从容处理。这也是该文档所在错误处理章节（errorhandling 目录）的整体设计意图。

名句佐证：为什么必须告知调用方

来自 Joyent 博客（在 "Node.js logging" 关键词下排名第一）的一段话，与本主题高度呼应：

我们已经讨论过如何处理错误，但当你编写一个新函数时，你要如何把错误传递给调用你函数的代码？……如果你不知道可能发生哪些错误、也不理解它们意味着什么，那么你的程序只有在偶然情况下才可能是正确的。所以，当你编写一个新函数时，你必须告诉调用者：会发生哪些错误，它们分别意味着什么……

这句话把"错误文档化"从锦上添花提升到了程序正确性的层面：调用方只有先知道错误集，才能写出正确的处理逻辑。对 Node.js 服务而言，这意味着在编写 API 端点时，就要同步产出错误契约——无论是 Swagger/OpenAPI 的响应定义，还是 GraphQL 的 errors 结构与注释。

实用工具：Swagger 在线文档创建工具

Swagger 提供了一整套在线工具生态，让你不需要额外搭建文档站点，就能根据 schema 自动生成可交互的 API 文档：

Swagger 在线生成的 API 文档界面（API 错误处理）

从截图可以看到，Swagger 在线文档会把各个端点的请求/响应定义（包括错误响应）渲染为结构化页面，调用方开发者可以直接在页面上查看每个状态码的含义，甚至在线发起测试请求。这正是"错误文档化"落地的抓手——文档不是写给别人看的摆设，而是可以被直接检索、测试与消费的契约。

实践检查清单

1. REST 端点：为每个操作声明全部可能返回的状态码及其语义（尤其是 4xx 业务错误，如400、404、409），用 Swagger/OpenAPI 生成在线文档。
2. GraphQL 端点：依赖规范保证的errors结构，用message/locations/path精确表达失败位置，并用注释补充业务错误语义。
3. 错误响应设计：保证响应体中的错误信息可被调用方程序化解析（结构化字段而非纯文本），与 集中式错误处理 的输出保持一致的形态。
4. 持续维护：当新增错误码或改变错误语义时，同步更新文档，让文档始终反映真实的 API 行为。
5. 微服务内省：记住"调用者可能就是你自己"，内部服务之间的错误契约同样需要文档化，避免未知错误引发连锁崩溃与重启。

• 文档
• 教程
• 后端