外观
架构文档导读(五层深入)
本节是 rust_svc 的架构手册,以当前代码为准写成。全部页面按由浅入深的次序组织成 五个层次,每层回答一类固定的问题;读完某一层即可停下来干活,需要更深时再往下走。 所有结论可回溯到源码,逐条证据登记在架构证据链。
五层视图与建议顺序
下表就是建议阅读顺序:从 L1 到 L5 依次加深。每一行给出该页回答的问题与适合的 读者画像,时间预算按通读估算。
| 顺序 | 层 | 页面 | 一句话摘要 | 适合读者 |
|---|---|---|---|---|
| 1 | L1 全局 | 全局视角 | 一张图与一张表说清系统组成、请求进出路径与事件流 | 所有人,约 10 分钟 |
| 2 | L2 逻辑 | 逻辑分层 | 五个逻辑层的职责边界与依赖规则,谁允许依赖谁 | 开发者、架构评审者 |
| 3 | L2 逻辑 | 组件清单 | 十个服务(九数据面 + 告警桥接)与十个平台 crate 的逐组件职责、依赖与端口 | 开发者、接手新模块的人 |
| 4 | L3 运行时 | 运行时架构 | 进程内怎么跑:装配序、tokio 任务、总线、优雅停机 | 平台开发者、性能排查者 |
| 5 | L4 控制流 | 请求生命周期 | 一次北向请求从网关进、落库、返回的全时序 | 深度理解者、排障者 |
| 6 | L4 控制流 | 启动生命周期 | 一次启动从配置装载到接流的装配时序与屏障 | 平台开发者、运维 |
| 7 | L4 控制流 | 服务间通信 | 同步 gRPC 与异步事件两类跨服务调用的契约 | 服务联调、契约评审者 |
| 8 | L5 源码 | 源码地图 | 按问题找代码入口的导航,附半天阅读路线与落点速查表 | 准备读代码的人 |
另有三个主题页不属于五层主线,按需取用:数据模型与迁移(五库 布局与 36 个迁移)、多租户安全模型(信任链、RLS 与审计链)、 一致性语义(每类状态的强弱一致分类,避免误用)。
按任务选页
text
我只想大概了解这套系统 → overview 读一遍
我要接入 API 或调试请求 → overview,再进 request-lifecycle
我要读代码、改某个服务 → components 找到组件,再按 source-map 进文件
我在排查线上行为 → request-lifecycle 与 consistency 定位语义,再查排障中心
我要评审一个架构改动 → layers 看依赖红线,design/adr 看既有决策
我要加一个新服务或新域 → components 对照现有样板,development/new-service 有配方与设计文档集的关系
本手册面向长期维护,随代码演进更新。项目设计文档集记录了逐里程碑的决策过程与裁决依据(架构决策编号 D-XX01 体系,例如 D-MA01 多租户方案、D-TR01 Tantivy 主引擎,站内导航见ADR 索引);职责边界的现行裁决以架构收敛与职责约定文档为准。设计文档集与本站冲突时,以本站与代码为准,差异记录在架构证据链。