面向"从零接手本项目"的开发者:按序读完,你会从一个空环境走到能独立实现服务模块、理解全部横切系统、并把系统安全部署上线。
本系列的定位:讲路径与概念,每章末尾的「深读」链到参考层文档(docs/*.md)拿细节。
两层冲突时以参考层与代码为准,欢迎修订教程。
| 章 | 主题 | 前置 | 你将得到 |
|---|---|---|---|
| 01 架构全景 | 仓库布局、一次请求的完整路径、横切系统地图、生成物边界 | 无 | 知道代码都在哪、请求怎么流 |
| 02 从零跑起来 | 本地开发环境(中间件 + 后端 + 前端)到登录进系统 | 01 | 一个可调试的本地环境 |
| 03 契约与生成链路 | proto 同步、构建期双面编译、路由/错误表/服务 trait 的生成与边界 | 02 | 知道哪些代码是生成的、哪些是手写的 |
| 04 第一个服务模块 | 以一个真实小模块为例,端到端走一遍服务实现闭环 | 03 | 亲手跑通一遍完整开发闭环 |
| 05 权限模型 | 鉴权门四阶段、令牌与声明、authz 评估、菜单/字段可见性 | 04 | 理解"谁能看到什么、调到什么" |
| 06 多租户与行级隔离 | 租户 HTTP 闸门、数据层 Viewer 三态、套餐与到期策略 | 05 | 理解"行级谁的数据"与部署闸门 |
| 07 审计与等保 | 六类审计日志的采集与留存、身份鉴别三件套、MFA | 01 | 知道审计能力怎么用、边界在哪 |
| 08 部署上线 | 配置模型、装配文档、生产密钥、启动序列、上线检查单 | 02 | 把系统安全地放到生产 |
| 09 写下游:加你的第一个业务模块 | fork 工作流、template 解剖、main.rs 四行装配、跟进上游 SOP | 04, 06 | 业务模块以独立目录长在基座上,且与上游零冲突可合并 |
- 全栈采用者(拿本基座做自己产品):01 → 02 → 03 → 04 → 05 → 06 → 08 → 09;07 按需。
- 后端开发者:01 → 02 → 03 → 04 → 06 → 07,再按子系统读参考层。
- 前端开发者:01 → 02 → 03(重点 TS 客户端面)→ 05,再读
frontend/admin/react内的说明文档。 - 运维 / 安全:01 → 02 → 07 → 08。
- 给本仓提 PR 的贡献者:全部教程 + 根
CONTRIBUTING.md(仓库约定以 CONTRIBUTING 为准)。
- 本系列只做"路径与概念",机制细节一律以参考层文档为权威(清单见 docs/README.md);
- 功能变更:改参考层,检查本系列链接是否仍成立;
- 发现章节内容与代码不符:以代码与参考层为准修章节,并在 PR 注明;
- 新增横切系统时:既加参考层文档,也在 01 章地图与对应章补一行。