Staff Engineer 指南

本页只回答一个问题：是否应该接受这次架构或运行时边界变化？

默认答案是保持现有边界。只有当前方案不能满足已证实的需求、最小替代方案明确、兼容性与运营成本可被验证时，才扩大公共契约、依赖或运行时职责。

已验证的架构输入

先从当前仓库建立决策基线：

• wow-api 拥有纯 API 契约；wow-core 拥有 CQRS、事件溯源、消息、投影、Saga 与运行时行为；wow-spring* 负责 Spring 装配；存储和传输留在专用模块。模块清单以 settings.gradle.kts 为准。
• 运行时保持 Reactor Mono/Flux 路径；核心分发、事件存储、投影、Saga 与传输路径不得引入阻塞。
• 命令追加事件流之后，下游发布、投影、Saga 与快照拥有各自的完成和失败边界。SENT、PROCESSED、SNAPSHOT、PROJECTED 不能互相替代。
• 事件历史是权威记录；快照是加速结构；投影是派生读模型；补偿是受控重试或重放，不是数据库回滚。
• 当前模块检查、TCK、集成测试和 benchmark 只能证明对应环境与范围，不能证明生产 SLA、全局顺序或任意部署拓扑。

细节由架构、运行时生命周期、数据流和模块依赖维护。

架构与运营取舍

决策	可能收益	必须承担的代价	最小证据
扩大 wow-api 公共契约	让下游直接表达新能力	source、binary、wire 兼容性需要分别评估	API 消费者、编译与契约测试；需要时比较 JVM ABI 与生成契约
移动模块职责或增加依赖	复用实现或简化装配	依赖方向、BOM、feature capability 与发布面扩大	生产者/消费者 Gradle 检查和解析后的依赖图
从本地总线切到分布式总线	跨进程交付与伸缩	投递歧义、顺序、ack、重试、DLQ 与运维责任	实际 broker 集成测试、故障演练和重放/对账方案
改变事件或生成 Schema	演进业务契约	旧事件读取、下游消费者和回滚可能失效	旧数据/旧请求契约测试、生成 diff 与升级路径
提高等待阶段	给调用方更强的可见性信号	延迟、超时和跨组件失败面增加	真实阶段测试与超时/取消行为，不把阶段命名当作证明
增加存储或缓存路径	满足持久化或查询需求	一致性、备份、恢复、索引和容量责任增加	后端 TCK/集成测试、备份恢复与重放验证
增加安全适配	传播身份或限制查询	Header 传播不等于完成认证、授权和租户隔离	应用安全配置、拒绝路径与资源范围测试
声称性能改善	改善已识别的瓶颈	结果依赖硬件、数据、参数和版本	可复现 benchmark 基线；不得从 smoke 推导容量

如果代价项没有明确所有者，它不是“以后补”的文档问题，而是当前方案尚未被运营接纳。

决策过程

1. 定位唯一所有者

列出公共类型、运行时消费者、Spring 装配、后端实现、测试与生成产物。优先在现有共享边界修复根因；不要为单一调用者创建并行抽象。

2. 分开四类契约

分别记录：

1. Source：下游源码能否继续编译；
2. Binary：现有 JVM 二进制是否仍能链接；
3. Wire / persisted data：旧请求、事件、快照、查询或生成客户端能否继续工作；
4. Operational：部署、重放、恢复、关闭、监控和回滚是否仍成立。

某一类通过不推导其他类别通过。若变化涉及历史数据或不兼容写入，转入迁移指南，不要把它当作普通依赖升级。

3. 选择最小可撤销方案

优先复用现有契约、后端原生语义和 feature capability。新配置只用于确实需要部署选择的行为；单一实现不需要预先增加接口、工厂或兼容桥。

4. 定义完成证据

在实现前写清检查矩阵：所属模块、消费者模块、TCK/集成测试、旧契约、生成 diff、benchmark 或运维演练。不能在本地建立的生产证据必须明确标为缺失，不能用单元测试替代。

接受门禁

只有以下条件都成立，才能建议接受边界变化：

• 需求和非目标明确，现有边界确实不足；
• 方案是满足需求的最小变化，且没有无用途的扩展点；
• source、binary、wire 和运营影响分别有结论；
• 事件演进、幂等、顺序、等待阶段、恢复和安全责任有明确所有者；
• 相关模块检查、契约/TCK、集成测试及生成产物检查已运行；
• 回滚边界与缺失的部署/数据证据写入决策记录；
• 最终 diff 只包含批准范围。

优先下一步

1. 边界不变：按贡献者指南实现最小变更。
2. 运行时或存储变化：先核对生产最佳实践与恢复。
3. 破坏性契约或历史数据变化：进入迁移，在切换前建立对账与回滚证据。