错误处理门 error-handling-gate

---

名称: 错误处理门 描述: 验证错误处理，包括空catch检测、用户友好消息和日志记录。在 /own:done 流程中触发的警告门。

门 3: 错误处理审查

“愉快路径的代码很容易。错误处理是高级工程师发光的地方。”

目的

这个门确保代码优雅地处理失败，为用户提供有意义的反馈，并且不默默地吞掉错误。

门状态

• 通过 — 错误处理适当
• 警告 — 发现了需要解决的问题

---

门问题

问题 1: 失败场景

“如果[主要操作]失败会发生什么？带我走一遍用户体验。”

寻找:

• 对失败模式的意识
• 用户友好的错误消息
• 恢复选项（重试，回退）
• 无沉默失败

示例场景:

• 网络请求失败
• 数据库宕机
• 验证失败
• 第三方API错误

问题 2: 用户反馈

“当错误发生时用户会看到什么？他们会理解下一步该怎么做吗？”

寻找:

• 有帮助的、非技术性的消息
• 可操作的指导（“再试一次”，“检查您的连接”）
• UI中适当的错误放置

问题 3: 错误可见性

“如果在生产中出现问题，您将如何调试？”

寻找:

• 错误被记录
• 日志中有足够的上下文
• 日志中没有敏感数据
• 错误跟踪意识（Sentry等）

---

错误处理检查清单

异步操作

• [ ] 所有异步调用都包装在try/catch或.catch()中
• [ ] 没有空的catch块
• [ ] 错误包括上下文（什么操作，什么数据）
• [ ] finally块用于清理（加载状态等）

用户体验

• [ ] 用户友好的错误消息（无技术术语）
• [ ] 错误是可操作的（用户可以做什么？）
• [ ] 错误时清除加载状态
• [ ] 适当的地方有重试选项

日志记录与调试

• [ ] 带有上下文的错误日志记录
• [ ] 错误日志中没有敏感数据
• [ ] 错误类型/代码用于分类
• [ ] 开发中可用的堆栈跟踪

边缘情况

• [ ] 空状态处理
• [ ] 超时处理
• [ ] 部分失败处理（一些项目成功，一些失败）
• [ ] 并发请求处理

---

响应模板

如果通过

✅ 错误处理门: 通过

错误处理看起来很牢固:
- 异步操作正确包装
- 用户友好的错误消息
- 错误记录用于调试

转到下一个门...

如果警告

⚠️ 错误处理门: 警告

发现了 [X] 个错误处理问题:

**问题 1: [空catch块 / 缺少错误处理]**
位置: `file.ts:42`
问题: "当这个默默地失败时会发生什么？"

**问题 2: [向用户显示技术错误]**
位置: `file.ts:88`
问题: "用户会理解'TypeError: Cannot read property...'吗？"

**问题 3: [没有加载状态清理]**
位置: `file.ts:100`
问题: "如果这个失败，加载指示器会怎样？"

这些应该被解决以确保良好的用户体验。

---

常见问题检查

1. 空Catch块

❌ try {
     await submitForm();
   } catch (error) {
     // 沉默失败 - 用户不知道
   }

✅ try {
     await submitForm();
   } catch (error) {
     console.error('表单提交失败:', error);
     setError('无法提交。请重试。');
   }

2. 缺少Finally块进行清理

❌ try {
     setLoading(true);
     await fetchData();
     setLoading(false);
   } catch (error) {
     handleError(error);
     // 加载状态永远保持为真！
   }

✅ try {
     setLoading(true);
     await fetchData();
   } catch (error) {
     handleError(error);
   } finally {
     setLoading(false);
   }

3. 技术错误暴露

❌ catch (error) {
     setError(error.message);
     // 用户看到: "TypeError: Cannot read property 'map' of undefined"
   }

✅ catch (error) {
     console.error('加载失败:', error);
     setError('出错了。请重试。');
   }

4. 无错误区分

❌ catch (error) {
     setError('错误');
   }

✅ catch (error) {
     if (error.status === 401) {
       setError('请登录以继续。');
       redirectToLogin();
     } else if (error.status === 404) {
       setError('未找到项目。');
     } else if (error.name === 'NetworkError') {
       setError('检查您的互联网连接。');
     } else {
       setError('出错了。请重试。');
     }
   }

---

苏格拉底式错误问题

不要直接指出修复，而是问:

1. “如果用户点击这个时网络断了会发生什么？”
2. “如果这个catch块运行，用户会看到什么？”
3. “您将如何在生产中知道这个失败了？”
4. “如果只有一些项目保存失败怎么办？”
5. “如果发生错误，加载指示器会被卡住吗？”

---

错误消息质量检查

糟糕的消息	更好的消息
“错误”	“无法保存。请重试。”
“发生错误”	“无法加载您的个人资料。检查您的连接。”
“TypeError: undefined”	“出错了。请刷新并重试。”
“500 Internal Server Error”	“我们的服务器遇到问题。请稍后再试。”
“失败”	“无法完成您的请求。需要帮助？联系支持。”

---

严重性指南

问题	严重性	影响
空catch块	高	沉默失败，难以调试
无加载状态清理	中	UI卡住，用户体验差
向用户显示技术错误	中	用户体验困惑，可能信息泄露
无重试选项	低	轻微的用户体验摩擦
通用错误消息	低	帮助较少但未破坏