用了这么多年 Room，你可能已经很习惯它的那套 API 了。
但这次 3.0，Google 直接换了包名、砍了 Java 代码生成、干掉了 KAPT，连同步 DAO 方法都不让写了。
是的，这是一次"断舍离"式的大版本升级。
为什么要大改
Room 从 2017 年发布到现在，一直是 Android 端最流行的数据库框架，没有之一。
但它有一个一直被诟病的问题：只能在 Android 上用。
随着 Kotlin Multiplatform（KMP）在 Google 内部的全面推进，Jetpack 的多个核心库都在做跨平台适配。Room 自然也不例外。
但问题是，Room 的底层深度绑定了 Android 的 SupportSQLite API，想要跨平台，必须换底座。小修小补解决不了问题。
所以 Google 选择了"大破大立"——直接发布 3.0 大版本，一次性清理历史包袱。
四个核心变化
Room 3.0 目前处于 Alpha 阶段，但方向已经非常明确。总结下来，有四个核心的破坏性变化。
全新包名
依赖从 androidx.room:room-runtime 变成了 androidx.room3:room3-runtime，类的包名也从 androidx.room 迁移到了 android.room3。
这意味着 Room 2.x 和 3.0 可以在同一个项目中共存，方便渐进式迁移。但也意味着——所有 import 都要改。
砍掉 Java 代码生成
Room 3.0 只生成 Kotlin 代码。如果你的项目还在用 Java 写 DAO 和 Entity，是时候迁移了。
这不是 Google 任性，而是为了简化编译器插件的维护成本。同时维护 Java 和 Kotlin 两套代码生成逻辑，对 Room 团队来说负担太重了。
仅支持 KSP
KAPT 和 Java 注解处理器（APT）都被移除了。Room 3.0 是一个纯粹的 KSP 处理器。
如果你还在用 KAPT，先迁移到 KSP。好消息是 Room 从 2.4.0 开始就支持 KSP 了，大多数项目应该已经完成了这步。
协程优先，禁止同步 DAO
这可能是影响最大的变化。Room 3.0 要求所有 DAO 方法必须是 suspend 函数，或者返回 Flow 等响应式类型。同步的、阻塞式的 DAO 方法？不支持了。
// ❌ Room 3.0 不再允许
@Query("SELECT * FROM users WHERE id = :id")
fun getUserById(id: Int): User
// ✅ 必须使用 suspend
@Query("SELECT * FROM users WHERE id = :id")
suspend fun getUserById(id: Int): User
// ✅ 或者返回 Flow
@Query("SELECT * FROM users")
fun getAllUsers(): Flow<List<User>>
你可能会问：我就想同步查个数据怎么办？
答案是用 runBlocking 或者在协程作用域里调用。Google 的态度很明确：现代 Android 开发，协程是标配。
怎么迁移
看到这些破坏性变化，你可能有点慌。别急，Google 给了一条比较清晰的迁移路径。
第一步：迁移 SQLite 驱动
从 Room 2.7.0 开始，就可以使用新的 androidx.sqlite 驱动 API 了。建议现在就开始迁，不要再写新的 SupportSQLite 代码。
第二步：用兼容层过渡
Room 2.8.0 提供了 room-sqlite-wrapper 桥接库，可以把 RoomDatabase 转换为 SupportSQLiteDatabase。这样你可以渐进式替换，而不是一次性改完所有代码。
第三步：切换到 Room 3.0
等 3.0 稳定后，替换包名和依赖。由于 2.x 和 3.0 可以共存，你甚至可以按模块逐步切换。
还有一个细节需要注意：如果你用了自定义的 DAO 返回类型（比如 RxJava 的 Observable、LiveData 等），需要用新的 @DaoReturnTypeConverter 注解显式注册转换器。
迁移的核心思路就是：先在 2.x 上做准备工作，等 3.0 稳定后再切换包名。
跨平台：不只是 Android
Room 3.0 最大的亮点，其实是跨平台能力。
通过 KMP 支持，Room 3.0 不仅能在 Android 上运行，还新增了 JavaScript 和 WebAssembly 平台的支持。
Web 端通过新的 androidx.sqlite:sqlite-web 驱动实现，底层是一个基于 Web Worker 的方案，利用 Origin Private File System（OPFS）做数据持久化。
这意味着什么？你可以用同一套 Room 定义的数据库 Schema，在 Android、iOS（通过 KMP）、以及 Web 端共享数据层逻辑。
对于做跨平台项目的团队来说，这是一个非常有价值的能力。再也不需要每个平台各写一套数据库操作了。
Room 2.x 还能用吗
能用，但进入了维护模式。
Google 会继续发布 2.8.1、2.8.2 这样的补丁版本，修复 bug 和安全问题。但不会再有新功能加入。
所以如果你的项目目前运行稳定，不必急着迁移。但如果是新项目，建议直接从 3.0 开始，哪怕它现在还是 Alpha。
因为迁移的成本只会越来越高，不如早走一步。
写在最后
Room 3.0 是 Jetpack 库跨平台化进程中的一个重要里程碑。
Google 选择了一条激进但正确的路：不兼容旧世界，全面拥抱 Kotlin 和协程。短期来看，迁移确实有成本。但长期来看，一个更简洁、更现代、更跨平台的 Room，对整个 Android 生态都是好事。
你的项目还在用 KAPT 吗？准备什么时候迁移 Room 3.0？评论区聊聊！
