structure-review

结构审查

审查代码时，请思考两个问题：每一处结构现在是否物有所值？是否缺少能让代码更易于导航和理解的结构？

过度结构化（臆想式抽象、过早泛型化）会掩盖实际流程，从而造成问题。结构不足（目录扁平、职责混杂、所有内容都放在一个文件或同一层级）则会迫使读者浏览无关代码，才能找到所需内容。

工作流

1. 以真实代码为评审依据。

• 阅读变更文件、相邻接口以及受影响的测试或文档。
• 区分以下情况：
  • 服务于当前行为的必要结构
  • 现在就能发挥作用、提升可读性的结构
  • 主要为假设中的未来用途而添加的推测性或低价值结构
• 完成标准：已阅读每个变更文件，并将其归入上述某一类别。

1. 查找结构过度的信号。

• 额外的数据库列、JSON 字段、DTO 属性、配置键或钩子，而当前行为几乎用不到。
• 增加额外跳转、却未改善命名、复用性、不变量或边界的辅助函数或包装器。
• 调用方仍需了解抽象声称要隐藏的内部细节。
• 看不到具体第二种用途的扩展点、策略对象、插件钩子或标志。
• 纯粹为了保留通用性而存在的映射对象或转换层。
• 围绕一个目前只有单一具体路径的概念，设置多层间接层。
• 选项、枚举或模式开关在实践中只有一种有效情况。
• 在具体消费者、生产者或不变量需要之前，就添加状态或持久化。
• 模块拆分或目录嵌套增加了查找成本，而非提升了理解度。
• 当前功能因设计针对假设中的后续工作进行优化而变得更难理解。

完成标准：已根据每项信号检查每个变更文件和目录。

1. 查找结构不足的信号。

• 某目录包含 10 个以上文件，涉及三种或更多互不相关的职责，却没有子目录分组。
• 模块的公共接口混合了多种能力，调用方必须在脑中筛选才能找到所需能力。
• 总是一起变更的文件在目录树中相距甚远，而无关文件却彼此相邻。
• 文件系统树无法体现项目的主要职责；新读者无法预判该去哪里查找。
• 单层目录可以拆分为两个或三个各自职责明确的子目录。
• 编码 Agent 往往倾向于采用扁平布局；应将扁平结构视为值得调查的异味，而非自动认定为正确。

完成标准：已根据每项信号检查每个变更文件和目录。

1. 检查结构是否物有所值。 思考额外的一层现在带来了什么：

• 更清晰的名称或调用点
• 更明确的类型边界
• 更清晰的所有权边界
• 减少重复的分支逻辑或胶合代码
• 更简单的不变量
• 隔离外部依赖中不理想的细节
• 更容易理解文件或目录层级的职责

如果收益有限或仅属假设，就将其视为可简化项。

1. 提高变更门槛。

• 不要仅因为某项内容是抽象的就建议删除。
• 不要仅因为目录文件多就建议嵌套。
• 不要因为代码明确就苛责它。
• 不要把提升可读性的结构视为浪费。
• 只有当额外结构带来持续的维护成本、掩盖真实流程，或主要为代码当前并不需要的未来用途而存在时，才建议简化。
• 只有当扁平布局迫使读者经常查阅无关代码，或职责混杂导致职责归属确实令人困惑时，才建议重组。

保留现有结构的迹象：

• 单次使用的辅助函数显著改善了签名、命名或调用点的可读性。
• 小型对象或组合值将相关数据归在一起，让不变量更容易看清。
• 嵌套模块或目录有助于读者预判职责所在。
• 包装器将不便处理的依赖细节或副作用隔离在更清晰的边界之后。
• 少量重复比共享抽象更省事，但当前结构在局部仍然清晰。
• 扁平目录中的文件不多，且每个文件名都能清楚表明其用途；新增子目录只会增加点击次数。

输出

报告时使用以下结构：

发现

• 仅列出代码能够证实的具体结构问题，无论是结构过度还是结构不足。
• 对于每个问题，说明当前结构为何不值得其成本，或缺少结构为何会影响导航。
• 如果代码本身是论点的关键依据，请用简短的内嵌代码片段或目录列表佐证。

保持不变

• 指出乍看之下可能显得臃肿或扁平、但值得保留的选择。
• 说明它们现在带来的好处。

重构候选项

• 仅纳入达到上述标准的改动。
• 对于每项改动，请说明：
  • 最小且合理的改动（简化、重组、拆分或合并）
  • 它会移除、合并或重新归类哪些内容
  • 能带来什么好处
  • 可能会失去什么
  • 现在是否适合进行，以及原因

待确认问题

• 列出可能支持当前结构的约束条件或未来需求，但目前尚未明确的部分。

结论

• 以以下其中一项结尾：
  • Structure is appropriate
  • Small restructure is justified
  • Broader reorganization may help, but only after clarifying constraints

代码片段规则

• 优先使用内嵌代码片段，而不是编辑器风格的行号引用。
• 将源文件路径作为注释放在每个代码片段的第一行。
• 代码片段应简洁；通常签名、模式定义、封装层、配置结构和翻译层就足够了。

沟通规则

• 默认给出最小且有用的建议。
• 如果代码结构已经足够精简，请直截了当地说明。
• 如果某个担忧看似合理但依据不足，请将其标注为观察项，而不是建议。
• 不要为了让评审显得有用而凭空制造简化机会。