Room 的多表关联查询，@Relation 的 N+1 问题

「Room 的多表关联查询，@Relation 的 N+1 问题」

去年维护一个本地缓存模块的时候，我踩到了 Room 的 @Relation 注解埋下的一个性能坑。当时的需求不算复杂：一个新闻 App 的离线阅读功能，文章表和标签表多对多，中间一张关联表。我用 @Relation 配合 Embedded 很快就搭好了 POJO，查询代码看起来干净利落，编译通过，数据也对。直到我在 Profiler 里看到 SQL 执行次数的时候，才发现事情不对劲。

`@Relation` 的便利背后

Room 的 @Relation 注解从 2.0 开始就是官方推荐的多表关联方案。它的设计意图很明确：让你用面向对象的方式表达一对多关系，框架自动处理 JOIN 和结果映射。典型的写法是这样的：

@Entity(tableName = "articles")
data class ArticleEntity(
    @PrimaryKey val id: String,
    val title: String,
    val content: String
)

@Entity(tableName = "tags")
data class TagEntity(
    @PrimaryKey val id: String,
    val name: String
)

@Entity(
    tableName = "article_tag_cross",
    primaryKeys = ["articleId", "tagId"]
)
data class ArticleTagCrossRef(
    val articleId: String,
    val tagId: String
)

data class ArticleWithTags(
    @Embedded val article: ArticleEntity,
    @Relation(
        parentColumn = "id",
        entityColumn = "id",
        associateBy = Junction(
            value = ArticleTagCrossRef::class,
            parentColumn = "articleId",
            entityColumn = "tagId"
        )
    )
    val tags: List<TagEntity>
)

然后 DAO 里一个方法搞定：

@Query("SELECT * FROM articles")
fun getArticlesWithTags(): Flow<List<ArticleWithTags>>

这种写法在官方文档和各路教程里被反复推荐，我也用了很久。问题出在数据量上来之后。我那个场景里，用户可能一次性加载 50 篇文章，每篇文章平均 3-5 个标签。Profiler 显示不是一条 JOIN 查询，而是 1 条主查询加 50 条标签查询。这就是经典的 N+1。

Room 到底生成了什么 SQL

我最初以为是自己的写法有问题，或者哪里漏配了。但翻 Room 的源码和生成的 _Impl 文件之后，发现这是 @Relation 的固有行为。

Room 编译器生成的实现代码里，@Relation 的处理逻辑在 androidx.room 的 EntityDeletionOrUpdateAdapter 相关类之外，由 RelationCollector 负责。它不会生成单条 JOIN SQL，而是分成两步：

第一步，执行你写在 @Query 里的主查询，拿到所有 parent 实体。第二步，对每一个 parent，根据 @Relation 的配置生成一条独立的子查询，用 IN 或者等值条件去取关联数据，然后在 Java/Kotlin 层做组装。

具体到我的例子，生成的逻辑近似这样：

// 伪代码，基于 Room 2.5.0 生成的实际逻辑简化
Cursor _cursor = db.query("SELECT * FROM articles");
while (_cursor.moveToNext()) {
    ArticleEntity _article = // ... 从 cursor 解析
    // 对每一篇文章，单独查标签
    Cursor _cursorTags = db.query(
        "SELECT id, name FROM tags " +
        "INNER JOIN article_tag_cross ON tags.id = article_tag_cross.tagId " +
        "WHERE article_tag_cross.articleId = ?",
        new Object[]{ _article.id }
    );
    List<TagEntity> _tags = // ... 解析标签列表
    // 组装 ArticleWithTags
}

这和我预期的 SELECT ... FROM articles LEFT JOIN article_tag_cross LEFT JOIN tags 完全不同。Room 2.5.0、2.6.0-alpha 都是这个行为，不是 bug，是设计如此。

Google Issue Tracker 上这个问题被反复提起。Issue 207847623 里有官方回复，确认 @Relation 目前的实现就是多条查询，原因是单条 JOIN 查询在处理一对多关系时会有结果集膨胀（duplication），Room 选择用多次查询来避免复杂的去重逻辑。这个权衡在关联数据量小的时候没问题，但 N 一旦变大，RTT 和 cursor 开销就不可忽视。

手动 JOIN 的尝试与坑

发现问题之后，我的第一反应是放弃 @Relation，自己写 JOIN。但这条路比想象中曲折。

最直接的写法：

@Query("""
    SELECT articles.*, tags.id AS tagId, tags.name AS tagName
    FROM articles
    LEFT JOIN article_tag_cross ON articles.id = article_tag_cross.articleId
    LEFT JOIN tags ON article_tag_cross.tagId = tags.id
""")
fun getArticlesWithTagsRaw(): List<ArticleWithTagsRaw>

问题在于 LEFT JOIN 会把一对多展开成多行。如果一篇文章有 3 个标签，结果集里这篇文章会出现 3 次，只是 tag 列不同。Room 的 @Embedded 没法自动把这种行结构折叠回 List<TagEntity>。

我试过几种映射方案。

第一种，用 Map 返回类型，这是 Room 2.4.0 引入的特性：

@Query("...")
fun getArticlesWithTagsMap(): Map<ArticleEntity, List<TagEntity>>

这个 API 看起来就是为 JOIN 场景设计的。但实际用起来有约束：Map 的 key 必须是 @Embedded 或者直接是 entity，value 必须是 list of entity。而且 Room 要求 SELECT 列必须能唯一标识 key，否则会抛 IllegalStateException。更麻烦的是，它内部仍然不是单条 JOIN 就搞定，而是类似 @Relation 的分治逻辑，只是接口封装不同。我测下来 SQL 执行次数没有减少。

第二种，自己写 TypeConverter 或者自定义 Pojo，在应用层做 fold。比如定义一个扁平的中间结构：

data class ArticleTagRow(
    val articleId: String,
    val title: String,
    val content: String,
    val tagId: String?,
    val tagName: String?
)

然后查询返回 List<ArticleTagRow>，再用 Kotlin 的 groupBy 组装：

@Query("...")
fun getRows(): List<ArticleTagRow>

// 在 Repository 层
fun getArticlesWithTags(): List<ArticleWithTags> {
    return getRows()
        .groupBy { it.articleId }
        .map { (articleId, rows) ->
            ArticleWithTags(
                article = ArticleEntity(
                    id = articleId,
                    title = rows.first().title,
                    content = rows.first().content
                ),
                tags = rows.mapNotNull { row ->
                    row.tagId?.let { TagEntity(it, row.tagName!!) }
                }
            )
        }
}

这个方案确实只用了一条 SQL，但代码臃肿，而且丢失了 Room 的响应式能力。getRows() 返回普通 List，如果要接 Flow，还得自己包装，或者把 fold 逻辑塞进 DAO 的 @Transaction 方法里，但 @Transaction 只保证原子性，不保证单条查询。

`@Transaction` 的误解

说到 @Transaction，这里有个常见的认知偏差。很多人以为在 DAO 方法上加 @Transaction，就能让 @Relation 的多次查询变成"一次事务执行"，从而提升性能。这完全是两回事。

@Transaction 在 Room 里的作用是确保方法内的所有数据库操作在一个 SQLite 事务中完成，保证原子性，避免并发修改导致的数据不一致。它不改变查询次数，也不减少 SQL 语句数量。对于 @Relation，Room 自动加了 @Transaction，所以你手动加不加都一样。

我在 2.4.0 版本上验证过：有 @Transaction 和没有，Profiler 里的 SQL 执行计划完全相同，都是 N+1 条。区别只在于这 N+1 条是否包裹在 BEGIN TRANSACTION / COMMIT 之间。对于只读查询，事务开销几乎可以忽略，所以 @Transaction 对性能没有实质帮助。

真正想减少查询次数，必须绕过 @Relation。

最终采用的方案：数据库视图 + 聚合

折腾了几轮之后，我采用的方案是 SQLite 的聚合函数配合 Room 的 @DatabaseView，或者说在查询层做 JSON 聚合。这个思路来自 SQLite 3.38.0 引入的 JSON 函数支持，以及 Room 2.4.0 之后对原生 SQL 的更好兼容。

具体做法：不查多行再折叠，而是在 SQL 里把多行标签聚合成一个 JSON 数组字符串，返回后再解析。

@Query("""
    SELECT 
        articles.*,
        json_group_array(
            json_object('id', tags.id, 'name', tags.name)
        ) AS tagsJson
    FROM articles
    LEFT JOIN article_tag_cross ON articles.id = article_tag_cross.articleId
    LEFT JOIN tags ON article_tag_cross.tagId = tags.id
    GROUP BY articles.id
""")
fun getArticlesWithTagsJson(): List<ArticleWithTagsJson>

对应的 POJO：

data class ArticleWithTagsJson(
    @Embedded val article: ArticleEntity,
    @ColumnInfo(name = "tagsJson") val tagsJson: String
)

然后在外面用 kotlinx.serialization 或者 Gson 解析 tagsJson。如果某篇文章没有标签，json_group_array 会返回 "[null]" 或者 "[]"，取决于 SQLite 版本和 json 扩展的编译选项，需要处理一下边界。

这个方案在 Room 2.5.0 + SQLite 3.39.0（Android API 33+ 的系统 SQLite，或者 bundled SQLite）上工作良好。对于低版本 Android，Room 的 createOpenHelper 可以配置 FrameworkSQLiteOpenHelperFactory，但系统 SQLite 版本不够的话 JSON 函数不支持。我最后的做法是依赖 androidx.sqlite:sqlite-bundled，把新版本的 SQLite 打进 APK，牺牲一点包体积换一致性。

实测数据：50 篇文章，每篇 3-5 个标签，用 @Relation 的方案平均 SQL 执行 51 次（1 次主查询 + 50 次子查询），耗时约 12-18ms（Pixel 4，debug 模式，有 trace overhead）。JSON 聚合方案单条 SQL，耗时 2-4ms。差距在数据量小的时候不明显，但文章数上到 200 之后，N+1 会线性恶化到 200+ 次查询，60ms 以上，而 JSON 方案仍然是单条，5-8ms。

另一个坑：Flow 与 N+1 的叠加伤害

我的原始需求是响应式查询，DAO 返回 Flow<List<ArticleWithTags>>，配合 Compose 的 collectAsState。这里 @Relation 的 N+1 问题会和 Flow 的刷新机制叠加，造成更频繁的数据库访问。

Room 的 Flow 返回是通过 InvalidationTracker 实现的。任何关联表的写入都会触发 Flow re-collect。在我的场景里，标签表是后台同步任务频繁更新的，每次同步新标签，articles 表其实没变，但 tags 和 article_tag_cross 变了，InvalidationTracker 会通知所有观察这些表的 Flow 重新查询。

于是出现这样的模式：后台每 5 分钟同步一次标签数据，前台 UI 的 Flow 触发 re-collect，@Relation 执行 1+N 次查询。用户可能只是在静止看文章列表，数据库却在反复刷。Profiler 里看到同步期间的 SQL 频率陡增，就是这个原因。

我试过用 distinctUntilChanged 在 Flow 链路上去重，但这只能解决 UI 层不刷新，不能阻止数据库查询本身。根本的解法还是减少单次查询的成本，或者把标签数据从实时关联中解耦。

最后的架构调整：文章列表只查文章基础字段，不 JOIN 标签。标签在点击进入详情页后再单独查，用 @Relation 也无所谓了，因为单篇文章的 N+1 是可以接受的。列表页如果需要显示标签预览，用一张反范化的冗余表，或者把标签名字符串直接存在文章表里，牺牲写一致性换读性能。

Room 3.0 会不会改

Room 2.6.0-alpha 的 release note 我逐条看过，没有提到 @Relation 的实现方式变更。Google I/O 2023 的 Android 数据库相关 session 里，重点在 Paging 3 和 Kotlin Flow 的整合，以及 RoomPagingSource 的优化。@Relation 的 N+1 问题似乎没有被当作高优先级事项。

从实现角度看，Room 要在编译期生成正确的单条 JOIN + 去重代码，确实比现在的分治方案复杂。特别是当 @Relation 嵌套多层，或者关联实体本身还有 @Relation 的时候，结果集的结构化折叠是个头疼的问题。现在的实现虽然粗暴，但正确性容易保证。

我个人不太认同这种"牺牲性能换 API 简洁"的权衡。N+1 问题在 ORM 领域被讨论了几十年，Hibernate 有 fetch join、MyBatis 有嵌套结果映射，都是给开发者显式控制加载策略的选项。Room 的 @Relation 目前完全没有这种灵活性，要么用（接受 N+1），要么不用（完全手写）。中间地带很窄，Map 返回类型尝试过，但没解决根本问题。

一些防御性写法

如果项目里已经在用 @Relation，并且数据量可控，没必要急着重构。但有几个检查点可以做：

在 DAO 层加 @Transaction 注解（虽然对性能无帮助，但确保原子性），然后在 debug 构建里用 androidx.room.roomRuntime 的 RoomSQLiteQuery 日志，或者直接用 StrictMode 检测主线程查询。更直接的是用 Android Studio 的 Database Inspector，看 SQL 执行历史，数一下关联查询的次数是否和 parent 行数匹配。

对于新写的关联查询，先评估 N 的最大可能值。如果是配置表、分类表这种 N 很小的场景，@Relation 完全够用。如果是用户生成内容、时间线、消息列表这种 N 可能很大的场景，提前考虑 JOIN 或者反范化。

如果决定手写 JOIN，注意 Room 对列名冲突的处理。SELECT * 在 JOIN 场景下会有同名列覆盖问题，建议显式列名加别名。Room 2.5.0 对 @ColumnInfo 的别名解析有改进，但嵌套对象里的同名字段仍然容易踩坑。

@Query("""
    SELECT 
        articles.id AS a_id, articles.title AS a_title,
        tags.id AS t_id, tags.name AS t_name
    FROM ...
""")

然后在 @Embedded 里用 prefix 或者手动映射，但 prefix 对复杂 JOIN 的支持有限，有时不得不拆扁平结构再组装。

回到那个新闻 App

我那个项目的最终状态是：列表页文章表独立查询，标签预览用文章表里的 tagPreview 冗余字段（同步时批量更新），详情页用 @Relation 查完整标签列表。后台同步任务用 WorkManager 触发，写操作集中在凌晨和用户手动刷新时。

这个方案不是最优雅的，但工程上可维护。Room 的 @Relation 仍然留在代码库里，只是被限制在 N=1 的场景。性能数据上，列表页从原来的 50+ 次查询降到 1 次，详情页保持 1+3~5 次可接受范围。

如果 Room 未来版本提供类似 fetch = FetchType.JOIN 的选项，我会第一时间试用。但就目前的版本（写到这的时候最新稳定版是 2.6.1），这个坑还在，文档里也不会告诉你背后的查询次数。只能自己 Profiler 里见真章。