React / 系统课时

组织接口错误处理

组织接口错误处理

接口错误处理的重点不是“所有地方都 try/catch”,而是让调用方始终收到可预测的状态码和错误结构,同时把真正的系统异常留在服务端日志中。完成本节后,你可以把参数错误、业务冲突和未知异常映射成稳定的 API 契约。

学习目标

  • 为参数错误、业务冲突和系统异常选择合适的 HTTP 状态码
  • 用统一错误类型和响应函数减少 Route Handler 中的重复分支
  • 让客户端获得稳定错误码,同时避免泄露堆栈、数据库消息等内部细节

先固定错误契约

客户端最需要稳定的是两件事:HTTP 状态码用于判断错误类别,机器可读的 code 用于决定具体交互。message 可以面向用户或开发者解释问题,但不应该承担程序分支判断,因为文案以后可能调整。

本节采用统一结构 {"error":{"code":"...","message":"...","requestId":"..."}}。参数或 JSON 格式错误返回 400,资源状态产生业务冲突返回 409,无法预期的程序或基础设施异常返回 500。成功响应仍走正常的 2xx 状态码,不把失败伪装成 200。

让已知错误和未知异常分流

错误处理最好在 Route Handler 边界完成一次映射:可预期的校验或业务错误转换为明确的 4xx;未识别异常记录到服务端,并只向客户端返回通用 500。这样内部实现即使更换数据库或第三方服务,外部错误契约仍可保持稳定。

Route Handler 错误分流与响应映射

用一个路由实现稳定响应

下面的 app/api/tags/route.ts 不依赖数据库,使用几个固定输入模拟参数错误、业务冲突和未知异常。requestId 用于把客户端报错与服务端日志关联起来。

ts
class ApiError extends Error {
  constructor(
    public readonly status: number,
    public readonly code: string,
    message: string,
  ) {
    super(message);
  }
}

function errorResponse(error: ApiError, requestId: string) {
  return Response.json(
    {
      error: {
        code: error.code,
        message: error.message,
        requestId,
      },
    },
    { status: error.status },
  );
}

export async function POST(request: Request) {
  const requestId = crypto.randomUUID();

  try {
    let body: unknown;
    try {
      body = await request.json();
    } catch {
      throw new ApiError(400, 'INVALID_JSON', '请求体必须是合法 JSON');
    }

    const name =
      body && typeof body === 'object' && 'name' in body
        ? (body as { name: unknown }).name
        : undefined;

    if (typeof name !== 'string' || name.trim().length < 2) {
      throw new ApiError(400, 'INVALID_NAME', 'name 至少包含 2 个字符');
    }

    const normalizedName = name.trim();
    if (normalizedName.toLowerCase() === 'existing') {
      throw new ApiError(409, 'TAG_CONFLICT', '标签已存在');
    }

    // 仅用于验证未知异常路径;真实代码不会靠特殊输入主动制造故障。
    if (normalizedName.toLowerCase() === 'crash') {
      throw new Error('simulated database outage');
    }

    return Response.json(
      { data: { id: 'tag-demo', name: normalizedName } },
      { status: 201 },
    );
  } catch (error) {
    if (error instanceof ApiError) {
      return errorResponse(error, requestId);
    }

    console.error('create tag failed', { requestId, error });
    return Response.json(
      {
        error: {
          code: 'INTERNAL_ERROR',
          message: '服务暂时不可用',
          requestId,
        },
      },
      { status: 500 },
    );
  }
}

使用同一个路由依次验证参数错误、冲突、未知异常和成功创建。curl 的 -w 会把状态码追加到响应体后,方便直接检查。

bash
curl -s -w '\nSTATUS:%{http_code}\n' -X POST http://localhost:3000/api/tags -H 'Content-Type: application/json' -d '{"name":1}'
curl -s -w '\nSTATUS:%{http_code}\n' -X POST http://localhost:3000/api/tags -H 'Content-Type: application/json' -d '{"name":"existing"}'
curl -s -w '\nSTATUS:%{http_code}\n' -X POST http://localhost:3000/api/tags -H 'Content-Type: application/json' -d '{"name":"crash"}'
curl -s -w '\nSTATUS:%{http_code}\n' -X POST http://localhost:3000/api/tags -H 'Content-Type: application/json' -d '{"name":"nextjs"}'

预期输出如下,其中每次错误响应的 requestId 都是动态值。

text
{"error":{"code":"INVALID_NAME","message":"name 至少包含 2 个字符","requestId":"<ID>"}}
STATUS:400
{"error":{"code":"TAG_CONFLICT","message":"标签已存在","requestId":"<ID>"}}
STATUS:409
{"error":{"code":"INTERNAL_ERROR","message":"服务暂时不可用","requestId":"<ID>"}}
STATUS:500
{"data":{"id":"tag-demo","name":"nextjs"}}
STATUS:201

日志与响应保持不同粒度

4xx 通常属于调用方可修正的问题,响应应告诉客户端哪个契约没有满足;500 则代表服务端没有按预期完成请求,应该记录 requestId、异常类型和必要上下文,但不要把堆栈、SQL、密钥或第三方原始错误直接返回。

统一错误边界之后,业务代码只负责“发现并抛出已知问题”,Route Handler 负责“映射成对外契约”,未知异常则进入日志和监控。这样既方便客户端处理,也能避免接口因内部实现变化而不断改变错误格式。

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

目录与阅读设置

阅读设置

17

记录一个想法

组织接口错误处理

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

登录哪都通