🚀 Next.js 后端能力扩展：错误处理与 HTTP 状态码规范

🌐 引言

Next.js 一直被称为 前端开发的瑞士军刀 ，但在 V13+ 的 App Router 体系中，它早已进化为 "全栈框架"。

前端跑页面，后端写 API，你一台机器就能搞定大半个微服务。

然而！

当我们满心欢喜地暴露 API 接口后，常常会被一个现实敲打：

前端报错了，返回却是 200？🤨
明明是客户端请求错了，却给出了 500？😵‍💫
用户看见的是 "Something went wrong"，但日志里却是一团浆糊？

今天，我们要聊聊 Next.js 的错误处理机制 以及 HTTP 状态码的奥义。

🔧 Next.js API Route 基础错误处理

在 Next.js (以 app/api 或老版本 pages/api 为例) 中，后端路由往往这样写：

javascript 复制代码

// app/api/hello/route.js
export async function GET(req) {
  try {
    const data = { message: "Hello, Next.js" };
    return new Response(JSON.stringify(data), { status: 200 });
  } catch (error) {
    return new Response(
      JSON.stringify({ error: "Internal Server Error" }), 
      { status: 500 }
    );
  }
}

这里我们使用了 Response API，一个与 Web 标准齐平 的好东西。

✨ 看点：这是浏览器里 fetch 的返回体，Next.js 后端也用它，保持了无缝一致性。

🎭 错误处理的艺术：别让 500 背锅

小小科普：500 并不是万能兜底！

一个健壮的 API，需要根据场景返回不同的 HTTP 状态码。

这里来一波拟人化解释：

400 Bad Request 🤦
"兄弟，你传的参数我根本解析不了。"
401 Unauthorized 🔑
"请出示证件，不带 Token 不让进。"
403 Forbidden 🚧
"有证件也没用，你的等级不够。"
404 Not Found 🕵️
"你找的资源根本不存在。"
409 Conflict ⚔
"数据冲突，比如注册重复。"
500 Internal Server Error 💥
"这真的是我的锅，我认了。"
503 Service Unavailable 💤
"我现在很忙，稍后再来。"

🧩 Next.js 中的状态码封装

与其每次都手搓 Response，我们可以写个简单的帮助器：

scala 复制代码

// utils/apiResponse.js
export function jsonResponse(data, status = 200) {
  return new Response(JSON.stringify(data), {
    status,
    headers: { "Content-Type": "application/json" },
  });
}

// utils/errors.js
export class ApiError extends Error {
  constructor(status, message) {
    super(message);
    this.status = status;
  }
}

在路由里使用：

javascript 复制代码

import { jsonResponse } from "@/utils/apiResponse";
import { ApiError } from "@/utils/errors";

export async function GET() {
  try {
    if (Math.random() > 0.5) {
      throw new ApiError(400, "随机参数错误");
    }
    return jsonResponse({ message: "一切顺利！" }, 200);
  } catch (err) {
    if (err instanceof ApiError) {
      return jsonResponse({ error: err.message }, err.status);
    }
    return jsonResponse({ error: "未知错误" }, 500);
  }
}

这样，错误处理就变得可控，日志清晰，前端收到的状态码也严格规范。

⚖️ 数学味的小插曲

错误处理其实可以类比于一种 映射函数：

输入：不同场景的异常 🎲
输出：对应的 HTTP 状态码 🏷 + 错误消息 💬

就像是一张"查表"的关系：

rust 复制代码

错误类型 -> 状态码  
参数缺失 -> 400  
未登录   -> 401  
权限不足 -> 403  
资源没了 -> 404  
代码异常 -> 500

如果把用户请求看作概率分布，那错误处理其实就是 保证分布的期望值落在预期范围内 。

否则 ------ "长尾事件" 会在你最不想出问题的时候炸出来。💣

📊 一个小图：错误处理流程

markdown 复制代码

请求进来 ➡️ 参数校验失败 ❌ → 返回 400
        ➡️ 权限校验失败 🚫 → 返回 401/403
        ➡️ 资源查无此人 🔍 → 返回 404
        ➡️ 内部异常 💥     → 返回 500
        ➡️ 一切顺利 ✅     → 返回 200

总结一句 ：

好的错误处理 = 用户收到合理提示 + 开发者能快速排查问题。

🏁 总结

错误不可怕，可怕的是一切都返回 500。
状态码是沟通语言，前后端都要会。
Next.js 给了足够的后端能力，合理封装响应工具函数，能让项目更优雅。

💡 最后提问：

你在项目里，是直接用 return new Response(...)，还是写了个"终极 API 工具箱"？
有没有踩过 状态码不规范 导致的线上事故？