1k-error-handling

错误处理

OneKey 代码库的错误处理最佳实践。

核心原则

• 对可能失败的异步操作使用 try/catch 代码块
• 提供适当的错误消息和回退方案
• 对需要加载状态和错误状态的操作使用 useAsyncCall hook
• 切勿静默吞掉错误

快速参考

基本的 Try/Catch

async function fetchData() {
  try {
    const result = await apiCall();
    return result;
  } catch (error) {
    console.error('Failed to fetch data:', error);
    throw error; // Re-throw if caller needs to handle
  }
}

使用回退值

async function fetchDataWithFallback() {
  try {
    const result = await apiCall();
    return result;
  } catch (error) {
    console.error('Failed to fetch, using fallback:', error);
    return defaultValue; // Return fallback instead of throwing
  }
}

使用 useAsyncCall Hook

import { useAsyncCall } from '@onekeyhq/kit/src/hooks/useAsyncCall';

function MyComponent() {
  const { run, isLoading, error, result } = useAsyncCall(
    async () => {
      return await fetchData();
    },
    {
      onError: (e) => {
        Toast.error({ title: 'Failed to load data' });
      },
    }
  );

  if (error) {
    return <ErrorView error={error} onRetry={run} />;
  }

  return <DataView data={result} loading={isLoading} />;
}

面向用户的错误

async function submitForm(data: FormData) {
  try {
    await api.submit(data);
    Toast.success({ title: 'Submitted successfully' });
  } catch (error) {
    // Show user-friendly message
    Toast.error({
      title: 'Submission failed',
      message: getUserFriendlyMessage(error),
    });
    // Log detailed error for debugging
    console.error('Form submission error:', error);
  }
}

反模式

静默吞掉错误

// ❌ BAD: Error silently ignored
async function badExample() {
  try {
    await riskyOperation();
  } catch (error) {
    // Nothing here - error lost forever
  }
}

// ✅ GOOD: At minimum, log the error
async function goodExample() {
  try {
    await riskyOperation();
  } catch (error) {
    console.error('Operation failed:', error);
    // Handle appropriately
  }
}

UI 中缺少错误状态

// ❌ BAD: No error state
function BadComponent() {
  const { data } = useQuery();
  return <View>{data}</View>; // What if data fetch fails?
}

// ✅ GOOD: Handle all states
function GoodComponent() {
  const { data, isLoading, error } = useQuery();

  if (isLoading) return <Loading />;
  if (error) return <Error error={error} />;
  return <View>{data}</View>;
}

详细指南

如需了解全面的错误处理模式和示例，请参阅 error-handling.md。

涵盖的主题：

• 核心原则
• 错误处理模式（try/catch、回退方案、hook）
• React 错误边界
• 错误类型（网络、验证、面向用户）
• 应避免的反模式
• 错误处理检查清单

检查清单

• 所有异步操作都使用 try/catch 包裹
• 记录错误以便调试
• 向用户显示友好的消息
• 在 UI 中处理加载状态和错误状态
• 不静默吞掉错误
• 在适当情况下捕获特定错误类型

相关技能

• /1k-coding-patterns - 通用编码模式和 Promise 处理
• /1k-sentry-analysis - Sentry 错误分析与修复