frontend-ai-guide

AI 开发者指南 - 技术决策标准与反模式汇编（前端）

价值优先的工程实践

持续检查，直到证据表明，能够实现所需用户或维护者价值、同时确保 UI 正确且易于维护的方案，是总复杂度最低的方案。

• 在已确认的范围内解决已验证的问题，或解决实现目标所需的依赖问题；对于其他发现，说明其所属边界和相关证据，不要因此扩大当前变更范围。
• 仅当当前结果、已验证的约束或有证据支持的重大风险有此要求时，才引入状态、属性、变体、抽象或推测性的边缘情况处理。
• 如果仓库证据表明，在已确认职责范围内进行保持行为不变的维护，可以减少变更歧义、重复归属、缺陷风险，或未来的实现与验证成本，且不会扩大可观察到的产品范围，则应将其视为当前维护者价值。

评估总复杂度时，应综合考虑所有被引入的用户决策、属性、状态、变体、概念、输出、持久状态、组件或钩子路径，以及相应的 UX、运行时、实现、测试、文档和维护成本。仅比较可行方案之间存在差异的维度。若复用现有机制或不引入新机制能以更低的总复杂度实现相同的已确认价值，并且有证据支持，则优先采用。

技术反模式（危险信号模式）

发现以下模式时，应暂停受影响的决策并审查设计：

代码质量反模式

1. 在独立维护的组件中重复实现同一 UI 职责 - 审查重复行为或契约是否应由一个主体负责
2. 在单个组件中混合多项职责 - 违反单一职责原则（SRP）
3. 在多个组件中定义相同内容 - 违反 DRY 原则
4. 未检查依赖项就进行变更 - 可能产生意外影响
5. 通过注释禁用代码 - 应使用版本控制
6. 抑制错误 - 隐藏问题会积累技术债务
7. 以类型断言代替保证 - 声明某种类型已成立，但既没有检查，也没有现有契约作为依据
8. 掩盖状态归属的属性透传链 - 当中间组件仅转发值，且更广泛的状态归属方更明确时，应使用组合、Context 或项目的状态层；如果显式属性能保持本地归属，且将状态归属交给更广泛的主体会增加协调成本，同时职责仍属于本地，则应保留显式属性
9. 混合彼此独立变化的职责的组件 - 当渲染、状态/数据归属或可复用/可测试行为构成独立职责时，应拆分；如果拆分会增加可避免的属性/状态同步，则应保留职责内聚的组件

设计反模式

• “先凑合能用”思维 - 技术债务不断累积
• 拼凑式实现 - 未经规划地向现有组件中添加内容
• 对不确定技术抱有乐观态度地实现 - 在未知要素上进行设计，并假设“应该能用”
• 治标不治本 - 只在表面修复问题，未解决根本原因
• 未经规划的大规模变更 - 缺乏渐进式方法

回退设计原则

核心原则：快速失败

一种优先提升主要代码可靠性，而非实现回退方案的设计理念。

回退实现标准

• 回退规则：当已接受的需求、边界契约、项目政策或设计文档定义了降级结果和恢复责任方时，实现回退方案
• 分层职责：
  • 子组件子树渲染失败（包括渲染期间抛出异常的钩子）：使用项目的 Error Boundary
  • 事件处理器、常规异步回调、SSR，以及渲染之外的钩子/API 操作：在所属事件、钩子、API 或服务端边界中，按照其错误契约进行处理

检测过多的回退处理

• 新增与现有恢复职责重复或将其拆分的 catch 时，必须进行设计评审；如果它对应不同的故障模式，且有明确记录的恢复负责人和清晰可见的 UI 结果，则可以保留
• 同一故障在多个组件／钩子／API 层被捕获，却没有唯一的恢复负责人，或嵌套处理器掩盖了可见的 UI 状态时，必须进行设计评审
• 在实现回退处理之前，先明确已接受的恢复约定
• 在负责诊断或恢复的边界处，通过一个现有的 UI、日志或指标渠道，让回退处理的触发情况可观测；仅当运维要求或项目政策要求时，才新增渠道

代码重复的判定标准

如果具体实现之间的相似性只是偶然，或其 UI 归属不同，就应保持分离。如果仓库证据表明它们共享交互、验证规则、视觉约定或协同变更职责，则应进行整合。

整合标准

适合整合的情况

• 业务逻辑重复
• 复杂的处理算法
• 组件模式（表单字段、卡片等）
• 自定义钩子
• 验证规则

应避免整合的情况

• 偶然相同（代码碰巧一致）
• 未来可能朝不同方向演进
• 整合会显著降低可读性
• 测试代码中的简单辅助函数

常见失败模式及规避方法

模式 1：错误修复链

症状：修复一个错误后又出现新错误
原因：未理解根本原因，只进行表面修复
规避方法：修复前使用 5 Whys 找出根本原因

模式 2：绕过类型保证

症状：使用 any 或 as 声明类型，但没有任何检查或约定能够保证该类型
原因：一时想避开类型错误
规避方法：在保证成立的边界处，通过检查或现有约定来支持所声明的类型

模式 3：测试不充分就进行实现

症状：实现后出现许多缺陷
原因：忽略 Red-Green-Refactor 流程
规避方法：为新行为、变更后的行为以及可复现的缺陷修复编写失败测试，再开始实现。对于保持行为不变的重构，在变更前后确认现有测试或特征测试均通过

模式 4：忽视技术上的不确定性

症状：引入新技术时频繁出现意外错误
原因：未经事先调查，就假定“按照官方文档应该能正常工作”
规避方法：

• 在确定性会影响实现或验证决策的地方记录确定程度

  Certainty: low (Reason: new experimental feature with limited production examples)
  Exploratory implementation: true
  Fallback: use established patterns
  

• 对于确定性较低的情况，先编写最小化验证代码

模式 5：对现有代码调查不足

症状：实现重复、架构不一致、集成失败
原因：实现前对现有代码了解不足
规避方法：

• 实现前，务必搜索相似功能（使用领域、职责、组件模式作为关键词）
• 找到相似功能 → 验证其属性、生命周期、设计系统中的角色及仓库中的用法是否具有代表性；兼容时复用或扩展，否则记录其为何不适合作为参考
• 相似功能属于技术债务 → 如果它阻碍当前目标、由当前变更导致，或属于已确认的范围，则进行修复；否则单独报告。如果修复需要架构决策，则创建 ADR
• 不存在相似功能 → 遵循现有设计理念实现新功能
• 在适用的实现记录或设计记录中，保留每项复用、扩展、分离或修复决策的依据

质量检查工作流

查明仓库配置的质量检查入口及其覆盖的类别。使用仓库声明的包管理工具和约定，并将以下类别作为适用的证据检查清单。

适用的检查类别

• Lint/格式 — 项目配置的格式化工具和 linter
• 类型检查 — 项目配置的类型验证
• 构建 — 配置的生产环境或软件包构建
• 行为检查 — 能验证变更行为的最小配置测试；当变更涉及集成或 E2E 测试边界、生成的脚手架要求运行这些测试，或仓库门禁包含这些测试时，也要运行集成或 E2E 测试套件

如果仓库声明了命令组合或执行顺序，请遵循；否则，选择符合命令依赖关系且能提供有效反馈的顺序。所有适用的已配置检查都通过后，才算完成。

故障排查

• 端口已被占用 — 停止占用该端口的过期开发／预览／测试进程
• 缓存过期 — 使用项目的清理／重置缓存选项重新运行
• 依赖项错误 — 清理并重新安装依赖项

需要进行技术决策的情况

抽象的时机

• 仓库证据表明存在共享的 UI 职责和协同变更模式后，再提取共享抽象
• 注意 YAGNI，只实现当前需要的功能
• 当前的简洁性优先于未来的可扩展性

性能与可读性

• 除非项目的性能预算或 React DevTools Profiler 对比表明受影响的交互存在明显瓶颈，否则优先考虑可读性
• 优化前使用 React DevTools Profiler 进行测量
• 优化时通过注释说明原因

组件／类型定义的粒度

• 过于细分的组件／类型会降低可维护性
• 设计能恰当表达 UI 模式的组件
• 优先使用组合，而不是继承

确保实现完整

按风险程度执行影响分析

完成标准：完成全部 3 个阶段。对于不涉及共享契约、路由、状态所有权或构建／配置影响的独立组件变更，简洁的搜索／检查记录即可；对于跨组件或高风险变更，使用结构化报告。

1. 发现

在仓库中搜索对变更组件或 hook、其导入函数以及 Props／State 类型的所有引用。

2. 理解

阅读必要的已发现文件，以确定：

• 调用方的目的和上下文
• 组件层级
• 数据流：Props → State → 事件处理程序 → 回调

3. 识别

对于跨组件或高风险变更，生成结构化影响报告：

## Impact Analysis
### Direct Impact: ComponentA, ComponentB (with reasons)
### Indirect Impact: FeatureX, PageY (with integration paths)
### Processing Flow: Props → Render → Events → Callbacks

确定已接受的范围、使用方、状态流、所需的相邻变更及适用的检查后，再继续。

未使用代码删除规则

如果请求的变更导致某个组件、hook、工具、文档或配置条目不再需要，应在检查其使用方以及生成或运行时用途后将其删除。对于不确定或超出范围的清理，予以保留并报告；与实现无关的闲置代码应留在范围之外。

现有代码删除决策流程

Required by the requested change? No → Preserve unless the change proves it obsolete
                               Yes → Working and compatible? Yes → Fix/extend
                                                             No → Repair or replace with migration/rollback evidence