據(jù)庫升級遷移實戰(zhàn)：從原理到避坑指南)
1. 從一次數(shù)據(jù)庫遷移事故說起為什么Room升級值得單獨拎出來講做Android開發(fā)的人幾乎都經(jīng)歷過這樣的場景App上線了一個版本本地數(shù)據(jù)庫表結(jié)構(gòu)設(shè)計得不太合理產(chǎn)品經(jīng)理又提了新需求需要加字段、改類型、拆表。你改完Entity編譯運行直接崩了——IllegalStateException: Room cannot verify the data integrity。更讓人頭疼的是用戶手機上已經(jīng)存了幾百兆的本地數(shù)據(jù)你不可能讓用戶卸載重裝。這就是Room升級要解決的核心問題在保證用戶數(shù)據(jù)不丟失的前提下安全地完成數(shù)據(jù)庫Schema的版本遷移。很多人對Room的印象停留在一個ORM框架寫寫注解就能用覺得升級無非就是改個version數(shù)字、加個Migration對象。但真正在線上環(huán)境跑過幾個版本迭代之后你會發(fā)現(xiàn)Room的遷移機制遠比想象中復(fù)雜。一個不小心輕則數(shù)據(jù)丟失重則線上大面積崩潰。而且Room的報錯信息往往非常隱晦它只會告訴你遷移失敗但具體哪張表、哪個字段、哪條SQL出了問題需要你自己一步步排查。這篇文章適合所有正在使用或準備使用Room的Android開發(fā)者。不管你是剛接觸Room的新手還是已經(jīng)寫過幾個Migration的老手我都會從底層原理到實戰(zhàn)操作把Room升級這件事徹底講透。包括Schema驗證機制、Migration的正確寫法、自動化遷移工具的使用、遷移測試方案、以及我在實際項目中踩過的那些坑。讀完你至少能搞清楚三件事Room升級到底在升什么、怎么升才安全、出了問題怎么排查。2. Room的Schema驗證機制升級失敗的根源在哪里2.1 編譯期與運行期的雙重校驗要理解Room升級為什么會失敗首先得搞清楚Room的Schema驗證是怎么工作的。Room的校驗分為兩個階段編譯期校驗和運行期校驗。編譯期Room的注解處理器會掃描所有Entity、Dao、Database注解生成對應(yīng)的Java實現(xiàn)類。同時它會把當前數(shù)據(jù)庫的Schema信息導(dǎo)出成一個JSON文件存放在app/schemas/目錄下。這個JSON文件非常關(guān)鍵它記錄了每個版本數(shù)據(jù)庫的完整結(jié)構(gòu)表名、字段名、字段類型、主鍵、索引、外鍵、默認值等等。運行期當App啟動、Room第一次訪問數(shù)據(jù)庫時它會做一次校驗讀取設(shè)備上現(xiàn)有數(shù)據(jù)庫的user_versionSQLite內(nèi)置的版本號和你代碼中Database(version N)聲明的版本號做對比。如果設(shè)備上的版本低于代碼版本Room就會觸發(fā)遷移流程如果版本一致Room會進一步校驗設(shè)備上數(shù)據(jù)庫的實際Schema是否和schema JSON文件中記錄的一致。如果不一致直接拋出IllegalStateException。這里有個很多人忽略的細節(jié)Room在運行期校驗Schema時比對的是設(shè)備上數(shù)據(jù)庫的真實結(jié)構(gòu)而不是你代碼里的Entity定義。也就是說即使你的Entity改對了但如果Migration執(zhí)行后數(shù)據(jù)庫的實際結(jié)構(gòu)和Schema JSON對不上照樣崩潰。2.2 Schema JSON文件的作用與生成邏輯Schema JSON文件是Room升級體系的核心樞紐。它的默認導(dǎo)出路徑是app/schemas/你的數(shù)據(jù)庫類全限定名/版本號.json。比如你的數(shù)據(jù)庫類叫AppDatabase包名是com.example.myapp那么版本1的Schema文件就在app/schemas/com.example.myapp.AppDatabase/1.json。這個文件的內(nèi)容大致長這樣{ formatVersion: 1, database: { version: 1, identityHash: abc123..., entities: [ { tableName: users, createSql: CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL, name TEXT NOT NULL, age INTEGER NOT NULL), fields: [ {fieldPath: id, columnName: id, affinity: INTEGER, notNull: true}, {fieldPath: name, columnName: name, affinity: TEXT, notNull: true}, {fieldPath: age, columnName: age, affinity: INTEGER, notNull: true} ], primaryKey: {columnNames: [id], autoGenerate: true} } ], views: [], setupQueries: [...] } }其中identityHash是一個關(guān)鍵字段。它是Room根據(jù)整個Schema內(nèi)容計算出來的哈希值。每次你修改Entity重新編譯后生成的Schema JSON的identityHash都會變化。Room在運行期就是通過比對這個哈希值來判斷Schema是否發(fā)生了變更。如果你沒有正確配置Schema的導(dǎo)出路徑或者把exportSchema設(shè)成了false那么Room在運行期就無法進行完整的Schema校驗遷移出問題的概率會大大增加。所以我的建議是永遠把exportSchema設(shè)為true并且把app/schemas/目錄納入版本控制。2.3 版本號不匹配時的三種走向當設(shè)備上的數(shù)據(jù)庫版本和代碼聲明的版本不一致時Room會根據(jù)情況走三條不同的路徑第一條路徑設(shè)備版本 代碼版本且找到了對應(yīng)的Migration。Room會按照版本號從小到大依次執(zhí)行Migration比如從版本1升到版本3它會先執(zhí)行MIGRATION_1_2再執(zhí)行MIGRATION_2_3。每一步執(zhí)行完畢后Room會更新數(shù)據(jù)庫的user_version。第二條路徑設(shè)備版本 代碼版本但沒有找到對應(yīng)的Migration。這時候Room會檢查你是否啟用了fallbackToDestructiveMigration()。如果啟用了Room會直接刪除所有表然后重建數(shù)據(jù)全部丟失。如果沒有啟用直接拋出IllegalStateExceptionApp崩潰。第三條路徑設(shè)備版本 代碼版本。這種情況通常發(fā)生在用戶安裝了舊版本App比如從應(yīng)用商店回滾了版本。Room同樣會拋出異常因為它不知道如何處理降級。你可以通過fallbackToDestructiveMigrationOnDowngrade()來處理這種情況但同樣會丟失數(shù)據(jù)。理解了這三條路徑你就明白了Migration的本質(zhì)就是告訴Room從版本A到版本B數(shù)據(jù)庫結(jié)構(gòu)發(fā)生了哪些變化需要執(zhí)行哪些SQL來完成這個變化。3. Migration的正確寫法從手動遷移到自動化方案3.1 手動編寫Migration的完整流程手動Migration是最基礎(chǔ)也最可控的方式。假設(shè)我們有一個users表版本1的結(jié)構(gòu)是id name版本2需要增加一個email字段同時給name字段加一個索引。第一步修改EntityEntity(tableName users, indices [Index(value [name])]) data class User( PrimaryKey(autoGenerate true) val id: Long 0, val name: String, val email: String )第二步升級數(shù)據(jù)庫版本號Database(entities [User::class], version 2, exportSchema true) abstract class AppDatabase : RoomDatabase() { abstract fun userDao(): UserDao }第三步編寫Migrationval MIGRATION_1_2 object : Migration(1, 2) { override fun migrate(database: SupportSQLiteDatabase) { // 添加新字段注意設(shè)置默認值 database.execSQL(ALTER TABLE users ADD COLUMN email TEXT NOT NULL DEFAULT ) // 創(chuàng)建索引 database.execSQL(CREATE INDEX IF NOT EXISTS index_users_name ON users (name)) } }第四步在構(gòu)建數(shù)據(jù)庫時注冊MigrationRoom.databaseBuilder(context, AppDatabase::class.java, app_database) .addMigrations(MIGRATION_1_2) .build()這四步看起來簡單但每一步都有坑。我逐個說。關(guān)于ALTER TABLE ADD COLUMN的坑SQLite的ALTER TABLE能力非常有限它只支持ADD COLUMN、RENAME TABLE、RENAME COLUMN這幾種操作。如果你想刪除字段、修改字段類型、修改約束SQLite是不支持的。這時候你需要用創(chuàng)建新表 - 拷貝數(shù)據(jù) - 刪除舊表 - 重命名新表的方式來完成。關(guān)于NOT NULL字段的默認值如果你新增的字段是NOT NULL的必須提供DEFAULT值否則已有數(shù)據(jù)的行會違反約束。而且這個默認值必須和Entity中聲明的defaultValue一致否則Schema校驗會失敗。關(guān)于索引命名Room生成的索引名有固定格式index_表名_字段名。如果你手動創(chuàng)建的索引名和Room期望的不一致Schema校驗同樣會失敗。所以最穩(wěn)妥的方式是先寫好Entity編譯一次然后去生成的Schema JSON文件里看Room期望的createSql是什么照著寫Migration。3.2 復(fù)雜遷移場景拆表、合表與數(shù)據(jù)轉(zhuǎn)換實際項目中簡單的加字段只是冰山一角。更復(fù)雜的情況包括把一張寬表拆成兩張表、把兩張表合并成一張、修改主鍵、修改字段類型并轉(zhuǎn)換數(shù)據(jù)。以拆表為例。假設(shè)版本1有一個users表包含id, name, email, phone。版本2需要把email和phone拆到單獨的contacts表中。這種遷移沒法用一條ALTER TABLE搞定需要分步驟val MIGRATION_1_2 object : Migration(1, 2) { override fun migrate(database: SupportSQLiteDatabase) { // 1. 創(chuàng)建新表 database.execSQL( CREATE TABLE IF NOT EXISTS contacts ( id INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL, user_id INTEGER NOT NULL, email TEXT NOT NULL DEFAULT , phone TEXT NOT NULL DEFAULT , FOREIGN KEY(user_id) REFERENCES users(id) ON DELETE CASCADE ) ) // 2. 從舊表拷貝數(shù)據(jù) database.execSQL( INSERT INTO contacts (user_id, email, phone) SELECT id, email, phone FROM users ) // 3. 重建users表去掉email和phone字段 database.execSQL( CREATE TABLE users_new ( id INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL, name TEXT NOT NULL ) ) database.execSQL(INSERT INTO users_new (id, name) SELECT id, name FROM users) database.execSQL(DROP TABLE users) database.execSQL(ALTER TABLE users_new RENAME TO users) // 4. 創(chuàng)建索引 database.execSQL(CREATE INDEX IF NOT EXISTS index_contacts_user_id ON contacts (user_id)) } }這段代碼有幾個關(guān)鍵點第一創(chuàng)建新表時的SQL必須和Room生成的完全一致包括字段順序、類型、約束、外鍵。第二拷貝數(shù)據(jù)時要注意字段映射關(guān)系別搞錯了列。第三刪除舊表之前一定要確保數(shù)據(jù)已經(jīng)完整拷貝否則就是不可逆的數(shù)據(jù)丟失。3.3 AutoMigration讓Room幫你寫遷移代碼從Room 2.4.0開始官方提供了AutoMigration功能。你只需要在Database注解中聲明autoMigrationsRoom就會在編譯期自動生成Migration代碼。Database( entities [User::class], version 2, exportSchema true, autoMigrations [ AutoMigration(from 1, to 2) ] ) abstract class AppDatabase : RoomDatabase()AutoMigration能處理大部分常見場景添加字段、刪除字段、創(chuàng)建索引、刪除索引、重命名表、重命名字段。但它也有局限性它無法處理需要數(shù)據(jù)轉(zhuǎn)換的場景比如把String類型的日期轉(zhuǎn)成Long時間戳或者拆表合表。對于AutoMigration無法處理的場景你可以提供一個AutoMigrationSpec來補充RenameColumn(tableName users, fromColumnName username, toColumnName name) static class MyAutoMigrationSpec : AutoMigrationSpec然后在Database中引用autoMigrations [ AutoMigration(from 1, to 2, spec MyAutoMigrationSpec::class) ]我的建議是能用AutoMigration就用AutoMigration但一定要檢查生成的Schema JSON和遷移測試結(jié)果。AutoMigration雖然方便但它生成的SQL不一定是最優(yōu)的而且在復(fù)雜場景下可能生成錯誤的遷移邏輯。4. 遷移測試上線前的最后一道防線4.1 為什么必須寫遷移測試我見過太多團隊Migration寫完就直接上線結(jié)果線上崩潰率飆升。原因很簡單Migration的代碼路徑在開發(fā)階段幾乎不會被觸發(fā)。你本地開發(fā)時數(shù)據(jù)庫版本永遠是最新的除非你手動降級或者用舊版本App覆蓋安裝否則根本走不到Migration邏輯。而線上用戶的情況千奇百怪有人從版本1直接升到版本5有人從版本3升到版本4有人卸載重裝有人清除了數(shù)據(jù)。每一種路徑都可能觸發(fā)不同的Migration組合。如果不寫測試你根本不知道這些組合能不能正常工作。Room官方提供了一個room-testing庫專門用來做遷移測試。它的原理是用舊版本的Schema創(chuàng)建一個數(shù)據(jù)庫插入一些測試數(shù)據(jù)然后執(zhí)行Migration最后校驗新數(shù)據(jù)庫的結(jié)構(gòu)和數(shù)據(jù)是否符合預(yù)期。4.2 用MigrationTestHelper搭建測試用例首先添加依賴androidTestImplementation androidx.room:room-testing:2.6.1然后編寫測試RunWith(AndroidJUnit4::class) class MigrationTest { private val TEST_DB migration-test get:Rule val helper: MigrationTestHelper MigrationTestHelper( InstrumentationRegistry.getInstrumentation(), AppDatabase::class.java.canonicalName, FrameworkSQLiteOpenHelperFactory() ) Test fun migrate1To2() { // 1. 用版本1的Schema創(chuàng)建數(shù)據(jù)庫 helper.createDatabase(TEST_DB, 1).apply { execSQL(INSERT INTO users (name) VALUES (張三)) execSQL(INSERT INTO users (name) VALUES (李四)) close() } // 2. 執(zhí)行遷移到版本2 val db helper.runMigrationsAndValidate(TEST_DB, 2, true, MIGRATION_1_2) // 3. 校驗數(shù)據(jù) val cursor db.query(SELECT * FROM users) assertEquals(2, cursor.count) cursor.moveToFirst() assertEquals(張三, cursor.getString(cursor.getColumnIndex(name))) assertEquals(, cursor.getString(cursor.getColumnIndex(email))) cursor.close() } }runMigrationsAndValidate這個方法非常關(guān)鍵。它做了三件事執(zhí)行Migration、校驗新數(shù)據(jù)庫的Schema是否和Schema JSON一致、返回可查詢的數(shù)據(jù)庫對象。如果Schema校驗失敗測試會直接報錯告訴你哪里不一致。4.3 多版本跳躍遷移的測試策略實際項目中用戶可能從任意一個歷史版本升級到最新版本。你需要測試所有可能的遷移路徑。比如當前最新版本是4歷史版本有1、2、3那么需要測試的路徑包括1-4、2-4、3-4。Room的MigrationTestHelper支持傳入多個MigrationTest fun migrate1To4() { helper.createDatabase(TEST_DB, 1).apply { execSQL(INSERT INTO users (name) VALUES (王五)) close() } val db helper.runMigrationsAndValidate( TEST_DB, 4, true, MIGRATION_1_2, MIGRATION_2_3, MIGRATION_3_4 ) // 校驗數(shù)據(jù)... }這里有個經(jīng)驗不要只測試相鄰版本的遷移一定要測試跨版本遷移。因為跨版本遷移會依次執(zhí)行多個Migration中間任何一步出問題都會導(dǎo)致最終失敗。而且跨版本遷移時數(shù)據(jù)會經(jīng)過多次轉(zhuǎn)換更容易出現(xiàn)數(shù)據(jù)丟失或類型不匹配的問題。5. 線上環(huán)境遷移失敗的排查鏈路5.1 從崩潰日志定位問題線上Migration失敗時崩潰日志通常長這樣java.lang.IllegalStateException: Room cannot verify the data integrity. Looks like youve changed schema but forgot to update the version number. You can simply fix this by increasing the version number. Expected: TableInfo{nameusers, columns{idColumn{nameid, typeINTEGER, affinity3, notNulltrue, primaryKeyPosition1}, nameColumn{namename, typeTEXT, affinity2, notNulltrue, primaryKeyPosition0}}, foreignKeys[], indices[]} Found: TableInfo{nameusers, columns{idColumn{nameid, typeINTEGER, affinity3, notNulltrue, primaryKeyPosition1}, nameColumn{namename, typeTEXT, affinity2, notNulltrue, primaryKeyPosition0}, emailColumn{nameemail, typeTEXT, affinity2, notNulltrue, primaryKeyPosition0}}, foreignKeys[], indices[]}這段日志的關(guān)鍵信息在Expected和Found兩個部分。Expected是Room期望的Schema來自Schema JSONFound是設(shè)備上數(shù)據(jù)庫的實際Schema。對比兩者你就能發(fā)現(xiàn)差異Found中多了一個email字段說明Migration執(zhí)行了添加字段的操作但Schema JSON中沒有這個字段說明你忘記升級版本號或者忘記重新編譯導(dǎo)出Schema。常見的崩潰原因和排查方向崩潰信息關(guān)鍵詞可能原因排查方向cannot verify the data integritySchema不一致對比Expected和Found的差異A migration from X to Y was required but not found缺少Migration檢查addMigrations是否注冊了對應(yīng)版本no such table表未創(chuàng)建檢查Migration中是否創(chuàng)建了新表no such column字段未添加檢查ALTER TABLE語句UNIQUE constraint failed唯一約束沖突檢查數(shù)據(jù)是否有重復(fù)值FOREIGN KEY constraint failed外鍵約束沖突檢查關(guān)聯(lián)數(shù)據(jù)是否存在5.2 用Schema JSON做差異比對當崩潰日志不夠清晰時最有效的排查方式是直接比對Schema JSON文件。假設(shè)你從版本2升到版本3失敗了你可以打開app/schemas/com.example.AppDatabase/2.json和3.json逐字段對比。我通常會關(guān)注這幾個地方表名是否一致、字段名是否一致、字段類型是否一致、notNull約束是否一致、默認值是否一致、索引是否一致、外鍵是否一致。任何一處不一致都會導(dǎo)致校驗失敗。有個小技巧你可以用diff命令或者IDE的對比工具來快速找出兩個JSON文件的差異。如果差異很多說明你的Entity改動很大需要仔細檢查每一處。5.3 降級與異常兜底方案即使做了充分的測試線上仍然可能出現(xiàn)意料之外的遷移失敗。這時候你需要一個兜底方案。最常見的做法是捕獲遷移異常降級到 destructive migration。Room.databaseBuilder(context, AppDatabase::class.java, app_database) .addMigrations(MIGRATION_1_2, MIGRATION_2_3) .fallbackToDestructiveMigrationOnDowngrade() .build()但fallbackToDestructiveMigration會丟失所有數(shù)據(jù)只適合那些本地數(shù)據(jù)不重要、可以從服務(wù)器重新拉取的場景。如果本地數(shù)據(jù)很重要你需要更精細的兜底策略比如在遷移失敗時把舊數(shù)據(jù)庫文件備份到另一個路徑然后創(chuàng)建一個新數(shù)據(jù)庫再嘗試從備份中恢復(fù)數(shù)據(jù)。還有一種做法是在Application啟動時先檢查數(shù)據(jù)庫版本如果發(fā)現(xiàn)異常提前處理。比如try { val db Room.databaseBuilder(...).build() db.openHelper.writableDatabase } catch (e: IllegalStateException) { // 遷移失敗執(zhí)行兜底邏輯 handleMigrationFailure() }6. 那些年我踩過的Room升級坑6.1 忘記導(dǎo)出Schema導(dǎo)致的連鎖反應(yīng)早期做項目時我覺得exportSchema沒什么用就設(shè)成了false。結(jié)果有一次線上遷移失敗我想排查問題發(fā)現(xiàn)根本沒有Schema JSON文件可以對比。只能靠猜效率極低。后來我把所有項目的exportSchema都改成了true并且把app/schemas/目錄提交到了Git。這里有個細節(jié)如果你用的是KSP而不是KAPTSchema的導(dǎo)出路徑可能需要在build.gradle中額外配置ksp { arg(room.schemaLocation, $projectDir/schemas) }另外Schema JSON文件必須納入版本控制。因為遷移測試需要用到歷史版本的Schema文件如果你不提交CI上跑測試時會找不到舊版本的Schema測試直接失敗。6.2 字段默認值與Entity聲明不一致這個問題非常隱蔽。假設(shè)你在Entity中聲明了一個字段ColumnInfo(defaultValue 0) val age: Int 0然后在Migration中寫database.execSQL(ALTER TABLE users ADD COLUMN age INTEGER NOT NULL DEFAULT 1)注意Entity中聲明的默認值是0但Migration中寫的默認值是1。這兩個不一致Schema校驗會失敗。而且報錯信息不會直接告訴你默認值不一致只會說Schema不匹配你需要自己去對比JSON文件才能發(fā)現(xiàn)。所以我的經(jīng)驗是Migration中的SQL語句最好直接從Schema JSON文件中復(fù)制createSql然后稍作修改。這樣能最大程度保證一致性。6.3 主鍵自增與數(shù)據(jù)拷貝的沖突在做拆表遷移時我遇到過一個問題新表的主鍵是AUTOINCREMENT的我從舊表拷貝數(shù)據(jù)時手動指定了id值。結(jié)果新表的sqlite_sequence沒有更新后續(xù)插入數(shù)據(jù)時自增ID從1開始導(dǎo)致主鍵沖突。解決方案是在拷貝數(shù)據(jù)后手動更新sqlite_sequenceUPDATE sqlite_sequence SET seq (SELECT MAX(id) FROM contacts) WHERE name contacts或者更簡單的做法拷貝數(shù)據(jù)時不指定id讓SQLite自動生成。但這樣會丟失舊表中的ID關(guān)聯(lián)關(guān)系需要根據(jù)實際情況權(quán)衡。6.4 多模塊項目中的Schema路徑?jīng)_突在組件化項目中數(shù)據(jù)庫可能被多個模塊引用。如果每個模塊都配置了room.schemaLocation可能會出現(xiàn)Schema文件路徑?jīng)_突或者覆蓋的問題。我的做法是只在app模塊中配置Schema導(dǎo)出路徑其他模塊通過api依賴傳遞Room的注解處理器。同時確保所有模塊使用的Room版本一致避免因為版本差異導(dǎo)致Schema格式不兼容。6.5 遷移耗時過長導(dǎo)致的ANR當數(shù)據(jù)庫數(shù)據(jù)量很大時Migration可能會執(zhí)行很長時間。如果Migration在主線程執(zhí)行直接ANR。Room默認的databaseBuilder是在主線程構(gòu)建的但實際的數(shù)據(jù)庫操作是在子線程執(zhí)行的。不過Migration本身是在打開數(shù)據(jù)庫時執(zhí)行的如果你在Application的onCreate中直接訪問數(shù)據(jù)庫Migration就會在主線程執(zhí)行。解決方案是不要在Application啟動時同步訪問數(shù)據(jù)庫。把數(shù)據(jù)庫的初始化放到子線程或者使用RoomDatabase.Builder的setQueryExecutor和setTransactionExecutor來指定執(zhí)行器。Room.databaseBuilder(context, AppDatabase::class.java, app_database) .setQueryExecutor(Executors.newFixedThreadPool(4)) .setTransactionExecutor(Executors.newSingleThreadExecutor()) .build()另外對于大數(shù)據(jù)量的遷移可以考慮分批處理。比如每次只遷移1000條數(shù)據(jù)遷移完一批就更新一次版本號避免一次性遷移太多導(dǎo)致超時。7. 面向未來的Room升級策略7.1 建立Schema變更的規(guī)范流程經(jīng)過多個項目的迭代我總結(jié)了一套Schema變更的規(guī)范流程團隊里每個人都必須遵守修改Entity之前先確認當前數(shù)據(jù)庫版本號。修改Entity之后立即升級版本號并編寫對應(yīng)的Migration。編譯項目檢查生成的Schema JSON文件確認identityHash已更新。編寫遷移測試覆蓋相鄰版本和跨版本遷移。在CI上運行遷移測試確保所有歷史版本的遷移路徑都能通過。Code Review時重點檢查Migration的SQL語句和Schema JSON的差異。這套流程看起來繁瑣但能避免90%以上的遷移問題。尤其是第3步和第4步很多團隊會忽略結(jié)果上線后才發(fā)現(xiàn)問題。7.2 用CI自動化遷移測試手動跑遷移測試容易遺漏最好把它集成到CI流程中。在build.gradle中配置android { testOptions { unitTests { includeAndroidResources true } } }然后在CI腳本中添加./gradlew connectedAndroidTest這樣每次提交代碼時CI會自動運行所有遷移測試。如果某個遷移路徑失敗了CI會直接報錯阻止合并。對于沒有條件跑儀器化測試的團隊可以考慮用Robolectric來跑遷移測試。Room的MigrationTestHelper也支持Robolectric雖然不如真機測試準確但能覆蓋大部分場景。7.3 數(shù)據(jù)庫版本管理的長期維護建議隨著App迭代數(shù)據(jù)庫版本會越來越多Migration文件也會越積越多。如果不加以管理最終會變成一團亂麻。我的建議是第一為每個Migration寫注釋說明這個版本做了什么變更、為什么做這個變更。比如// 版本2 - 3新增用戶頭像字段用于支持個性化推薦 val MIGRATION_2_3 object : Migration(2, 3) { ... }第二定期整理Migration文件把相關(guān)的Migration放在同一個文件中按版本號排序。不要把所有Migration都堆在一個文件里。第三考慮使用Room的AutoMigration來減少手動代碼。對于簡單的加字段、加索引AutoMigration完全夠用。只有復(fù)雜的數(shù)據(jù)轉(zhuǎn)換才需要手動寫Migration。第四保留所有歷史版本的Schema JSON文件。這些文件是遷移測試的基礎(chǔ)也是排查線上問題的關(guān)鍵依據(jù)。不要因為文件多就刪除它們。第五在數(shù)據(jù)庫版本達到一定數(shù)量后考慮做一次基線合并。比如當前最新版本是10你可以把版本1到10的Migration合并成一個從1直接到10的Migration減少遷移路徑的復(fù)雜度。但這樣做的前提是你確定沒有用戶還在使用版本1到9的App。 Android Room數(shù)據(jù)庫升級遷移實戰(zhàn)：從原理到避坑指南
1. 從一次數(shù)據(jù)庫遷移事故說起為什么Room升級值得單獨拎出來講做Android開發(fā)的人幾乎都經(jīng)歷過這樣的場景App上線了一個版本本地數(shù)據(jù)庫表結(jié)構(gòu)設(shè)計得不太合理產(chǎn)品經(jīng)理又提了新需求需要加字段、改類型、拆表。你改完Entity編譯運行直接崩了——IllegalStateException: Room cannot verify the data integrity。更讓人頭疼的是用戶手機上已經(jīng)存了幾百兆的本地數(shù)據(jù)你不可能讓用戶卸載重裝。這就是Room升級要解決的核心問題在保證用戶數(shù)據(jù)不丟失的前提下安全地完成數(shù)據(jù)庫Schema的版本遷移。很多人對Room的印象停留在一個ORM框架寫寫注解就能用覺得升級無非就是改個version數(shù)字、加個Migration對象。但真正在線上環(huán)境跑過幾個版本迭代之后你會發(fā)現(xiàn)Room的遷移機制遠比想象中復(fù)雜。一個不小心輕則數(shù)據(jù)丟失重則線上大面積崩潰。而且Room的報錯信息往往非常隱晦它只會告訴你遷移失敗但具體哪張表、哪個字段、哪條SQL出了問題需要你自己一步步排查。這篇文章適合所有正在使用或準備使用Room的Android開發(fā)者。不管你是剛接觸Room的新手還是已經(jīng)寫過幾個Migration的老手我都會從底層原理到實戰(zhàn)操作把Room升級這件事徹底講透。包括Schema驗證機制、Migration的正確寫法、自動化遷移工具的使用、遷移測試方案、以及我在實際項目中踩過的那些坑。讀完你至少能搞清楚三件事Room升級到底在升什么、怎么升才安全、出了問題怎么排查。2. Room的Schema驗證機制升級失敗的根源在哪里2.1 編譯期與運行期的雙重校驗要理解Room升級為什么會失敗首先得搞清楚Room的Schema驗證是怎么工作的。Room的校驗分為兩個階段編譯期校驗和運行期校驗。編譯期Room的注解處理器會掃描所有Entity、Dao、Database注解生成對應(yīng)的Java實現(xiàn)類。同時它會把當前數(shù)據(jù)庫的Schema信息導(dǎo)出成一個JSON文件存放在app/schemas/目錄下。這個JSON文件非常關(guān)鍵它記錄了每個版本數(shù)據(jù)庫的完整結(jié)構(gòu)表名、字段名、字段類型、主鍵、索引、外鍵、默認值等等。運行期當App啟動、Room第一次訪問數(shù)據(jù)庫時它會做一次校驗讀取設(shè)備上現(xiàn)有數(shù)據(jù)庫的user_versionSQLite內(nèi)置的版本號和你代碼中Database(version N)聲明的版本號做對比。如果設(shè)備上的版本低于代碼版本Room就會觸發(fā)遷移流程如果版本一致Room會進一步校驗設(shè)備上數(shù)據(jù)庫的實際Schema是否和schema JSON文件中記錄的一致。如果不一致直接拋出IllegalStateException。這里有個很多人忽略的細節(jié)Room在運行期校驗Schema時比對的是設(shè)備上數(shù)據(jù)庫的真實結(jié)構(gòu)而不是你代碼里的Entity定義。也就是說即使你的Entity改對了但如果Migration執(zhí)行后數(shù)據(jù)庫的實際結(jié)構(gòu)和Schema JSON對不上照樣崩潰。2.2 Schema JSON文件的作用與生成邏輯Schema JSON文件是Room升級體系的核心樞紐。它的默認導(dǎo)出路徑是app/schemas/你的數(shù)據(jù)庫類全限定名/版本號.json。比如你的數(shù)據(jù)庫類叫AppDatabase包名是com.example.myapp那么版本1的Schema文件就在app/schemas/com.example.myapp.AppDatabase/1.json。這個文件的內(nèi)容大致長這樣{ formatVersion: 1, database: { version: 1, identityHash: abc123..., entities: [ { tableName: users, createSql: CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL, name TEXT NOT NULL, age INTEGER NOT NULL), fields: [ {fieldPath: id, columnName: id, affinity: INTEGER, notNull: true}, {fieldPath: name, columnName: name, affinity: TEXT, notNull: true}, {fieldPath: age, columnName: age, affinity: INTEGER, notNull: true} ], primaryKey: {columnNames: [id], autoGenerate: true} } ], views: [], setupQueries: [...] } }其中identityHash是一個關(guān)鍵字段。它是Room根據(jù)整個Schema內(nèi)容計算出來的哈希值。每次你修改Entity重新編譯后生成的Schema JSON的identityHash都會變化。Room在運行期就是通過比對這個哈希值來判斷Schema是否發(fā)生了變更。如果你沒有正確配置Schema的導(dǎo)出路徑或者把exportSchema設(shè)成了false那么Room在運行期就無法進行完整的Schema校驗遷移出問題的概率會大大增加。所以我的建議是永遠把exportSchema設(shè)為true并且把app/schemas/目錄納入版本控制。2.3 版本號不匹配時的三種走向當設(shè)備上的數(shù)據(jù)庫版本和代碼聲明的版本不一致時Room會根據(jù)情況走三條不同的路徑第一條路徑設(shè)備版本 代碼版本且找到了對應(yīng)的Migration。Room會按照版本號從小到大依次執(zhí)行Migration比如從版本1升到版本3它會先執(zhí)行MIGRATION_1_2再執(zhí)行MIGRATION_2_3。每一步執(zhí)行完畢后Room會更新數(shù)據(jù)庫的user_version。第二條路徑設(shè)備版本 代碼版本但沒有找到對應(yīng)的Migration。這時候Room會檢查你是否啟用了fallbackToDestructiveMigration()。如果啟用了Room會直接刪除所有表然后重建數(shù)據(jù)全部丟失。如果沒有啟用直接拋出IllegalStateExceptionApp崩潰。第三條路徑設(shè)備版本 代碼版本。這種情況通常發(fā)生在用戶安裝了舊版本App比如從應(yīng)用商店回滾了版本。Room同樣會拋出異常因為它不知道如何處理降級。你可以通過fallbackToDestructiveMigrationOnDowngrade()來處理這種情況但同樣會丟失數(shù)據(jù)。理解了這三條路徑你就明白了Migration的本質(zhì)就是告訴Room從版本A到版本B數(shù)據(jù)庫結(jié)構(gòu)發(fā)生了哪些變化需要執(zhí)行哪些SQL來完成這個變化。3. Migration的正確寫法從手動遷移到自動化方案3.1 手動編寫Migration的完整流程手動Migration是最基礎(chǔ)也最可控的方式。假設(shè)我們有一個users表版本1的結(jié)構(gòu)是id name版本2需要增加一個email字段同時給name字段加一個索引。第一步修改EntityEntity(tableName users, indices [Index(value [name])]) data class User( PrimaryKey(autoGenerate true) val id: Long 0, val name: String, val email: String )第二步升級數(shù)據(jù)庫版本號Database(entities [User::class], version 2, exportSchema true) abstract class AppDatabase : RoomDatabase() { abstract fun userDao(): UserDao }第三步編寫Migrationval MIGRATION_1_2 object : Migration(1, 2) { override fun migrate(database: SupportSQLiteDatabase) { // 添加新字段注意設(shè)置默認值 database.execSQL(ALTER TABLE users ADD COLUMN email TEXT NOT NULL DEFAULT ) // 創(chuàng)建索引 database.execSQL(CREATE INDEX IF NOT EXISTS index_users_name ON users (name)) } }第四步在構(gòu)建數(shù)據(jù)庫時注冊MigrationRoom.databaseBuilder(context, AppDatabase::class.java, app_database) .addMigrations(MIGRATION_1_2) .build()這四步看起來簡單但每一步都有坑。我逐個說。關(guān)于ALTER TABLE ADD COLUMN的坑SQLite的ALTER TABLE能力非常有限它只支持ADD COLUMN、RENAME TABLE、RENAME COLUMN這幾種操作。如果你想刪除字段、修改字段類型、修改約束SQLite是不支持的。這時候你需要用創(chuàng)建新表 - 拷貝數(shù)據(jù) - 刪除舊表 - 重命名新表的方式來完成。關(guān)于NOT NULL字段的默認值如果你新增的字段是NOT NULL的必須提供DEFAULT值否則已有數(shù)據(jù)的行會違反約束。而且這個默認值必須和Entity中聲明的defaultValue一致否則Schema校驗會失敗。關(guān)于索引命名Room生成的索引名有固定格式index_表名_字段名。如果你手動創(chuàng)建的索引名和Room期望的不一致Schema校驗同樣會失敗。所以最穩(wěn)妥的方式是先寫好Entity編譯一次然后去生成的Schema JSON文件里看Room期望的createSql是什么照著寫Migration。3.2 復(fù)雜遷移場景拆表、合表與數(shù)據(jù)轉(zhuǎn)換實際項目中簡單的加字段只是冰山一角。更復(fù)雜的情況包括把一張寬表拆成兩張表、把兩張表合并成一張、修改主鍵、修改字段類型并轉(zhuǎn)換數(shù)據(jù)。以拆表為例。假設(shè)版本1有一個users表包含id, name, email, phone。版本2需要把email和phone拆到單獨的contacts表中。這種遷移沒法用一條ALTER TABLE搞定需要分步驟val MIGRATION_1_2 object : Migration(1, 2) { override fun migrate(database: SupportSQLiteDatabase) { // 1. 創(chuàng)建新表 database.execSQL( CREATE TABLE IF NOT EXISTS contacts ( id INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL, user_id INTEGER NOT NULL, email TEXT NOT NULL DEFAULT , phone TEXT NOT NULL DEFAULT , FOREIGN KEY(user_id) REFERENCES users(id) ON DELETE CASCADE ) ) // 2. 從舊表拷貝數(shù)據(jù) database.execSQL( INSERT INTO contacts (user_id, email, phone) SELECT id, email, phone FROM users ) // 3. 重建users表去掉email和phone字段 database.execSQL( CREATE TABLE users_new ( id INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL, name TEXT NOT NULL ) ) database.execSQL(INSERT INTO users_new (id, name) SELECT id, name FROM users) database.execSQL(DROP TABLE users) database.execSQL(ALTER TABLE users_new RENAME TO users) // 4. 創(chuàng)建索引 database.execSQL(CREATE INDEX IF NOT EXISTS index_contacts_user_id ON contacts (user_id)) } }這段代碼有幾個關(guān)鍵點第一創(chuàng)建新表時的SQL必須和Room生成的完全一致包括字段順序、類型、約束、外鍵。第二拷貝數(shù)據(jù)時要注意字段映射關(guān)系別搞錯了列。第三刪除舊表之前一定要確保數(shù)據(jù)已經(jīng)完整拷貝否則就是不可逆的數(shù)據(jù)丟失。3.3 AutoMigration讓Room幫你寫遷移代碼從Room 2.4.0開始官方提供了AutoMigration功能。你只需要在Database注解中聲明autoMigrationsRoom就會在編譯期自動生成Migration代碼。Database( entities [User::class], version 2, exportSchema true, autoMigrations [ AutoMigration(from 1, to 2) ] ) abstract class AppDatabase : RoomDatabase()AutoMigration能處理大部分常見場景添加字段、刪除字段、創(chuàng)建索引、刪除索引、重命名表、重命名字段。但它也有局限性它無法處理需要數(shù)據(jù)轉(zhuǎn)換的場景比如把String類型的日期轉(zhuǎn)成Long時間戳或者拆表合表。對于AutoMigration無法處理的場景你可以提供一個AutoMigrationSpec來補充RenameColumn(tableName users, fromColumnName username, toColumnName name) static class MyAutoMigrationSpec : AutoMigrationSpec然后在Database中引用autoMigrations [ AutoMigration(from 1, to 2, spec MyAutoMigrationSpec::class) ]我的建議是能用AutoMigration就用AutoMigration但一定要檢查生成的Schema JSON和遷移測試結(jié)果。AutoMigration雖然方便但它生成的SQL不一定是最優(yōu)的而且在復(fù)雜場景下可能生成錯誤的遷移邏輯。4. 遷移測試上線前的最后一道防線4.1 為什么必須寫遷移測試我見過太多團隊Migration寫完就直接上線結(jié)果線上崩潰率飆升。原因很簡單Migration的代碼路徑在開發(fā)階段幾乎不會被觸發(fā)。你本地開發(fā)時數(shù)據(jù)庫版本永遠是最新的除非你手動降級或者用舊版本App覆蓋安裝否則根本走不到Migration邏輯。而線上用戶的情況千奇百怪有人從版本1直接升到版本5有人從版本3升到版本4有人卸載重裝有人清除了數(shù)據(jù)。每一種路徑都可能觸發(fā)不同的Migration組合。如果不寫測試你根本不知道這些組合能不能正常工作。Room官方提供了一個room-testing庫專門用來做遷移測試。它的原理是用舊版本的Schema創(chuàng)建一個數(shù)據(jù)庫插入一些測試數(shù)據(jù)然后執(zhí)行Migration最后校驗新數(shù)據(jù)庫的結(jié)構(gòu)和數(shù)據(jù)是否符合預(yù)期。4.2 用MigrationTestHelper搭建測試用例首先添加依賴androidTestImplementation androidx.room:room-testing:2.6.1然后編寫測試RunWith(AndroidJUnit4::class) class MigrationTest { private val TEST_DB migration-test get:Rule val helper: MigrationTestHelper MigrationTestHelper( InstrumentationRegistry.getInstrumentation(), AppDatabase::class.java.canonicalName, FrameworkSQLiteOpenHelperFactory() ) Test fun migrate1To2() { // 1. 用版本1的Schema創(chuàng)建數(shù)據(jù)庫 helper.createDatabase(TEST_DB, 1).apply { execSQL(INSERT INTO users (name) VALUES (張三)) execSQL(INSERT INTO users (name) VALUES (李四)) close() } // 2. 執(zhí)行遷移到版本2 val db helper.runMigrationsAndValidate(TEST_DB, 2, true, MIGRATION_1_2) // 3. 校驗數(shù)據(jù) val cursor db.query(SELECT * FROM users) assertEquals(2, cursor.count) cursor.moveToFirst() assertEquals(張三, cursor.getString(cursor.getColumnIndex(name))) assertEquals(, cursor.getString(cursor.getColumnIndex(email))) cursor.close() } }runMigrationsAndValidate這個方法非常關(guān)鍵。它做了三件事執(zhí)行Migration、校驗新數(shù)據(jù)庫的Schema是否和Schema JSON一致、返回可查詢的數(shù)據(jù)庫對象。如果Schema校驗失敗測試會直接報錯告訴你哪里不一致。4.3 多版本跳躍遷移的測試策略實際項目中用戶可能從任意一個歷史版本升級到最新版本。你需要測試所有可能的遷移路徑。比如當前最新版本是4歷史版本有1、2、3那么需要測試的路徑包括1-4、2-4、3-4。Room的MigrationTestHelper支持傳入多個MigrationTest fun migrate1To4() { helper.createDatabase(TEST_DB, 1).apply { execSQL(INSERT INTO users (name) VALUES (王五)) close() } val db helper.runMigrationsAndValidate( TEST_DB, 4, true, MIGRATION_1_2, MIGRATION_2_3, MIGRATION_3_4 ) // 校驗數(shù)據(jù)... }這里有個經(jīng)驗不要只測試相鄰版本的遷移一定要測試跨版本遷移。因為跨版本遷移會依次執(zhí)行多個Migration中間任何一步出問題都會導(dǎo)致最終失敗。而且跨版本遷移時數(shù)據(jù)會經(jīng)過多次轉(zhuǎn)換更容易出現(xiàn)數(shù)據(jù)丟失或類型不匹配的問題。5. 線上環(huán)境遷移失敗的排查鏈路5.1 從崩潰日志定位問題線上Migration失敗時崩潰日志通常長這樣java.lang.IllegalStateException: Room cannot verify the data integrity. Looks like youve changed schema but forgot to update the version number. You can simply fix this by increasing the version number. Expected: TableInfo{nameusers, columns{idColumn{nameid, typeINTEGER, affinity3, notNulltrue, primaryKeyPosition1}, nameColumn{namename, typeTEXT, affinity2, notNulltrue, primaryKeyPosition0}}, foreignKeys[], indices[]} Found: TableInfo{nameusers, columns{idColumn{nameid, typeINTEGER, affinity3, notNulltrue, primaryKeyPosition1}, nameColumn{namename, typeTEXT, affinity2, notNulltrue, primaryKeyPosition0}, emailColumn{nameemail, typeTEXT, affinity2, notNulltrue, primaryKeyPosition0}}, foreignKeys[], indices[]}這段日志的關(guān)鍵信息在Expected和Found兩個部分。Expected是Room期望的Schema來自Schema JSONFound是設(shè)備上數(shù)據(jù)庫的實際Schema。對比兩者你就能發(fā)現(xiàn)差異Found中多了一個email字段說明Migration執(zhí)行了添加字段的操作但Schema JSON中沒有這個字段說明你忘記升級版本號或者忘記重新編譯導(dǎo)出Schema。常見的崩潰原因和排查方向崩潰信息關(guān)鍵詞可能原因排查方向cannot verify the data integritySchema不一致對比Expected和Found的差異A migration from X to Y was required but not found缺少Migration檢查addMigrations是否注冊了對應(yīng)版本no such table表未創(chuàng)建檢查Migration中是否創(chuàng)建了新表no such column字段未添加檢查ALTER TABLE語句UNIQUE constraint failed唯一約束沖突檢查數(shù)據(jù)是否有重復(fù)值FOREIGN KEY constraint failed外鍵約束沖突檢查關(guān)聯(lián)數(shù)據(jù)是否存在5.2 用Schema JSON做差異比對當崩潰日志不夠清晰時最有效的排查方式是直接比對Schema JSON文件。假設(shè)你從版本2升到版本3失敗了你可以打開app/schemas/com.example.AppDatabase/2.json和3.json逐字段對比。我通常會關(guān)注這幾個地方表名是否一致、字段名是否一致、字段類型是否一致、notNull約束是否一致、默認值是否一致、索引是否一致、外鍵是否一致。任何一處不一致都會導(dǎo)致校驗失敗。有個小技巧你可以用diff命令或者IDE的對比工具來快速找出兩個JSON文件的差異。如果差異很多說明你的Entity改動很大需要仔細檢查每一處。5.3 降級與異常兜底方案即使做了充分的測試線上仍然可能出現(xiàn)意料之外的遷移失敗。這時候你需要一個兜底方案。最常見的做法是捕獲遷移異常降級到 destructive migration。Room.databaseBuilder(context, AppDatabase::class.java, app_database) .addMigrations(MIGRATION_1_2, MIGRATION_2_3) .fallbackToDestructiveMigrationOnDowngrade() .build()但fallbackToDestructiveMigration會丟失所有數(shù)據(jù)只適合那些本地數(shù)據(jù)不重要、可以從服務(wù)器重新拉取的場景。如果本地數(shù)據(jù)很重要你需要更精細的兜底策略比如在遷移失敗時把舊數(shù)據(jù)庫文件備份到另一個路徑然后創(chuàng)建一個新數(shù)據(jù)庫再嘗試從備份中恢復(fù)數(shù)據(jù)。還有一種做法是在Application啟動時先檢查數(shù)據(jù)庫版本如果發(fā)現(xiàn)異常提前處理。比如try { val db Room.databaseBuilder(...).build() db.openHelper.writableDatabase } catch (e: IllegalStateException) { // 遷移失敗執(zhí)行兜底邏輯 handleMigrationFailure() }6. 那些年我踩過的Room升級坑6.1 忘記導(dǎo)出Schema導(dǎo)致的連鎖反應(yīng)早期做項目時我覺得exportSchema沒什么用就設(shè)成了false。結(jié)果有一次線上遷移失敗我想排查問題發(fā)現(xiàn)根本沒有Schema JSON文件可以對比。只能靠猜效率極低。后來我把所有項目的exportSchema都改成了true并且把app/schemas/目錄提交到了Git。這里有個細節(jié)如果你用的是KSP而不是KAPTSchema的導(dǎo)出路徑可能需要在build.gradle中額外配置ksp { arg(room.schemaLocation, $projectDir/schemas) }另外Schema JSON文件必須納入版本控制。因為遷移測試需要用到歷史版本的Schema文件如果你不提交CI上跑測試時會找不到舊版本的Schema測試直接失敗。6.2 字段默認值與Entity聲明不一致這個問題非常隱蔽。假設(shè)你在Entity中聲明了一個字段ColumnInfo(defaultValue 0) val age: Int 0然后在Migration中寫database.execSQL(ALTER TABLE users ADD COLUMN age INTEGER NOT NULL DEFAULT 1)注意Entity中聲明的默認值是0但Migration中寫的默認值是1。這兩個不一致Schema校驗會失敗。而且報錯信息不會直接告訴你默認值不一致只會說Schema不匹配你需要自己去對比JSON文件才能發(fā)現(xiàn)。所以我的經(jīng)驗是Migration中的SQL語句最好直接從Schema JSON文件中復(fù)制createSql然后稍作修改。這樣能最大程度保證一致性。6.3 主鍵自增與數(shù)據(jù)拷貝的沖突在做拆表遷移時我遇到過一個問題新表的主鍵是AUTOINCREMENT的我從舊表拷貝數(shù)據(jù)時手動指定了id值。結(jié)果新表的sqlite_sequence沒有更新后續(xù)插入數(shù)據(jù)時自增ID從1開始導(dǎo)致主鍵沖突。解決方案是在拷貝數(shù)據(jù)后手動更新sqlite_sequenceUPDATE sqlite_sequence SET seq (SELECT MAX(id) FROM contacts) WHERE name contacts或者更簡單的做法拷貝數(shù)據(jù)時不指定id讓SQLite自動生成。但這樣會丟失舊表中的ID關(guān)聯(lián)關(guān)系需要根據(jù)實際情況權(quán)衡。6.4 多模塊項目中的Schema路徑?jīng)_突在組件化項目中數(shù)據(jù)庫可能被多個模塊引用。如果每個模塊都配置了room.schemaLocation可能會出現(xiàn)Schema文件路徑?jīng)_突或者覆蓋的問題。我的做法是只在app模塊中配置Schema導(dǎo)出路徑其他模塊通過api依賴傳遞Room的注解處理器。同時確保所有模塊使用的Room版本一致避免因為版本差異導(dǎo)致Schema格式不兼容。6.5 遷移耗時過長導(dǎo)致的ANR當數(shù)據(jù)庫數(shù)據(jù)量很大時Migration可能會執(zhí)行很長時間。如果Migration在主線程執(zhí)行直接ANR。Room默認的databaseBuilder是在主線程構(gòu)建的但實際的數(shù)據(jù)庫操作是在子線程執(zhí)行的。不過Migration本身是在打開數(shù)據(jù)庫時執(zhí)行的如果你在Application的onCreate中直接訪問數(shù)據(jù)庫Migration就會在主線程執(zhí)行。解決方案是不要在Application啟動時同步訪問數(shù)據(jù)庫。把數(shù)據(jù)庫的初始化放到子線程或者使用RoomDatabase.Builder的setQueryExecutor和setTransactionExecutor來指定執(zhí)行器。Room.databaseBuilder(context, AppDatabase::class.java, app_database) .setQueryExecutor(Executors.newFixedThreadPool(4)) .setTransactionExecutor(Executors.newSingleThreadExecutor()) .build()另外對于大數(shù)據(jù)量的遷移可以考慮分批處理。比如每次只遷移1000條數(shù)據(jù)遷移完一批就更新一次版本號避免一次性遷移太多導(dǎo)致超時。7. 面向未來的Room升級策略7.1 建立Schema變更的規(guī)范流程經(jīng)過多個項目的迭代我總結(jié)了一套Schema變更的規(guī)范流程團隊里每個人都必須遵守修改Entity之前先確認當前數(shù)據(jù)庫版本號。修改Entity之后立即升級版本號并編寫對應(yīng)的Migration。編譯項目檢查生成的Schema JSON文件確認identityHash已更新。編寫遷移測試覆蓋相鄰版本和跨版本遷移。在CI上運行遷移測試確保所有歷史版本的遷移路徑都能通過。Code Review時重點檢查Migration的SQL語句和Schema JSON的差異。這套流程看起來繁瑣但能避免90%以上的遷移問題。尤其是第3步和第4步很多團隊會忽略結(jié)果上線后才發(fā)現(xiàn)問題。7.2 用CI自動化遷移測試手動跑遷移測試容易遺漏最好把它集成到CI流程中。在build.gradle中配置android { testOptions { unitTests { includeAndroidResources true } } }然后在CI腳本中添加./gradlew connectedAndroidTest這樣每次提交代碼時CI會自動運行所有遷移測試。如果某個遷移路徑失敗了CI會直接報錯阻止合并。對于沒有條件跑儀器化測試的團隊可以考慮用Robolectric來跑遷移測試。Room的MigrationTestHelper也支持Robolectric雖然不如真機測試準確但能覆蓋大部分場景。7.3 數(shù)據(jù)庫版本管理的長期維護建議隨著App迭代數(shù)據(jù)庫版本會越來越多Migration文件也會越積越多。如果不加以管理最終會變成一團亂麻。我的建議是第一為每個Migration寫注釋說明這個版本做了什么變更、為什么做這個變更。比如// 版本2 - 3新增用戶頭像字段用于支持個性化推薦 val MIGRATION_2_3 object : Migration(2, 3) { ... }第二定期整理Migration文件把相關(guān)的Migration放在同一個文件中按版本號排序。不要把所有Migration都堆在一個文件里。第三考慮使用Room的AutoMigration來減少手動代碼。對于簡單的加字段、加索引AutoMigration完全夠用。只有復(fù)雜的數(shù)據(jù)轉(zhuǎn)換才需要手動寫Migration。第四保留所有歷史版本的Schema JSON文件。這些文件是遷移測試的基礎(chǔ)也是排查線上問題的關(guān)鍵依據(jù)。不要因為文件多就刪除它們。第五在數(shù)據(jù)庫版本達到一定數(shù)量后考慮做一次基線合并。比如當前最新版本是10你可以把版本1到10的Migration合并成一個從1直接到10的Migration減少遷移路徑的復(fù)雜度。但這樣做的前提是你確定沒有用戶還在使用版本1到9的App。