错误处理与容错机制：GeoAI-UP的降级策略设计

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

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

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

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

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

现实情况是：

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

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

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

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

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

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

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

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

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

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

……

为什么要这么分类？

好处有三个：

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
};
}

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

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

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

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里。

这样做的好处是：

五、容错设计的度量

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

六、总结

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

核心理念：

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

三个关键实践：

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