Room升级至2.5.0-alpha03后迁移脚本因SHADOW_TABLE_NAME_SUFFIXES抛异常

问题描述 #

升级Room版本从2.4.3到2.5.0-alpha03后，执行迁移生成新的schema JSON文件（如74.json）时，偶尔会触发以下解析异常：

Caused by: java.lang.IllegalStateException: Cannot parse existing schema file: C:\mypath\com.example.MyDatabase\74.json. If you've modified the file, you might've broken the JSON format, try deleting the file and re-running the compiler. 
If you've not modified the file, please file a bug with a sample app to reproduce the issue.   
    at androidx.room.vo.Database.exportSchema(Database.kt:111)  
    at androidx.room.DatabaseProcessingStep.process(DatabaseProcessingStep.kt:123)  
    at androidx.room.compiler.processing.CommonProcessorDelegate.processRound(XBasicAnnotationProcessor.kt:123)     
    at androidx.room.compiler.processing.javac.JavacBasicAnnotationProcessor.process(JavacBasicAnnotationProcessor.kt:71)   
    at org.jetbrains.kotlin.kapt3.base.incremental.IncrementalProcessor.process(incrementalProcessors.kt:90)    
    at org.jetbrains.kotlin.kapt3.base.ProcessorWrapper.process(annotationProcessing.kt:197)    
    at jdk.compiler/com.sun.tools.javac.processing.JavacProcessingEnvironment.callProcessor(JavacProcessingEnvironment.java:985)    ... 44 more

对比新旧schema文件，发现新生成的文件中ftsVersion块多了以下不属于Schema规范的内容：

"SHADOW_TABLE_NAME_SUFFIXES": [
      "_content",
      "_segdir",
      "_segments",
      "_stat",
      "_docsize"
    ],
    "shadowTableNames$delegate": {
      "initializer": {},
      "_value": {}
    },

这些字段是androidx.room.migration.bundle.FtsEntityBundle类的静态变量，删除该代码块后异常消失，且问题与迁移脚本内容无关。

原因分析 #

这是Room 2.5.0-alpha03版本的一个bug：Room的Schema序列化逻辑错误地将FtsEntityBundle类中的静态字段（包括SHADOW_TABLE_NAME_SUFFIXES和委托属性shadowTableNames$delegate）写入了生成的JSON文件，而Room自身的Schema解析器无法识别这些非预期字段，导致抛出解析异常。

临时解决方法 #

• 手动修复Schema文件：每次生成异常的JSON文件后，删除其中新增的SHADOW_TABLE_NAME_SUFFIXES和shadowTableNames$delegate代码块，再重新编译项目
• 回退到稳定版：暂时降级Room版本至2.4.3，等待官方发布修复后的版本
• 禁用Schema导出：如果项目不需要Schema文件，可以在@Database注解中设置exportSchema = false（注意：此方法会关闭Schema生成，不推荐需要迁移记录的项目使用）

后续处理 #

该问题属于Alpha版本的已知缺陷，建议关注Room后续的稳定版本更新，官方会在正式版或后续Alpha/Beta版本中修复此序列化逻辑错误。

内容的提问来源于stack exchange，提问作者Monica Ivan