Skip to content

架构文档导读(五层深入) ​

本节是 rust_svc 的架构手册,以当前代码为准写成。全部页面按由浅入深的次序组织成 五个层次,每层回答一类固定的问题;读完某一层即可停下来干活,需要更深时再往下走。 所有结论可回溯到源码,逐条证据登记在架构证据链。

五层视图与建议顺序 ​

下表就是建议阅读顺序:从 L1 到 L5 依次加深。每一行给出该页回答的问题与适合的 读者画像,时间预算按通读估算。

顺序层页面一句话摘要适合读者
1L1 全局全局视角一张图与一张表说清系统组成、请求进出路径与事件流所有人,约 10 分钟
2L2 逻辑逻辑分层五个逻辑层的职责边界与依赖规则,谁允许依赖谁开发者、架构评审者
3L2 逻辑组件清单十个服务(九数据面 + 告警桥接)与十个平台 crate 的逐组件职责、依赖与端口开发者、接手新模块的人
4L3 运行时运行时架构进程内怎么跑:装配序、tokio 任务、总线、优雅停机平台开发者、性能排查者
5L4 控制流请求生命周期一次北向请求从网关进、落库、返回的全时序深度理解者、排障者
6L4 控制流启动生命周期一次启动从配置装载到接流的装配时序与屏障平台开发者、运维
7L4 控制流服务间通信同步 gRPC 与异步事件两类跨服务调用的契约服务联调、契约评审者
8L5 源码源码地图按问题找代码入口的导航,附半天阅读路线与落点速查表准备读代码的人

另有三个主题页不属于五层主线,按需取用:数据模型与迁移(五库 布局与 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 索引);职责边界的现行裁决以架构收敛与职责约定文档为准。设计文档集与本站冲突时,以本站与代码为准,差异记录在架构证据链。

以仓库代码为事实源构建 · RC Hardening 阶段