android-room-database

Android Room 数据库

适用场景

• 当请求涉及以下内容时使用此技能：Android Room 数据库、Android DAO 查询迁移、Room 架构导出。
• 主要目标：建模 Room 实体、DAO、事务、迁移、架构导出，以及适合测试的本地持久化。
• 当难点在于架构设计、DAO 查询、事务、迁移或 Room 测试时，使用此技能。仅当主要工作是响应式 API 迁移，而非数据库契约本身时，才转交给 android-rxjava-to-coroutines-migration。
• 当范围扩大时，转交给以下技能：
• android-local-persistence-datastore
• android-testing-unit

工作流

1. 从持久化契约入手：实体、键、索引、关系，以及数据属于事实来源、缓存还是离线优先状态。
2. 明确建模 DAO 访问模式，包括事务边界、查询形态、分页和失效行为。
3. 更改实体前规划架构演进：导出的架构、迁移步骤、自动迁移适用性和破坏性回退策略。
4. 使用确定性测试验证迁移和查询行为，而不要认为 Room 注解已足够。
5. 只有在 Room 边界正确之后，才转交 DataStore、同步或响应式 API 相关问题。

防护措施

• 导出架构，并将其视为契约的一部分，而非可有可无的工具产物。
• 让实体专注于持久化；应映射到领域模型或 UI 模型，而不要向上层泄露表结构。
• 对必须保持一致的多步写入使用显式事务。
• 在正式版本中依赖迁移之前，先针对真实的旧架构测试迁移。

反模式

• 在整个应用中都将 Room 实体当作应用的领域模型。
• 修改架构时不导出，也不验证迁移路径。
• 当屏幕只需要范围较窄的投影时，仍编写宽泛的 SELECT * 查询。
• 将数据库、同步和响应式流迁移问题混为一个不加区分的任务。

审查重点

• 实体键、索引、关系和架构归属。
• DAO 查询形态、事务和失效行为。
• 迁移安全性、架构导出和测试覆盖率。
• Room 模型与更高层应用模型之间的清晰边界。

示例

顺利完成

• 场景：使用支持架构管理的实体持久化任务项和提醒标记。
• 命令：cd examples/orbittasks-compose && ./gradlew :app:testDebugUnitTest

边缘情况

• 场景：通过显式迁移路径从架构变更失败中恢复。
• 命令：python3 scripts/eval_triggers.py --skill android-room-database

故障恢复

• 场景：将 Room 请求与 DataStore、网络和现代化提示词分开处理。
• 命令：cd examples/orbittasks-xml && ./gradlew :app:testDebugUnitTest

完成检查清单

• 实体、DAO 和事务符合实际的持久化契约。
• 架构导出和迁移策略明确。
• 查询和迁移测试覆盖高风险路径。
• 将非 Room 相关问题转交处理，而非与数据库任务混在一起。

官方参考资料

• https://developer.android.com/training/data-storage/room
• https://developer.android.com/training/data-storage/room/migrating-db-versions
• https://developer.android.com/training/data-storage/room/accessing-data
• https://developer.android.com/training/data-storage/room/prepopulate
• https://developer.android.com/topic/performance/sqlite-performance-best-practices