前言

为什么写这本书

Rust 生态中的数据库访问方案丰富多样：从底层的 `sqlx` 到异步ORM，开发者可以根据需求自由选择。然而，**当项目规模扩大、实体关系复杂、团队协作加深时，缺乏统一模式的裸 SQL 或极简查询库往往导致重复代码和隐晦的bug**。

`rust-ef`（Rust Entity Framework）的诞生，源于一个清晰的目标：为 Rust 开发者提供一套**受 EF Core 启发、接口导向、与 DI 容器深度集成**的 ORM 框架，使数据库操作在保持 Rust 类型安全的同时，具备工程化团队所需的可维护性和可测试性。

本书不是 API 参考手册的堆砌，而是一份**面向实际开发场景的实践指南**——它告诉你如何设计实体、如何编写可读性强的查询、如何在真实项目中处理关联数据，以及如何避开常见陷阱。

本书适合谁

| 读者画像 | 你将获得什么 | |---------|-------------| | 从 EF Core / Django ORM 迁移的团队 | 概念一一映射、DbContext 思维模型直接复用 | | Rust 中级开发者，首次使用 ORM | 渐进式学习路径，避免在查询构造与状态跟踪间反复试错 | | 架构师与技术负责人 | 职责划分、批量操作策略、性能优化依据 | | AI 辅助开发者 | 模块化的实体/查询/上下文边界，使 AI 生成代码可直接插入系统 |

如何阅读本书

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

1. **第一至二章**——建立全局认知，15 分钟内跑起第一个 DbContext 2. **第三至四章**——理解实体设计与关系映射，掌握 `#[derive(EntityType)]` 的能力边界 3. **第五至六章**——查询是 ORM 的核心，深入学习 `linq!` 宏与高级场景 4. **第七至八章**——变更跟踪与批量操作，理解 SaveChanges 的幕后行为 5. **第九至十一章**——事务、迁移、DI 集成与最佳实践，形成生产级能力

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

核心推荐：代码可读性优先

本书始终推荐一种**可读性优先**的编码风格：

let set = ctx.set::<Blog>();

let expr = linq!(|b: Blog| b.rating > 0.5);

return set.filter(expr).to_list().await?;

这种写法在合适的时机使用链式调用，而非将所有操作挤压在一行。当查询条件复杂时，拆分为独立的 `let` 绑定能显著提升可维护性。

约定与符号

- 代码示例默认使用 `use rust_ef::prelude::*;` 统一导入 - `✅` 表示推荐做法，`❌` 表示常见错误 - 示例项目 `blog` 贯穿全书，可通过 `cargo run -p blog` 本地体验

致谢

`rust-ef` 站在 Rust 生态的肩膀上：`sqlx` 提供异步数据库底座，`rust-dix` 提供 DI 容器，`quote`/`syn` 驱动 `linq!` 宏的编译时代码生成。感谢所有开源贡献者。

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