零容错设计原则Fail Fast任何异常/失败/边界情况必须立即暴露宁可崩溃不可静默。参考docs/KnowLedge/零容错设计原则.md完整版哲学基础软件熵增定律错误被掩盖 系统熵增错误被暴露 系统熵减。每次静默吞没异常系统就多一个不可见的不稳定点累积到临界值后以不可预测的方式爆发。失败传播定律早期失败成本 O(1) — 问题在发生处即时报 晚期失败成本 O(n²) — 问题在 N 步后以诡异方式爆发失败越早暴露修复成本越低。每延迟一层传播排查复杂度平方增长。确定性原则系统行为应可预测。静默失败破坏可预测性——调用方以为操作成功实际已失败后续行为不可预测。三种失败模式对比模式行为适用场景代价Fail Fast立即抛出异常不可恢复错误、前置条件违例调用方必须处理Fail Safe降级到安全默认值用户输入校验、可选功能失效可能隐藏问题Fail Graceful优雅降级部分可用非核心功能失效、第三方超时实现复杂度高零容错 Fail Fast 的严格形式在初始化、边界、数据完整性等关键路径上拒绝 Fail Safe 的默认值替代策略。三层检查体系按契约式编程Design by Contract的三个维度组织前置条件检查Precondition— 调用方责任方法被调用前必须满足的条件不满足则拒绝执行。规则说明异常类型创建/工厂方法失败抛异常工厂、构建器、DI 容器无法创建实例时抛异常指明缺失的类型/配置/依赖InvalidOperationException查找/获取不到抛异常查找、获取、解析方法找不到目标时抛异常指明查找的键/名称/条件KeyNotFoundException/InvalidOperationException配置缺失报错必要字段、类型、依赖缺失时在启动/初始化时抛异常禁止默认值替代InvalidOperationException后置条件保证Postcondition— 实现方责任方法执行后必须保证的状态无法保证则拒绝静默返回。规则说明异常类型禁止空 catch所有 catch 块必须记录异常禁止catch {}静默吞没视场景而定状态不一致立即暴露内部状态校验发现不一致时立即抛异常禁止尝试静默修复InvalidOperationException不变式维护Invariant— 全局责任系统在任何时刻都必须保持的恒常条件。规则说明异常类型边界显式检查参数 null、集合空、索引越界在方法入口处显式检查ArgumentNullException/ArgumentOutOfRangeException聚合架构设计规范参考docs/KnowLedge/聚合架构设计规范从三收拢点到多元聚合的工程范式.mdv3.0核心让隐式的依赖变得显式让分散的操作变得集中让混乱的边界变得清晰。定义与结构聚合 边界 契约 实现要素含义设计关注点边界职责范围清晰/完整/无重叠契约对外接口稳定/完备/可测试实现内部细节可替换/可独立演化拓扑结构三种类型可嵌套组合面→线→点类型定义适用场景示例点聚合分散同类操作收敛到单一入口外部依赖/数据流边界收敛EcsInputPort/CsgEntryPoint/WinFormsOutputPort线聚合有序步骤编排为管线流程编排/阶段式处理EcsRenderPipeline.ExecutePipeline()面聚合模块公开能力收敛到入口面模块能力出口收敛WorkflowMethodUsage设计规范聚合点识别原则何时创建聚合点外部依赖收敛多组件依赖同一外部资源时创建聚合点封装数据流边界收敛数据跨子系统流动时在边界创建聚合点能力出口收敛模块对外提供多能力时创建统一入口变更热点收敛频繁变更点收敛到聚合点中限制影响范围聚合边界划分规范单一职责一个聚合点只负责一个维度的收敛边界内完整能力必须完整覆盖该维度所有场景边界间无重叠聚合边界间不允许职责重叠聚合间通信契约方式适用场景耦合度方法调用同步、同进程编译时耦合事件/委托异步、解耦运行时耦合数据对象跨边界传输数据耦合反模式与评估从内聚度、收敛度、边界清晰度三个维度评估聚合质量反模式症状解决方案上帝聚合过度聚合方法 30实现 1000 行拆分为多个单一职责聚合点分散聚合聚合不足操作分散无统一入口创建统一输出聚合点隐式聚合无明确边界边界不明确越界操作明确边界禁止越界循环聚合循环依赖聚合点 A ↔ 聚合点 B引入事件/委托打破循环设计哲学解耦减少模块间直接依赖 聚合将分散操作收敛到统一入口正确聚合不会增加耦合而是将隐式分散的耦合转化为显式集中的耦合。设计目标高解耦 高聚合——模块间契约通信模块内聚合收敛。核心价值可审计关键操作经明确入口/出口、可维护变更影响被聚合边界限制、可演化内部实现可替换对外契约不变。三者相互促进目标是在三者间找到适合项目阶段的最优平衡点。文件读取策略核心一次读取分阶段消化。让读取深度与分析深度匹配。参考docs/KnowLedge/文件读取策略.md完整版上下文守恒定律逐个读取 N 个文件的总消耗 Σ(每个文件的上下文开销 往返开销)。批量读取 N 个文件的总消耗 ≈ max(文件开销) 单次往返开销。当 N 1 时批量读取始终优于逐个读取。推论每减少一次往返就多一份预算用于真正的分析。信息分层理论信息按密度分三层分析阶段与信息层次必须匹配不可跳跃层次内容对应阶段元信息路径、大小、语言类型扫描结构信息类/函数签名、大纲预览细节信息完整实现、算法逻辑深入约束未评估信息域之前不进行任何信息获取。未到达的分析阶段不预加载其所需信息。三阶段读取模型阶段目标信息层次约束扫描确定有哪些文件需要关注元信息不读取任何文件内容预览批量获取结构信息建立全局认知结构信息一次调用读取所有目标文件深入对选定文件进行完整分析细节信息仅对预览阶段确认为需要深入的文件执行前置条件——信息域评估进入三阶段之前先评估所需信息的范围单文件/单模块/跨模块/全项目、类型代码/配置/日志/文档/数据、复杂度简单/中等/复杂和确定性已知/模糊/未知。信息获取路径两种基本路径链式追溯沿调用链逐层追溯函数调用链、项目依赖链、继承链适用于理解数据流、评估变更影响。平铺探索按目录结构横向展开只获取元信息和结构信息适用于了解整体结构、模块划分。四种读取策略策略定义上下文效率批量读取一次调用读取所有目标文件★★★★★分阶段读取按扫描→预览→深入逐层推进★★★★☆按需读取仅当需要时才读取特定文件★★★☆☆流式读取边读取边处理不保留全量★★★★★策略选择首次接触代码库→分阶段修复已知 Bug→按需批量代码审查→批量大文件/日志→流式架构重构→分阶段批量。反模式反模式解决方案盲目读取无评估先评估信息域再选择策略逐点读取逐个读取合并为批量读取过度读取只需头部却读全文按信息层次分级读取深度不匹配扫描阶段加载细节按三阶段模型匹配读取深度设计哲学先评估后读取。 链式追溯平铺探索。 扫描不预览预览不深入。 一次读取分阶段消化。