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 等重要语义,也无法给用户正确的下一步。处理请求错误时应先保留业务可判断的状态,再把真正未知的异常交给错误边界;这样页面反馈、日志和后续监控才不会混成一类。
按自己的节奏,确认真正理解。