前言

为什么写这本书

Rust 在系统编程领域已经证明了自身的价值，但在 Web 后端开发中，开发者仍常常面临一个困境：**要么选择极简路由库自行拼装一切，要么在大量样板代码中迷失方向**。

`rust-webx`（原名 LRWF）的诞生，源于一个朴素的目标：让熟悉 ASP.NET Core 的开发者，以及追求工程化、模块化的 Rust 开发者，能够**用他们已掌握的思维模型，在 Rust 中构建生产级 WebApi 服务**。

本书不是 API 手册的堆砌，而是一份**面向产品形态的开发者指南**——它告诉你框架如何思考、如何组织代码、如何在真实项目中解决实际问题，以及如何从入门者成长为能够驾驭整个框架的开发者。

本书适合谁

| 读者画像 | 你将获得什么 | |---------|-------------| | 从 ASP.NET Core / MediatR 迁移的团队 | 概念一一映射、分层结构直接复用、迁移路径清晰 | | Rust 中级开发者，首次构建 WebApi | 渐进式学习路径，避免在路由/DI/中间件之间反复试错 | | 架构师与技术负责人 | 职责划分、依赖方向、扩展点的设计依据 | | AI 辅助开发者 | 请求即端点的模块边界，使 AI 生成的代码可直接插入系统 |

如何阅读本书

本书严格遵循**渐进式披露**原则：

1. **第一至二章**——建立全局认知，30 分钟内跑起第一个服务 2. **第三至四章**——理解设计哲学与架构全景，知道「为什么这样设计」 3. **第五至十一章**——按主题深入各子系统，解决具体开发需求 4. **第十二至十四章**——项目组织、扩展封装与最佳实践，形成工程化能力 5. **第十五至十六章**——通过 Docbit 案例与迁移指南，融会贯通

每章开头的 `INDEX.md` 是小节目录；遇到不熟悉的名词，先读该章 INDEX，再按需跳转到具体小节，不必线性通读。

约定与符号

- 代码示例默认使用 `use webx::*;` 统一导入 - `✅` 表示推荐做法，`❌` 表示常见错误 - 路径参数写作 `{id}`，与路由宏一致 - 示例项目 `docbit` 贯穿全书，可通过 `cargo run -p docbit` 本地体验

致谢

`rust-webx` 站在 Rust 生态的肩膀上：`hyper` 提供 HTTP 底座，`rust-dix` 提供 DI 容器，`inventory` 实现编译时路由收集。感谢所有开源贡献者。

**迁移提示：** 若你使用过已弃用的 `global_provider()`，请参阅 [全局状态迁移](16-migration/global-state.md)。

现在，让我们从第一章开始。