今天通过GeoAI-UP系统：聊一个非常重要但经常被忽视的话题——错误处理与容错机制。

做系统开发的人都明白，再完美的代码也会遇到各种意外情况。网络抖动、数据库超时、外部服务不可用……这些"黑天鹅"事件随时可能发生。

如何让系统在面对这些错误时依然保持可用，而不是直接崩溃？这就是容错设计的价值所在。

一、为什么容错比防错更重要？

很多人以为，只要代码写得足够好，就不会有bug，系统就不会出错。这话没错，但只对了一半。

现实情况是：

• 网络会断
• 硬盘会满
• 第三方API会限流
• 服务器会OOM

这些都不是代码问题，而是基础设施和外部环境的问题。你没办法控制这些，但你可以控制系统的反应。

容错设计的核心理念：不是"不犯错"，而是"犯错后优雅地降级"。

就像汽车的安全气囊，不是为了防止事故，而是为了在事故发生时保护乘客。

二、GeoAI-UP的容错策略全景

我们设计了一套分层降级的容错体系，核心思想是：

永远不要让用户看到"系统错误"，而是让他们看到"友好提示"

1. 第一层：错误分类与代码设计

系统定义了清晰的错误类型体系，每种错误都有明确的含义和处理方式：

Error
├── DataSourceError（数据源错误）
│   ├── ConnectionError（连接失败）
│   └── ValidationError（数据校验失败）
├── PublishingError（发布服务错误）
│   ├── ValidationError（参数校验）
│   └── NotFoundError（资源不存在）
├── SummaryError（摘要生成错误）
│   ├── TemplateLoadError（模板加载失败）
│   ├── LLMGenerationError（LLM调用失败）
│   └── StreamingError（流式传输中断）
└── ExecutorError（执行器错误）
    ├── TaskNotFoundError（任务不存在）
    ├── OperatorNotFoundError（操作符不存在）
    └── ExecutionFailedError（执行失败）

......

为什么要这么分类？

好处有三个：

1. 便于定位问题：看到错误类型就知道大概在哪个环节出问题
2. 便于处理错误：不同类型的错误需要不同的处理策略
3. 便于日志分析：生产环境的错误统计是优化的依据

2. 第二层：智能降级策略

这是GeoAI-UP容错设计的精髓。我们采用了链式降级的策略：

最佳方案 → 降级方案 → 更简单的降级方案 → 最终兜底方案

实例一：意图分类的降级

当用户输入一句话时，系统需要判断这是"空间分析"还是"知识查询"还是"闲聊"。

// 尝试用LLM进行语义分类
const llmResult = await this.llmBasedClassification(userInput, state);

// 如果LLM调用失败，降到规则匹配
if (llmResult.confidence < 0.6) {
  return this.ruleBasedClassification(userInput);
}

// 如果规则也匹配不了，默认按GIS分析处理
return {
  type: 'GIS_ANALYSIS',
  confidence: 0.5,
  reasoning: 'Classification failed, defaulting to GIS_ANALYSIS'
};

设计原理：

• LLM分类最准确，但可能因为API超时等原因失败
• 规则匹配稍逊，但稳定可靠
• 默认值是最保守的选择，保证系统不会"不知所措"

实例二：摘要生成的降级链

当分析任务完成后，需要给用户生成一份结果摘要。

async generate(state: GeoAIStateType): Promise<string> {
  // 第一选择：LLM生成的自然语言摘要
  if (this.llmSummarizer) {
    try {
      return await this.llmSummarizer.generateWithLLM(state, language);
    } catch (e) {
      // LLM失败，降到模板渲染
    }
  }
  
  // 第二选择：模板渲染
  try {
    return await templateRenderer.generateFromTemplate(state);
  } catch (e) {
    // 模板也失败，降到兜底方案
  }
  
  // 最终兜底：纯数据汇总
  return fallbackRenderer.generateFallback(state);
}

降级链的设计哲学：

• 每一层都比上一层"傻"，但也更稳定
• 用户体验逐级下降，但至少能看到结果
• 不会出现"加载中…"然后就没然后的情况

3. 第三层：Fallback渲染器

FallbackRenderer是整个降级体系的最后一道防线。它的任务很简单：不管发生什么，都要给用户一个能看的结果。

generateFallback(state: GeoAIStateType): string {
  let summary = '';
  
  // 标题总是有的
  summary += '## Analysis Complete\n\n';
  
  // 统计执行结果
  if (state.executionResults) {
    const results = Array.from(state.executionResults.values());
    const successCount = results.filter(r => r.status === 'success').length;
    const failCount = results.filter(r => r.status === 'failed').length;
    
    summary += `### Execution Results\n\n`;
    summary += `- Successful: ${successCount}\n`;
    summary += `- Failed: ${failCount}\n`;
  }
  
  // 列出失败的操作和原因
  if (failCount > 0) {
    summary += '**Failed Operations:**\n\n';
    results.filter(r => r.status === 'failed').forEach(result => {
      summary += `- ${result.operatorName}: ${result.error}\n`;
    });
  }
  
  // 列出系统警告
  if (state.errors && state.errors.length > 0) {
    summary += `### Warnings\n\n`;
    state.errors.forEach(err => {
      summary += `- **${err.goalId}**: ${err.error}\n`;
    });
  }
  
  return summary;
}

Fallback的核心原则：

• 永远返回结果：不管有没有出错，都返回一个格式化的摘要
• 保留关键信息：失败原因、警告信息都展示给用户
• 不抛异常：任何内部错误都被catch住，转化为友好输出

三、容错设计的三条黄金法则

经过几年的实践，我总结出三条黄金法则：

法则一：快速失败，优雅降级

不要让错误传播太久，发现问题就立即处理。

try {
  const result = await riskyOperation();
  return result;
} catch (error) {
  // 立即降级，不要让错误继续传播
  return fallbackResult;
}

反例：把catch写成空的，让错误悄悄溜走，最后用户看到莫名其妙的空白页面。

法则二：降级要可观测

每次降级都要记录日志，方便后续优化。

try {
  return await primaryMethod();
} catch (error) {
  console.warn('[Service] Primary method failed, falling back:', error.message);
  
  try {
    return await fallbackMethod();
  } catch (fallbackError) {
    console.error('[Service] Fallback also failed:', fallbackError.message);
    // 记录详细错误，用于后续分析
    metrics.record('service.fallback.failed', { service: 'xxx' });
  }
}

法则三：兜底方案要简单

Fallback代码一定要简单，越简单越不容易出错。

// ❌ 不好：兜底方案太复杂，可能也会失败
async fallback() {
  const data = await fetchFromBackup();
  const processed = transformData(data);
  const formatted = formatOutput(processed);
  return formatted;
}

// ✅ 好：兜底方案只做最核心的事情
async fallback() {
  // 直接返回原始数据，最简单的兜底
  return {
    status: 'partial',
    message: '部分结果可用',
    data: state.executionResults
  };
}

四、实战：任务拆分的容错

让我用一个具体的例子来说明容错设计的实际应用。

当用户说"帮我分析一下北京市的人口分布和房价关系"时，系统需要：

1. 理解用户意图
2. 拆分成多个子任务
3. 并行执行子任务
4. 汇总结果

async execute(state: GeoAIStateType): Promise<Partial<GeoAIStateType>> {
  try {
    // 尝试用LLM进行任务拆分
    const goals = await this.llmBasedGoalSplitting(state.userInput);
    return { goals };
    
  } catch (error) {
    // LLM拆分失败，不要让整个流程挂掉
    console.error('[Goal Splitter] LLM splitting failed:', error);
    
    // 创建单个兜底任务
    const fallbackGoal: AnalysisGoal = {
      id: `goal_${Date.now()}`,
      description: state.userInput,  // 直接用用户的原始输入
      priority: 5
    };
    
    // 返回一个包含错误的state，而不是抛出异常
    return {
      goals: [fallbackGoal],
      errors: [
        ...(state.errors || []),
        {
          goalId: 'goal_splitter',
          error: error.message
        }
      ]
    };
  }
}

这里有个关键的设计点：不抛异常，而是把错误信息记录到state里。

这样做的好处是：

1. 后续的Summary Generator可以把这个错误展示给用户
2. 监控系统可以统计这个错误的频率
3. 用户看到的是"部分结果"，而不是"系统崩溃"

五、容错设计的度量

容错做得好不好，需要量化评估。我们关注几个关键指标：

指标	含义	目标值
P99延迟	99%请求的响应时间	< 3s
降级率	发生降级的请求比例	< 5%
兜底触发率	触发最终兜底的比例	< 1%
错误恢复时间	从错误到恢复的时间	< 30s

六、总结

容错设计不是防御性的"凑合"，而是积极的用户体验优化。

核心理念：

• 系统可能出错，但用户不应该看到错误
• 降级要有清晰的层次，每层都比上层更稳定
• Fallback要简单，越简单越可靠
• 所有降级都要可观测，方便后续优化

三个关键实践：

1. 链式降级：Best → Better → Good → OK，每层都有用
2. 错误累积：错误信息不是扔掉，而是累积起来展示给用户
3. 永不崩溃：任何情况下都要给用户一个能看的结果

好的容错设计，就像一位经验丰富的老中医——不是什么病都能治好，但总能让病人感觉好一点。

---