React / 系统课时

处理请求错误

处理请求错误

请求失败并不都意味着“系统崩了”。本课把超时、未登录、无权限、资源不存在和真正的程序异常分开处理,让页面能够给出明确反馈,并把不可恢复的异常交给 Next.js 的错误边界。

学习目标

  • 能根据 HTTP 状态和异常类型区分可预期失败与程序异常
  • 能为服务端 fetch 设置超时,并为 401、403、404 设计不同结果
  • 能用 notFound()、not-found.tsx 和 error.tsx 组织路由级兜底

先按错误类型决定处理方式

可预期失败应当被建模成明确结果,而不是全部 throw new Error()。例如未登录、无权限、资源不存在和上游暂时不可用,都属于业务运行中可能正常出现的状态;真正未知的异常才适合继续抛出,让错误边界接管。

场景 推荐处理 用户看到的结果
请求超时 返回“服务暂不可用”状态 可重试提示
401 未登录 返回未登录状态或跳转登录页 登录提示
403 无权限 返回禁止访问状态 权限提示
404 数据不存在 调用 notFound() not-found.tsx
未知异常 继续抛出 最近的 error.tsx

请求错误分流流程

把状态码和超时转换成明确结果

下面是片段示例,放在 app/articles/[id]/page.tsx 中;项目需要先在 .env.local 配置 API_BASE_URL,并保证上游存在 /articles/:id 接口。这里显式使用 cache: 'no-store',避免错误演示被旧缓存结果干扰。

tsx
import { notFound } from 'next/navigation'

type Article = {
  id: string
  title: string
  content: string
}

type Result =
  | { kind: 'ok'; article: Article }
  | { kind: 'unauthorized' | 'forbidden' | 'not-found' | 'unavailable' }

async function getArticle(id: string): Promise<Result> {
  const baseUrl = process.env.API_BASE_URL
  if (!baseUrl) throw new Error('API_BASE_URL is not configured')

  try {
    const response = await fetch(`${baseUrl}/articles/${id}`, {
      cache: 'no-store',
      signal: AbortSignal.timeout(3000),
    })

    if (response.status === 401) return { kind: 'unauthorized' }
    if (response.status === 403) return { kind: 'forbidden' }
    if (response.status === 404) return { kind: 'not-found' }
    if (!response.ok) return { kind: 'unavailable' }

    return { kind: 'ok', article: (await response.json()) as Article }
  } catch (error) {
    // 超时是可预期的运行时失败,未知异常继续交给错误边界。
    if (error instanceof DOMException && error.name === 'TimeoutError') {
      return { kind: 'unavailable' }
    }
    throw error
  }
}

export default async function Page({
  params,
}: {
  params: Promise<{ id: string }>
}) {
  const { id } = await params
  const result = await getArticle(id)

  if (result.kind === 'not-found') notFound()
  if (result.kind === 'unauthorized') return <p>请先登录后查看。</p>
  if (result.kind === 'forbidden') return <p>你没有查看这篇文章的权限。</p>
  if (result.kind === 'unavailable') return <p>数据服务暂时不可用,请稍后重试。</p>

  return (
    <article>
      <h2>{result.article.title}</h2>
      <p>{result.article.content}</p>
    </article>
  )
}

预期结果

text
200:渲染文章标题与正文
401:页面显示“请先登录后查看。”
403:页面显示“你没有查看这篇文章的权限。”
404:终止当前路由段渲染并显示 not-found.tsx
超过 3 秒未完成:页面显示“数据服务暂时不可用,请稍后重试。”
其他未知异常:继续抛出,由最近的 error.tsx 处理

用特殊文件承接路由级失败

notFound() 适合“资源确实不存在”,它会终止当前路由段的渲染,并寻找对应的 not-found.tsx。error.tsx 则用于捕获未处理异常;它必须是 Client Component。两者职责不同,不要用一个通用错误页把 404 和程序异常混在一起。

片段示例:在 app/articles/[id]/ 下分别创建两个文件。

tsx
// not-found.tsx
export default function NotFound() {
  return <p>没有找到这篇文章。</p>
}
tsx
// error.tsx
'use client'

export default function Error() {
  return <p>页面发生异常,请稍后重试。</p>
}

预期结果

text
调用 notFound():显示“没有找到这篇文章。”
出现未捕获异常:显示“页面发生异常,请稍后重试。”

避免把所有失败都变成 500

最常见的问题是只写 if (!response.ok) throw new Error(...)。这样虽然代码短,却丢失了 401、403、404 等重要语义,也无法给用户正确的下一步。处理请求错误时应先保留业务可判断的状态,再把真正未知的异常交给错误边界;这样页面反馈、日志和后续监控才不会混成一类。

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

目录与阅读设置

阅读设置

17

记录一个想法

处理请求错误

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

登录哪都通