# Architecture 方法

当核心工作流不够详细时读取此参考资料。

## 质量属性场景

把质量目标转为可测试的场景：

| 字段 | 问题 |
| --- | --- |
| Stimulus | 发生了什么事件、负载、故障、威胁或变更？ |
| Source | 谁或什么触发它？ |
| Environment | 处于正常、峰值、降级还是恢复条件？ |
| Artifact | 哪个服务、模块、数据存储或部署受到影响？ |
| Response | 系统应该做什么？ |
| Measure | 要多快、多频繁、多少，或达到什么恢复目标？ |

示例：“区域依赖中断期间，checkout API 应在 2 秒内以安全错误拒绝新的支付尝试，保留订单状态，并在 5 分钟内产生告警。”不要把示例数值当作其他系统的目标。

## 有用的架构视图

选择能回答决策的问题的视图，而不是记录所有内容。

- **Context：** 参与者、外部系统、职责、信任边界和离开系统的数据。
- **Container/module：** 可部署单元或代码模块、接口、依赖方向、所有权和变更局部性。
- **Data：** 权威来源、读模型、schema/version 所有权、一致性、保留和迁移。
- **Runtime：** 请求顺序、异步工作、并发、队列语义、超时、重试、背压和故障传播。
- **Deployment：** 环境、放置位置、扩缩容单元、网络/身份依赖、发布、回滚和恢复。

当关系比视觉布局更重要时使用表格。只有在能明显澄清流程或边界时才使用 Mermaid。保持图与正文一致，并标记未知项。

## 方案比较矩阵

使用相同标准比较每个候选方案。只有定义了含义时才使用 High/Medium/Low。

| 标准 | Baseline | Option A | Option B |
| --- | --- | --- | --- |
| 当前交付速度 |  |  |  |
| 边界强度 |  |  |  |
| 运维复杂度 |  |  |  |
| 独立扩缩容 |  |  |  |
| 故障隔离 |  |  |  |
| 数据一致性成本 |  |  |  |
| 可测试性 |  |  |  |
| 迁移风险 |  |  |  |
| 成本/认知负担 |  |  |  |

不要在不解释含义的情况下添加分数。如果权重重要，说明权重，并展示优先级变化会如何改变结果。

## 边界启发式

有用的边界通常具备：

- 一个清晰的职责和词汇
- 行为和数据的所有者
- 小而有意设计的接口
- 可以解释的依赖方向
- 调用者能够理解的事务与一致性模型
- 独立测试，或明确设计的集成测试边界
- 不会迫使无关模块一起变更的变更模式

警示信号包括共享可变表、循环 import、拥有业务权威的“utility”模块、泄露内部状态的 callback、重复所有权、同步发布依赖，以及暴露持久化细节的接口。

## 迁移切片

优先选择能保持系统运行的、纵向且可逆的切片：

1. 描述当前行为，并在接缝处增加可观测性。
2. 引入显式契约或 anti-corruption layer。
3. 在兼容旧路径的同时移动一个能力或流程。
4. 只有在具备对账与移除计划时才做双读或双写。
5. 逐步切换流量或所有权，并定义回滚。
6. 有证据确认安全后再移除旧路径、schema 或依赖。

每个切片都要写明 invariant、owner、rollout signal、rollback action、data reconciliation 和 cleanup condition。除非约束让渐进式迁移不可行且风险已明确接受，否则避免“全部重写”计划。