Firebase含数组与Map字段文档映射到Data Class时部分字段为Null

架构老林

2026-8-6

Firebase文档映射Data Class部分字段为空的排查方案

先从最常见的坑查起：

字段名完全匹配：Firebase文档里的orderQty和Data Class里的变量名必须大小写、符号全一致，差一点都不行。要是想搞命名风格适配（比如Firebase用蛇形order_qty，Data Class用驼峰orderQty），直接加注解：
```
import com.google.firebase.firestore.PropertyName

data class Order(
    @PropertyName("order_qty") val orderQty: Int? = null
)
```
数据类型严丝合缝：去Firebase控制台看orderQty的实际类型——是Int还是Long？是数字还是字符串？比如Firebase存的是Long，你Data Class写Int，数值小的时候可能没事，大了直接解析成null。必须严格对应类型，别想当然。
嵌套结构别偷懒：如果orderQty藏在Map或者数组里：
- Map对应嵌套Data Class：比如Firebase里是product: {orderQty: 5}，别直接用Map<String, Any>，得定义Product数据类包含orderQty，再在主类里引用val product: Product? = null。
- 数组对应List<数据类>：比如Firebase是items: [{orderQty:3}, ...]，主类里要写val items: List<Item>? = emptyList()，Item类里定义orderQty，别用Array类型，Firestore对List支持更好。
必须有无参构造：Kotlin的data class得给所有参数加默认值，比如val orderQty: Int? = null，不能写val orderQty: Int。Firebase解析的时候要调用无参构造，没默认值就生成不了，字段直接null。
权限别踩坑：去看Firestore的安全规则，要是当前用户没权限读这个字段，返回的数据集里根本没这个字段，自然解析成null。
依赖和序列化配置要对：确保加了Firestore的Kotlin扩展依赖，读取的时候用documentSnapshot.toObject(Order::class.java)，别自己手动解析Map，容易出问题。