前端错误边界与可观测性：让白屏有证据

// ❌ 坏做法：全局边界只返回一行文字，用户不知所措
class AppErrorBoundary extends React.Component<
  { children: React.ReactNode },
  { hasError: boolean }
> {
  state = { hasError: false }
 
  static getDerivedStateFromError() {
    return { hasError: true }
  }
 
  componentDidCatch(error: Error) {
    // 只上报了 error，没有上下文
    reportError(error)
  }
 
  render() {
    if (this.state.hasError) {
      return <p>出错了</p>
      // 用户看到这三个字，除了刷新什么也做不了
    }
    return this.props.children
  }
}

// ✅ 好做法：全局边界提供明确信息和恢复路径
class AppErrorBoundary extends React.Component<
  { children: React.ReactNode },
  { hasError: boolean; error: Error | null }
> {
  state = { hasError: false, error: null }
 
  static getDerivedStateFromError(error: Error) {
    return { hasError: true, error }
  }
 
  componentDidCatch(error: Error, info: React.ErrorInfo) {
    reportError({
      error,
      // 关键差异：同时上报组件堆栈和运行时上下文
      componentStack: info.componentStack,
      route: location.pathname,
      buildVersion: BUILD_VERSION,
      userId: getCurrentUserId(),
    })
  }
 
  render() {
    if (this.state.hasError) {
      return (
        <GlobalFallback
          onRetry={() => this.setState({ hasError: false, error: null })}
          onBack={() => navigate(-1)}
        />
      )
      // 用户可以选择重试或返回上一页
    }
    return this.props.children
  }
}

// ❌ 坏做法：整个页面共用一个 ErrorBoundary
function DashboardPage() {
  return (
    <ErrorBoundary fallback={<PageFallback />}>
      <DataPanel />
      <ChartPanel />   {/* 这里崩了，DataPanel 也没了 */}
      <FilterPanel />
    </ErrorBoundary>
  )
}

// ✅ 好做法：每个独立模块有自己的错误边界
function DashboardPage() {
  return (
    <div className="dashboard-grid">
      <ErrorBoundary
        fallback={<ModuleFallback title="数据面板" />}
        // 标签用于监控平台的分组过滤
        tags={{ module: 'data-panel' }}
      >
        <DataPanel />
      </ErrorBoundary>
 
      <ErrorBoundary
        fallback={<ModuleFallback title="趋势图" />}
        tags={{ module: 'chart-panel' }}
      >
        <ChartPanel />
      </ErrorBoundary>
 
      <ErrorBoundary
        fallback={<ModuleFallback title="筛选器" />}
        tags={{ module: 'filter-panel' }}
      >
        <FilterPanel />
      </ErrorBoundary>
    </div>
  )
}

// 第三方图表组件可能在不同数据格式下抛异常
function SafeChart({ data, config }: ChartProps) {
  return (
    <ErrorBoundary
      fallback={<ChartUnavailable dataId={config.dataId} />}
      tags={{ component: 'third-party-chart', dataId: config.dataId }}
    >
      <ThirdPartyChart data={data} config={config} />
    </ErrorBoundary>
  )
}

// ❌ 坏做法：上报一个裸 Error 对象
function componentDidCatch(error: Error) {
  Sentry.captureException(error)
  // 在 Sentry 里只能看到一行堆栈
  // 不知道用户在哪个页面、做了什么操作、接口返回了什么
}

// ✅ 好做法：上报结构化上下文
function componentDidCatch(error: Error, info: React.ErrorInfo) {
  Sentry.withScope((scope) => {
    scope.setTag('module', this.props.tags?.module ?? 'unknown')
    scope.setTag('build', BUILD_VERSION)
    scope.setContext('react', { componentStack: info.componentStack })
    scope.setContext('route', {
      path: location.pathname,
      query: Object.fromEntries(new URLSearchParams(location.search)),
    })
    scope.setContext('environment', {
      buildVersion: BUILD_VERSION,
      env: APP_ENV,
    })
    // 面包屑已经在 Sentry.init 中通过 integrations 自动记录了
    // 包括路由变化、点击事件、fetch/XHR 请求
    Sentry.captureException(error)
  })
}

// ❌ 坏做法：所有错误一视同仁
function handleApiError(error: unknown) {
  Sentry.captureException(error)
  showToast('加载失败，请稍后重试')
  // 网络超时和数据结构异常走了同一条路
  // 超时应该静默重试，不该和用户说「请稍后」
}

// ✅ 好做法：按错误类型分别处理
function handleApiError(error: unknown) {
  if (isNetworkError(error)) {
    // 网络错误：静默重试，不打扰用户
    return retryRequest(error.config, { maxRetries: 3 })
  }
 
  if (isBusinessError(error)) {
    // 业务错误：正常路径，不需要上报
    return showEmptyState(error.code)
  }
 
  // 真异常：上报 + 降级 + 报警
  Sentry.captureException(error, {
    tags: { errorCategory: 'unexpected' },
    extra: { responseStatus: error.status, responseData: error.data },
  })
  showFallbackUI()
  notifyOnCall(error)
}

// 在关键业务节点添加面包屑
function handleOrderSubmit(orderId: string) {
  Sentry.addBreadcrumb({
    category: 'order',
    message: `提交订单: ${orderId}`,
    level: 'info',
    data: { orderId, itemCount: cart.items.length },
  })
  // ...提交逻辑
}

// ✅ 带重试的错误边界
function ErrorBoundaryWithRetry({
  children,
  fallback,
  maxRetries = 2,
  ...rest
}: ErrorBoundaryProps) {
  const [retryCount, setRetryCount] = useState(0)
 
  return (
    <ErrorBoundary
      {...rest}
      fallbackRender={({ error, resetErrorBoundary }) => {
        // 在自动重试次数内静默重试
        if (retryCount < maxRetries) {
          setTimeout(() => {
            setRetryCount((c) => c + 1)
            resetErrorBoundary()
          }, 1000 * (retryCount + 1))
          // 指数退避：1s, 2s, 3s
          return <LoadingHint retryCount={retryCount + 1} />
        }
        // 超过重试次数，展示可操作的降级 UI
        return fallback ?? (
          <FallbackCard
            error={error}
            onRetry={() => {
              setRetryCount(0)
              resetErrorBoundary()
            }}
          />
        )
      }}
    >
      {children}
    </ErrorBoundary>
  )
}

// ❌ 模式一：吞掉错误
try {
  const data = JSON.parse(response)
  return <Chart data={data} />
} catch {
  return <div>--</div>
  // 错误被静默吞掉了，页面上显示一个短横线
  // 开发不知道这里出过错，数据团队也不知道数据有异常
}

// ❌ 模式二：catch 了但不上报
async function fetchData() {
  try {
    const res = await fetch('/api/orders')
    return await res.json()
  } catch (error) {
    console.error(error)
    // console.error 在生产环境没人看
    // 错误在这里消失了
    return null
  }
}

// ❌ 模式三：错误边界里没有状态重置
class MyErrorBoundary extends React.Component {
  static getDerivedStateFromError() {
    return { hasError: true }
  }
 
  render() {
    if (this.state.hasError) {
      return <p>出错了</p>
      // 即使路由变了，hasError 仍然是 true
      // 用户导航到其他页面仍然看到降级 UI
      // 必须同时监听路由变化来重置状态
    }
    return this.props.children
  }
}

// ❌ 模式四：在事件处理函数里依赖 ErrorBoundary
function SubmitButton({ onSubmit }: { onSubmit: () => Promise<void> }) {
  const handleClick = async () => {
    await onSubmit()
    // 如果 onSubmit 内部抛异常
    // ErrorBoundary 不会捕获它——事件处理函数不在渲染阶段
  }
  return <button onClick={handleClick}>提交</button>
}
 
// ✅ 事件处理函数需要自己 try-catch
function SubmitButton({ onSubmit }: { onSubmit: () => Promise<void> }) {
  const handleClick = async () => {
    try {
      await onSubmit()
    } catch (error) {
      // 这里需要手动上报
      Sentry.captureException(error)
      showToast('提交失败')
    }
  }
  return <button onClick={handleClick}>提交</button>
}