Vue / 系统课时

建立错误反馈机制

建立错误反馈机制

本课把请求失败转换成一致、克制且可追踪的用户反馈。完成后,网络异常、超时、登录失效和服务端错误会走不同策略,相同错误不会连续弹窗,内部错误细节也不会暴露给页面。

学习目标

  • 为不同错误类型制定清晰的反馈策略
  • 实现弹窗去重、登录跳转防抖与信息脱敏
  • 让页面通过统一执行函数处理请求结果

从“捕获就弹窗”改为分层处理

错误反馈不应等同于 catch 后立刻显示后端消息。请求层负责产生结构化错误,反馈层负责决定是否提示、提示什么以及是否跳转,页面只负责加载态、空状态和可恢复操作。

当多个并发请求同时失败时,直接在每个请求里弹窗会造成提示风暴。权限失效还可能触发多次登录跳转。因此反馈中心需要同时具备分类、去重和单次导航能力。

请求错误反馈分层与去重机制

制定反馈策略

业务错误可以显示经过约束的业务文案;断网和超时应告诉用户可执行的下一步;401 只提示一次并跳转登录页;5xx 只显示通用文案,详细堆栈进入内部日志。普通 4xx 不应直接展示服务器原文,以免暴露实现细节。

错误类型 页面反馈 额外动作
BUSINESS 显示安全、简短的业务文案 保留当前页面
NETWORK 提示检查网络后重试 不跳转
TIMEOUT 提示请求超时 允许重试
AUTH 提示登录已失效 只跳转一次
SERVER 显示通用服务异常 记录追踪号
HTTP 显示通用请求失败 页面决定是否修正输入
PROTOCOL 显示通用响应异常 检查接口契约

实现统一错误反馈中心

下面的主示例保存为 src/utils/error-feedback.ts。它不依赖具体请求函数,只要求错误对象包含 name、kind、status、code 和可选的 requestId,因此可以与响应拦截器稳定协作。

ts
import { ElMessage } from 'element-plus'
import router from '@/router'

type ErrorKind =
  | 'BUSINESS'
  | 'HTTP'
  | 'AUTH'
  | 'SERVER'
  | 'TIMEOUT'
  | 'NETWORK'
  | 'PROTOCOL'

interface AppRequestError extends Error {
  readonly kind: ErrorKind
  readonly status?: number
  readonly code?: number
  readonly requestId?: string
}

const ERROR_KINDS = new Set<ErrorKind>([
  'BUSINESS',
  'HTTP',
  'AUTH',
  'SERVER',
  'TIMEOUT',
  'NETWORK',
  'PROTOCOL'
])

const recentMessages = new Map<string, number>()
let authRedirecting = false
const DEDUPE_WINDOW = 1500

function isRequestError(error: unknown): error is AppRequestError {
  if (!(error instanceof Error)) return false
  const kind = (error as Partial<AppRequestError>).kind
  return typeof kind === 'string' && ERROR_KINDS.has(kind as ErrorKind)
}

function showOnce(key: string, message: string): void {
  const now = Date.now()
  const lastTime = recentMessages.get(key) ?? 0

  // 同类错误在短时间内只提示一次,避免并发请求形成弹窗风暴。
  if (now - lastTime < DEDUPE_WINDOW) return

  recentMessages.set(key, now)
  ElMessage.error(message)
}

function safeBusinessMessage(message: string): string {
  const oneLine = message.replace(/[\r\n]+/g, ' ').trim()
  return oneLine && oneLine.length <= 80
    ? oneLine
    : '操作未完成,请检查后重试'
}

export function handleRequestError(error: unknown): void {
  if (!isRequestError(error)) {
    showOnce('UNKNOWN', '发生未知错误,请稍后重试')
    return
  }

  const kind = error.kind

  if (kind === 'AUTH') {
    if (authRedirecting || router.currentRoute.value.name === 'login') return
    authRedirecting = true
    ElMessage.warning('登录状态已失效,请重新登录')

    const redirect = router.currentRoute.value.fullPath
    void router
      .replace({ name: 'login', query: { redirect } })
      .finally(() => {
        window.setTimeout(() => {
          authRedirecting = false
        }, DEDUPE_WINDOW)
      })
    return
  }

  const feedback: Record<Exclude<ErrorKind, 'AUTH'>, string> = {
    BUSINESS: safeBusinessMessage(error.message),
    NETWORK: '网络连接失败,请检查网络后重试',
    TIMEOUT: '请求超时,请稍后重试',
    SERVER: '服务暂时不可用,请稍后重试',
    HTTP: '请求失败,请检查输入或稍后重试',
    PROTOCOL: '响应格式异常,请稍后重试'
  }

  const key = `${kind}:${error.status ?? ''}:${error.code ?? ''}`
  showOnce(key, feedback[kind])
}

export type RequestResult<T> =
  | { ok: true; data: T }
  | { ok: false; error: unknown }

export async function runRequest<T>(
  task: () => Promise<T>
): Promise<RequestResult<T>> {
  try {
    return { ok: true, data: await task() }
  } catch (error) {
    handleRequestError(error)
    return { ok: false, error }
  }
}

预期结果

text
1500ms 内出现 3 个相同的 SERVER 错误:只显示 1 次通用错误提示
多个请求同时返回 401:只提示 1 次并执行 1 次登录跳转
服务端返回堆栈或数据库细节:页面不会直接展示这些内容

去重窗口是交互参数,可按项目体验调整;动态的请求时间、状态码和追踪号可分别记录为 <TIME>、<ID>,但不要拼接进用户可见提示。

在页面边界统一调用

页面通过 runRequest 获取可判别结果,不必重复编写 try/catch 和弹窗逻辑。下面是项目内调用片段,依赖已封装的 request<T>。

ts
const result = await runRequest(() =>
  request<User[]>({ method: 'GET', url: '/users' })
)

if (result.ok) {
  users.value = result.data
} else {
  users.value = []
}

预期结果

text
请求成功:users.value 更新为用户数组
请求失败:统一反馈中心处理提示,页面进入空数据状态

防止信息泄漏与重复反馈

后端 message 只有在明确约定为可展示业务文案时才允许进入界面。5xx、网关错误、未知异常和普通 HTTP 错误均使用前端固定文案;完整响应、堆栈与追踪号应写入受权限控制的日志系统。

同一个请求只能在一个边界调用 runRequest。如果请求封装、状态管理和页面三层都重复调用反馈函数,虽然去重可以缓解弹窗风暴,但仍会产生重复日志和难以追踪的控制流。

验收检查

  • 关闭网络后只出现一次可理解的网络提示
  • 模拟超时后页面保持可操作,并允许用户重试
  • 并发返回 401 时只跳转一次登录页
  • 模拟 500 响应时不展示堆栈、SQL 或服务器原文
按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

建立错误反馈机制

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

登录哪都通