---
url: /zh/onboarding/staff-engineer-guide.md
description: 用架构、兼容性与运营证据判断一次 Wow 边界变化是否值得接受。
---

# Staff Engineer 指南

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

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

## 已验证的架构输入

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

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

细节由[架构](../guide/advanced/architecture.md)、[运行时生命周期](../guide/advanced/runtime-lifecycle.md)、[数据流](../guide/advanced/data-flow.md)和[模块依赖](../guide/advanced/module-dependencies.md)维护。

## 架构与运营取舍

| 决策 | 可能收益 | 必须承担的代价 | 最小证据 |
|---|---|---|---|
| 扩大 `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**：部署、重放、恢复、关闭、监控和回滚是否仍成立。

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

### 3. 选择最小可撤销方案

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

### 4. 定义完成证据

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

## 接受门禁

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

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

## 优先下一步

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