跳到正文
擎天文档返回官网 ↗
文档/方法参考

架构设计原则

本页内容

用以下原则裁决 owner、状态、生命周期和抽象力度,只展开与当前决策直接相关的项:

  • information-expert:职责归拥有所需事实和不变量的对象。
  • single-complete-owner:同一事实、状态变化和生命周期只有一个权威且完整的 owner;owner 覆盖创建、状态、不变量、生命周期和对外语义。
  • minimal-responsibility-surface:上层只提供 owner 无法自知的外部事实、用户选择或真实策略点。
  • high-cohesion-low-coupling:一起变化且必须同步的状态放在一起;调用方不依赖内部细节。
  • tell-dont-ask:调用业务意图,不读散字段后在 owner 外拼流程。
  • simple-structure-first:对象、数组、局部函数或现有 owner 足够时,不升级为新 service、manager 或 context。
  • abstractions-pay-rent:抽象必须消除真实重复、保护不变量或隔离稳定变化点,收益大于名字、文件、跳转和合同成本。
  • evidence-before-generality:先服务已确认的用户路径和当前调用者;动态发现、多实现路由、registry/resolver/provider 层、namespace、分页、通用 DSL、capability 或扩展槽不能只凭未来可能性进入首版合同。第二个消费者、既有重复 owner、明确排期或昂贵持久迁移属于当前证据;没有证据时,需求出现后再增加通常更便宜。
  • balanced-complexity:同时审计过小端的错误边界、重复生命周期和迁移债,以及过大端的无消费者抽象、状态和验证面;按全生命周期净复杂度选平衡点,不把最小改动或最大扩展性当目标。
  • constructor-builds-graph:constructor 只建立同步确定的长期对象图;load/start/reload/stop/dispose 承担副作用。
  • cqs-pure-read:read/get/list/status 不暗中改变状态;mutation 表达业务意图。
  • equivalence-by-construction:当多个入口、宿主、实现或持久状态被要求语义等价时,让它们收敛到同一权威 owner、规范表示和状态迁移,并使旧实现与平行路径从正常链路中不可达;禁止靠消费者逐点补丁、复制规则或穷举黑盒场景拼装等价。测试只证明该机制及其不变量未被破坏,不负责用样例数量制造等价性。
  • no-compatibility-by-default:兼容必须由真实存量证据驱动;不能把旧命名、聊天引用、曾写过或刚发布过的草案虚构成历史消费者。无真实依据时直接更新已知引用并删除旧入口;判定见下节。
  • deletion-first:新增前先删除重复入口、平行 owner、无语义 wrapper 和过期兼容;不为行数指标损害可读性和合同安全。

判断顺序:先写最小完整路径、事实、不变量、生命周期与已知变化轴;找到 information expert;要求跨入口等价时收敛到同一 owner;列出过小端与过大端成本;删除重复 owner 和透传层;逐个审计新增名词的当前证据与全生命周期净收益;冻结保留、删除、延后项。

输出命中的原则、违反点、推荐 owner、删除与延后项、生命周期边界,以及过小端、平衡点、过大端的关键代价。不能用“可扩展”或“最小改动”单独证明方案正确。

真实存量与兼容证据#

准备新增或保留旧入口、字段别名、迁移适配、legacy分支或重定向时,先回答:谁现在依赖它?有什么证据?为何不能直接一起更新? 兼容设计方承担举证责任,不能把“不知道是否有人用”描述成“有历史存量”。

  • 可用依据包括已运行且不能同步升级的实际使用方、真实持久化数据、可定位的独立客户端,以及明确生效的对外版本支持承诺;记录来源与具体影响。真实对外承诺可以构成约束,不以缺少使用遥测为由擅自破坏。
  • Git里存在过、聊天里贴过旧路径、刚改过名、AI先前写了一个方案、单独一条发布记录或假想用户,都不单独证明兼容必要性。未落地/未形成存量的机制直接采用正确路径,更新当前引用,删除旧入口;过程历史留在Git或日志,不用跳转文件保存历史。
  • 证据存在时仍选择最窄迁移/过渡边界,写清消费者、必要性、可观察方式与删除条件;内部能一起更新的调用方直接迁移,不为一次重命名建立长期双路径。缺少关键证据先核对事实,不默认增加兼容层,也不虚构“绝无用户”。

反例:未投入使用的文档从A改名B,只更新引用并删除A;不能因聊天引用过A就保留跳转。真实客户端仍读取旧协议或已有持久数据时,则先处理其实际升级/迁移约束,不能机械套用删除。

公开闭集变体的传播合同

新增或扩展公开 schema、union、protocol、runtime kind 或其它闭集 variant 时,设计必须形成传播矩阵,从 producer 逐项核对真实适用的 parser/validator、序列化与持久化、索引/目录、transport/分发、安装/升级以及最终 runtime/UI consumer。不适用项写明依据。类型编译、本地入口或单个 consumer 通过,不能支持“能力已完整支持”的结论。