React / 系统课时
组织接口错误处理
组织接口错误处理
接口错误处理的重点不是“所有地方都 try/catch”,而是让调用方始终收到可预测的状态码和错误结构,同时把真正的系统异常留在服务端日志中。完成本节后,你可以把参数错误、业务冲突和未知异常映射成稳定的 API 契约。
学习目标
- 为参数错误、业务冲突和系统异常选择合适的 HTTP 状态码
- 用统一错误类型和响应函数减少 Route Handler 中的重复分支
- 让客户端获得稳定错误码,同时避免泄露堆栈、数据库消息等内部细节
先固定错误契约
客户端最需要稳定的是两件事:HTTP 状态码用于判断错误类别,机器可读的 code 用于决定具体交互。message 可以面向用户或开发者解释问题,但不应该承担程序分支判断,因为文案以后可能调整。
本节采用统一结构 {"error":{"code":"...","message":"...","requestId":"..."}}。参数或 JSON 格式错误返回 400,资源状态产生业务冲突返回 409,无法预期的程序或基础设施异常返回 500。成功响应仍走正常的 2xx 状态码,不把失败伪装成 200。
让已知错误和未知异常分流
错误处理最好在 Route Handler 边界完成一次映射:可预期的校验或业务错误转换为明确的 4xx;未识别异常记录到服务端,并只向客户端返回通用 500。这样内部实现即使更换数据库或第三方服务,外部错误契约仍可保持稳定。

用一个路由实现稳定响应
下面的 app/api/tags/route.ts 不依赖数据库,使用几个固定输入模拟参数错误、业务冲突和未知异常。requestId 用于把客户端报错与服务端日志关联起来。
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 会把状态码追加到响应体后,方便直接检查。
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 都是动态值。
{"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 负责“映射成对外契约”,未知异常则进入日志和监控。这样既方便客户端处理,也能避免接口因内部实现变化而不断改变错误格式。