Coding Standards

通用编码标准

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

检测到以下任一模式时，暂停实现并记录：触发的模式、受影响的当前需求、最小的合规替代方案，以及恢复所需的验证。当替代方案消除该模式或有文档记录的需求证明保留该模式合理时，方可恢复。

代码质量反模式

1. 相似代码编写 3 次或以上 —— 违反三次法则（Rule of Three）
2. 单个文件中混杂多种职责 —— 违反单一职责原则（SRP）
3. 在多个文件中定义相同内容 —— 违反 DRY 原则
4. 未检查依赖关系就进行修改 —— 存在意外影响的可能性
5. 用注释禁用代码 —— 应使用版本控制
6. 错误抑制 —— 隐藏问题会形成技术债
7. 用类型断言替代保证 —— 声明了既无运行时检查也无既有契约作为依据的类型

设计反模式

• “暂时能用就行”的思维 —— 技术债的累积
• 补丁式实现 —— 对现有代码进行无计划的追加
• 对不确定技术的乐观实现 —— 假设未知要素“大概能行”就进行设计
• 对症式修复 —— 不解决根本原因的表面修复
• 无计划的大规模变更 —— 缺乏渐进式方法

基本原则

持续排查，直到依据能够确定在保持系统正确性和可维护性的前提下，以最低总复杂度交付所需的用户、运维或维护者价值的方案。

• 基于依据的重构范围 —— 只重构阻碍当前结果、被当前任务变更、或未通过适用质量检查的代码；使用保持行为不变的小步骤。对其他发现，连同其所属边界和依据一并报告，而不扩大当前变更范围
• 仅限当前需求的代码 —— 只有当当前需求、已验证的约束、或有依据支持的实质性风险要求时，才引入新的代码路径、能力、基础设施、抽象或推测性的边缘情况处理（YAGNI）
• 设计收敛 —— 以最小的设计增量交付当前所需的结果。在引入持久状态、公共或跨边界契约、行为模式、可复用抽象或组件拆分之前，先记录现有能力已经交付了什么、它们在当前结果上未能交付什么，以及为什么该新增是能弥合这一差距的最小方案

对每个被激活的层面综合评估总复杂度：用户决策、设置、模式、概念、输出、持久状态和实现路径，以及它们各自在 UX、运行时、实现、测试、文档和维护方面的成本。只比较各可行方案之间存在差异的维度。当能以更低的总复杂度交付相同的已确认价值和验证结果时，优先选择复用或不引入新机制。

注释编写规则

• 代码优先：命名、类型和结构是主要的表达媒介；只有在注释能传达代码无法表达的信息时才添加注释。犹豫不决时，改进命名而不是加注释
• 注释“为什么”，而非“是什么”：解释推理过程、权衡取舍、约束/边缘情况，或公共 API 契约
• 内容不过时：注释包含当前的推理、约束、边缘情况或 API 契约；开发历史由版本控制保留
• 长期有效：只写在任何阅读时刻都依然有效的内容
• 简洁性：将说明控制在必要的最低限度

错误处理基础

快速失败原则

在出错时快速失败，防止在无效状态下继续处理。传播该失败，或返回带有原始诊断上下文的显式类型化错误。

关于详细实现方法（Result 类型、自定义错误类、分层错误处理等），请参考特定语言和框架的规则。

三次法则 —— 代码重复的判断标准

根据 Martin Fowler《重构》一书处理重复代码的方式：

提取公共实现的判断标准

适合提取公共实现的情况

• 业务逻辑重复
• 复杂的处理算法
• 很可能需要批量修改的部分
• 校验规则

应保持分离的情况

• 偶然一致（碰巧代码相同）
• 有可能朝不同方向演化
• 提取公共实现会显著降低可读性
• 测试代码中的简单辅助函数

变更边界与参考代表性

提示中给出的路径是调查的起点。当有依据表明仓库中的其他文件实现了被接受的结果、是必需的依赖或调用路径、或必须变更以维持受本次工作影响的契约时，将其纳入范围。调用方、使用方、测试、配置和数据流是有用的依据，而非必须逐项核查的清单。

在采用某种模式、API 或依赖时，检查具有相同职责和当前契约的相关功能及仓库中的其他使用之处。在该职责范围内优先选择兼容的实现。出现频率有助于定位候选方案，但并不能使某个模式因此具有权威性；当多种方案并存时，通过其调用方、生命周期和兼容性来区分当前模式与遗留或无关的模式。

从清单文件、锁文件和兼容的使用方中解析外部依赖版本。仅当这些来源无法解决影响兼容性或架构的选择时才上报处理。

常见失败模式及规避方法

模式 1：错误修复连锁反应

症状：修复一个错误导致产生新的错误 原因：未理解根本原因就进行表面修复 规避方法：修复前用五个为什么（5 Whys）找出根本原因

模式 2：绕过类型保证

症状：用 any 或 as 声明了没有任何检查或契约作为依据的类型 原因：想要规避类型错误的冲动 规避方法：应用“类型安全基础”中关于依据的判断标准。

模式 3：测试不充分的实现

症状：实现后出现大量 bug 原因：忽视 Red-Green-Refactor 流程 规避方法：以能够展示所需结果的失败测试开始行为变更

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

症状：引入新技术时频繁出现意外错误 原因：未事先调查，假设“照官方文档应该能行” 规避方法：

• 在任务文件开头记录确定性评估
• 当仓库依据、与版本匹配的一手资料，或可运行的本地检查都无法确认与结果相关的行为时，将确定性视为低；在实现前先创建能解决该行为问题的最小验证

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

症状：重复实现、架构不一致、集成失败、采用过时模式 原因：实现前对现有代码理解不足；仅参考附近文件而未核实其代表性 规避方法：

• 实现前，使用领域、职责和配置模式相关的关键词搜索类似功能
• 发现类似功能 -> 当该实现满足当前契约时，复用或扩展它
• 类似功能属于技术债 -> 当它阻碍当前结果、由当前变更引起、或位于已确认范围内时予以修复；否则单独报告。当修复需要架构决策时创建 ADR
• 不存在类似功能 -> 按照现有设计理念实现新功能
• 将每个决策及其理由记录在当前工作流为其指定的产物中
• 参考代表性核查：参见上文“变更边界与参考代表性”一节

调试技巧

五个为什么 —— 根本原因分析

将每个回答追溯到已观察到的依据，直至找到一个修正后能防止原始故障的原因。记录每个问题、依据以及最终的因果链；当下一个回答将只是推测时停止，并指出还需要哪些依据。

类型安全基础

类型安全原则：类型收窄应以运行时检查或既有契约为依据。类型守卫保证的类型应与实际检查内容一致。

• 对结构尚未确定的输入使用 unknown，并验证使用方需要的属性。
• 使用泛型、联合类型或交叉类型表达类型关系及变体。
• 将基于已验证的 SDK 或框架契约的类型断言放在对应边界。当静态分析无法表达该契约时，将抑制限定于相关规则，并说明契约依据和断言的适用范围。

类型复杂度管理

• 字段数量：最多 20 个（超过则按职责拆分，外部 API 类型除外）
• 可选字段比例：最多 30%（超过则将必填/可选分离）
• 嵌套深度：最多 3 层（超过则扁平化）
• 外部 API 类型：放宽约束，按实际情况定义（在内部适当转换）

重构技巧

基本方针

• 小步前进：每次保持行为不变的重构后，确保最相关的适用测试和静态检查仍然通过
• 安全变更：一次只改变一个重构职责，并在进行下一个职责之前验证其可观测行为
• 行为保证：确保现有行为在过程中保持不变

实现流程：理解现状 -> 渐进式修改 -> 行为验证 -> 最终确认

优先级：删除重复代码 > 拆分大函数 > 简化复杂条件分支 > 提升类型安全

实现完整性保证

影响追踪

开始实现前，追踪所变更代码的调用方、依赖以及数据流（生成 -> 修改 -> 引用），直到再多一个文件也无法改变“变更边界与参考代表性”所界定的变更边界为止。将实现或其验证所依赖的直接与间接影响带入后续工作。

未使用代码的删除规则

检测到未使用的代码时，在任务完成前根据当前需求和可达的调用路径判断它是否被使用。

• 是 -> 将其接入该调用路径并验证需求
• 否 -> 删除它；版本控制会保留之前的实现

对象：代码、文档、配置文件

Red-Green-Refactor 流程（测试先行开发）

推荐原则：以因预期原因而失败的测试开始行为变更

开发步骤：

1. Red：为预期行为编写测试（测试失败）
2. Green：以最小实现使测试通过
3. Refactor：在保持测试通过的同时改进代码

可直接验证的情况：

• 纯配置文件变更（.env、config 等）
• 仅文档更新（README、注释等）
• 生产环境紧急事故响应（事后必须补充测试）

测试设计原则

测试用例结构

• 测试由“Arrange（准备）”“Act（执行）”“Assert（断言）”三个阶段组成
• 测试名称应说明触发条件和可观测结果
• 一个测试用例只验证一种行为

测试数据管理

• 在专用目录中管理测试数据
• 定义测试专用的环境变量值
• 对测试中的凭据、令牌、个人数据和支付数据，使用合成的、非敏感的值
• 保持测试数据最小化，只使用与测试用例验证目的直接相关的数据

Mock 与 Stub 使用策略

推荐：在单元测试中对外部依赖进行 mock

• 优点：确保测试的独立性和可复现性
• 实践：对数据库、API、文件系统等外部依赖进行 mock

单元测试边界：对外部连接使用确定性的替代品；在为该契约选定的集成测试或 E2E 测试中，实际调用真实的外部边界

测试失败应对的判断标准

修正测试：预期值错误、引用了不存在的功能、依赖于实现细节、仅为测试而存在的实现 修正实现：合理的规格、业务逻辑、重要的边缘情况 两种解读在现有需求下都说得通：返回未解决的行为决策 —— 说明两种候选行为、能够裁定哪一种正确的来源，以及在不做选择之前应停止的条件

测试粒度原则

核心原则：只验证可观测行为

通过可观测边界进行测试：公共 API、返回值、异常、外部调用和持久化状态。只能通过这些可观测边界间接触及私有方法、内部状态和算法细节。

安全原则

安全默认值

• 通过环境变量或专用的密钥管理器存储凭据和密钥
• 对所有数据库访问使用参数化查询（预处理语句）
• 使用语言或框架提供的成熟加密库
• 使用密码学安全的随机数生成器生成安全关键值（令牌、ID、nonce）
• 使用标准协议对静态和传输中的敏感数据进行加密

输入与输出边界

• 在系统入口处校验所有外部输入的预期格式、类型和长度
• 根据渲染上下文（HTML、SQL、shell、URL）对输出进行适当编码
• 错误响应中只返回调用方所需的信息；详细诊断信息记录在服务器端日志中

访问控制

• 对所有处理用户数据或触发状态变更的入口点应用身份验证
• 对每次资源访问都进行授权校验，而不仅仅在入口处
• 只授予操作所需的最小权限（文件、数据库连接、API 作用域）

知识截止日期补充（2026-03）

• OWASP Top 10:2025 已从关注症状转向关注根本原因；新增了“软件供应链失效”（A03）和“异常情况处理不当”（A10）
• 最新研究表明，AI 生成的代码在访问控制方面存在缺陷的比例较高 —— 应将身份验证和授权列为高优先级评审对象
• OpenSSF 发布了《面向 AI 代码助手指令的安全导向指南》—— 建议使用针对特定语言的可执行约束，而非泛泛而谈的建议
• 详细的检测模式请参见 references/security-checks.md