React / 系统课时
返回标准响应
返回标准响应
接口可以返回任意 JSON,但缺少统一约定会迫使前端为每个接口编写不同判断。本课建立固定的成功与失败结构,并让 HTTP 状态码、业务代码、错误消息和追踪标识各自承担清晰职责。
学习目标
- 使用 HTTP 状态码表达请求处理结果
- 统一成功与失败响应的数据结构
- 通过追踪标识定位一次具体请求
划分响应职责
HTTP 状态码供浏览器、代理和客户端库判断请求类别,例如 200 表示成功、400 表示参数错误、404 表示资源不存在、409 表示业务冲突、500 表示未处理异常。
响应体中的 code 用于稳定表达业务结果,message 面向调用方说明原因,data 承载正常数据,traceId 用于关联服务端日志。不要只返回 success: false,也不要用 200 包装所有失败。
封装统一响应
下面的辅助函数集中生成结构,Route Handler 只决定业务数据和状态码。
ts
// lib/api-response.ts
import { randomUUID } from "node:crypto";
import { NextResponse } from "next/server";
export type ApiBody<T> = {
code: string;
message: string;
data: T | null;
traceId: string;
};
export function ok<T>(data: T, message = "操作成功") {
const body: ApiBody<T> = {
code: "OK",
message,
data,
traceId: randomUUID(),
};
return NextResponse.json(body, { status: 200 });
}
export function fail(
status: number,
code: string,
message: string,
) {
const body: ApiBody<never> = {
code,
message,
data: null,
traceId: randomUUID(),
};
return NextResponse.json(body, { status });
}
// app/api/profile/route.ts
import { fail, ok } from "@/lib/api-response";
export async function GET(request: Request) {
const userId = new URL(request.url).searchParams.get("userId");
if (!userId) {
return fail(400, "USER_ID_REQUIRED", "缺少 userId");
}
return ok({ id: userId, nickname: "Ada" }, "查询成功");
}生效行为:成功和失败响应拥有相同字段,调用方可以先看 HTTP 状态,再读取稳定的 code;每次响应都会生成不同的 traceId。执行请求,其中 <PORT> 替换为实际端口:
bash
curl -i "http://localhost:<PORT>/api/profile"预期输出中的 <ID> 为实际生成的追踪标识:
text
HTTP/1.1 400 Bad Request
Content-Type: application/json
{"code":"USER_ID_REQUIRED","message":"缺少 userId","data":null,"traceId":"<ID>"}保持错误消息稳定
业务代码应适合程序判断,因此发布后不要随意改名。message 可以更友好,但不要暴露 SQL、文件路径、密钥或异常堆栈。详细异常应写入服务端日志,并通过同一个 traceId 与客户端反馈关联。
创建资源时可返回 201,无响应体的删除可返回 204,参数错误与业务冲突则分别使用 400 和 409。状态码应描述当前请求结果,而不是内部实现步骤。
按自己的节奏,确认真正理解。