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。状态码应描述当前请求结果,而不是内部实现步骤。

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

目录与阅读设置

阅读设置

17

记录一个想法

返回标准响应

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

登录哪都通