最近帮同事 review 一个功能分支，任务本身很简单：给订单表加一个“最后修改时间”。方案也很常规，实体类里加个Date字段，更新逻辑 set 一下，然后跑构建。结果 Android Studio 直接甩出来一行红色错误：Cannot figure out how to save this field into database. You can consider adding a type converter for it.同事看了一眼，转头问我：“这句话到底什么意思？我的字段明明就是一个普通的 Date 啊。”
这个场面我太熟了。只要用 Room 做本地存储的 Android 开发者，基本都撞过这堵墙。别看报错只有一句话，背后涉及 Room 的类型映射机制：数据库能存什么、Room 默认认识什么、不认识的时候它为什么选择“拒绝编译”而不是“猜着存”。这套逻辑一旦想明白，后面再遇到枚举、自定义对象、List<xxx>这类字段，基本都能举一反三。下面我会从一次真实的编译错误开始，把类型转换（TypeConverter）的写法、使用场景、替代方案，以及我在实际项目里踩过的“加了转换器还是报错”的坑，一次讲清楚。不管你是第一天写 Room 的新手，还是已经写过不少 DAO 的老开发，应该都能找到点能直接拿去用的东西。
1. 先弄懂 Room 为什么会问“这个字段怎么存”
1.1 报错信息逐词拆解：这是编译期发问，不是运行时崩溃
很多人看到Cannot figure out how to save this field into database第一反应是程序崩了，其实不是。它发生在编译阶段，由 Room 的注解处理器触发，类似你写错了资源文件，APK 根本打不出来，而不是 App 跑到一半才炸。
Room 的职责是把 Java/Kotlin 对象映射到 SQLite 表：实体类的每个字段对应一列，DAO 的方法对应 SQL 语句。为了让这一切可自动生成，Room 必须在编译期知道每个字段能被存成 SQLite 的哪种列类型。当它遇到一个自己不认识的类型，比如java.util.Date，就只能停下来问你：这个字段我没法直接入库，你考虑加一个 type converter 吧。
完整的报错通常在字段下一行还会带上具体信息，比如：
error: Cannot figure out how to save this field into database. You can consider adding a type converter for it. private final java.util.Date createdAt;注意private final java.util.Date createdAt这一行，它就是 Room 认不出的那个字段。项目里字段一多，报错会一次性列出所有问题字段，所以不要只盯着第一行看，往下翻翻往往能把当天的问题一次消灭干净。
1.2 SQLite 的“五类数据类型”和 Room 的默认映射表
为什么一个普通的Date会让 Room 犯难？根本原因在 SQLite 的类型系统身上。SQLite 本身只有五个存储类：INTEGER、TEXT、REAL、BLOB、NULL。Java/Kotlin 世界里的类千千万，不可能每个都天然对应一个 SQLite 类型，所以 Room 内置了一套默认映射规则：
| Java/Kotlin 类型 | SQLite 存储类 |
|---|---|
| int / Integer / long / Long | INTEGER |
| String / CharSequence | TEXT |
| float / Float / double / Double | REAL |
| byte[] | BLOB |
| boolean / Boolean | INTEGER（用 0/1 表示） |
| Date / Calendar / 枚举 / 自定义对象 / List / Map 等 | 不支持，需要 TypeConverter |
你会发现 Room 对 Boolean 也是用 INTEGER 来存的，社区的规范做法也一直是 0 表示 false、1 表示 true。这个表看起来简单，但它是后续所有排查的基础：本科目一旦认清，遇到新类型时你就能提前判断“这字段会不会报错”。
1.3 为什么 Room 不选择“自动猜一个类型存进去”
你可能想问：SQLite 反正什么都能当文本存，Room 为什么不遇到不认识的就默认转成 TEXT 算了？非得报错？
这里有个很实际的讲究。拿Date举例，它可以转成毫秒时间戳存INTEGER，也可以格式化成 ISO8601 字符串存TEXT，两种方案都说得通。Room 没法替你判断业务上适合哪种，如果它暗自选一个，后续你查数据时可能会发现格式不对、时区不对、精度丢失，那时候排查起来可比现在严重得多。
TypeConverter 的存在，就是把“如何翻译”的选择权交给你。你明确告诉 Room：这个类型存库时转成什么，读库时再还原成什么。Room 只负责在你写好的转换规则之上生成代码，绝不瞎猜。这套设计看似保守，但确实避免了很多隐性坑。
2. 方案一：写 TypeConverter，给数据库配个“翻译官”
2.1 最基础的实战：把 Date 存成时间戳 Long
既然问题是 Room 不认识Date，那就让它认识。最常见的做法是把它转成长整型毫秒时间戳，在 SQLite 里用一个 INTEGER 列保存。
先定义一个转换器类：
import java.util.Date class DateConverter { @TypeConverter fun fromTimestamp(value: Long?): Date? { return value?.let { Date(it) } } @TypeConverter fun dateToTimestamp(date: Date?): Long? { return date?.time } }然后在数据库类上注册：
@Database( entities = [Order::class], version = 1 ) @TypeConverters(DateConverter::class) abstract class AppDatabase : RoomDatabase() { // ... }注册之后，Room 在编译期就能识别Date了。实体类里怎么写都行：
@Entity(tableName = "orders") data class Order( @PrimaryKey(autoGenerate = true) val id: Long, val customerName: String, val createdAt: Date )这里有两个函数，方向相反：dateToTimestamp负责把Date变成Long，写入数据库；fromTimestamp负责把Long变回Date，读取时填充到实体字段。数据库层面看到的只有 INTEGER 列，代码层面你依然可以放心使用Date，转换对业务层完全透明。
关于可空性，建议两个方法的参数和返回值都声明成可空类型，这样兼容Date?字段，也能避免 Kotlin 空安全带来的类型匹配问题。如果字段不允许为 NULL，数据库列也别忘了加约束。
2.2 枚举怎么存：用 name() 还是 ordinal()，我推荐 name()
枚举也是高频报错点。有人觉得枚举可以自动映射成整数，实际不行，Room 同样要求你写转换器。而且用什么策略存，是个值得想清楚的事。
第一种方案是存ordinal，也就是枚举的声明顺序，比如PENDING是 0，PAID是 1。优点是省空间、查询数字快。缺点是只要有人调整枚举声明顺序，旧数据读出来就全错位了。比如原来PAID是 1，你有一天在它前面插了一个CREATED，所有已入库的PAID都会变成 2，含义完全变了。
第二种方案是存name，也就是枚举名称字符串。可读性好，日志里直接能看出状态含义；枚举声明顺序变了也不会影响旧数据。代价只是多几个字节的 TEXT 空间，对绝大多数业务来说完全可忽略。所以我默认建议用name()。
enum class OrderStatus { PENDING, PAID, SHIPPED, DONE } class EnumConverter { @TypeConverter fun fromString(value: String?): OrderStatus? { return value?.let { OrderStatus.valueOf(it) } } @TypeConverter fun statusToString(value: OrderStatus?): String? { return value?.name } }如果你确实有性能洁癖，就想用整数存，那也请把ordinal当作一种不可变的数据契约，坚决不要重排枚举顺序，必要时写个 unit test 锁住这个顺序。
2.3 自定义对象和集合：序列化成 JSON 字符串
实体类里出现List<...>或者某个自定义对象时，很多人会直接想“我能不能把它 JSON 化塞进去”。可以，但要想清楚后果再做。
比如一个订单需要保存标签列表：
@Entity(tableName = "orders") data class Order( @PrimaryKey(autoGenerate = true) val id: Long, val customerName: String, val tags: List<Tag> )这种字段直接编译一定会报Cannot figure out how to save this field into database。如果标签只是“整体读取、整体更新、不参与查询条件”，用 JSON 字符串是合理的。下面是一个用 Gson 实现的转换器：
import com.google.gson.Gson import com.google.gson.reflect.TypeToken class JsonConverter { private val gson = Gson() @TypeConverter fun listToJson(value: List<Tag>?): String? { return value?.let { gson.toJson(it) } } @TypeConverter fun jsonToList(value: String?): List<Tag>? { if (value == null) return null val type = object : TypeToken<List<Tag>>() {}.type return gson.fromJson(value, type) } }数据库里tags列就是一个 TEXT，存的是"[{\"name\":\"爆款\"}]"这种内容。
但在这里我必须提个醒：JSON 方案最大的问题是“没法查询”。如果未来你需要在 DAO 里写WHERE tags LIKE '%爆款%'来按标签过滤订单，那会很痛苦，不仅性能差，还容易匹配错。真要按子表数据筛选，就老老实实拆表，用关联查询。JSON 只适合冗余展示字段，不适合核心业务关系。
2.4 多个转换器统一管理：全局注册比局部标注省事
实际项目里不可能只有一个Date字段。你可能会同时遇到枚举、JSON、BigDecimal等一堆类型。如果一个一个写在类上很烦，我习惯把所有转换器收敛到一个类里：
class AppConverters { @TypeConverter fun fromTimestamp(value: Long?): Date? = value?.let { Date(it) } @TypeConverter fun dateToTimestamp(date: Date?): Long? = date?.time @TypeConverter fun fromString(value: String?): OrderStatus? = value?.let { OrderStatus.valueOf(it) } @TypeConverter fun statusToString(value: OrderStatus?): String? = value?.name @TypeConverter fun listToJson(value: List<Tag>?): String? { return value?.let { Gson().toJson(it) } } @TypeConverter fun jsonToList(value: String?): List<Tag>? { if (value == null) return null val type = object : TypeToken<List<Tag>>() {}.type return Gson().fromJson(value, type) } }然后在数据库类上统一挂@TypeConverters(AppConverters::class)。这样所有实体表都共享这套转换规则，新加实体基本不用再操心单个字段。如果只有某张表需要特殊处理，也可以把@TypeConverters标注在实体类上，甚至标注在具体字段上，作用域越局部，影响面越小。
需要注意几个细节：converter 类必须能被公开实例化，最好是无参构造的 public class，或者 Kotlinobject单例；标注@TypeConverter的方法必须只有一个参数，返回非 Void；两个方法如果转换类型互相冲突，编译时会提示 duplicate converter，这时要检查是不是全局和局部注册了重复的转换器。改完转换器之后，Android Studio 偶尔不会立刻生效，我建议直接 Clean 再 Rebuild，省得白等。
3. 方案二：有些字段本来就不该进数据库
3.1 @Ignore：让 Room 别管这个字段
不是所有实体类里的字段都需要持久化。比如一个User实体，列表页要记住用户列表项的选中状态，这个状态就是临时的界面数据，放数据库反而是污染。
@Entity(tableName = "users") data class User( @PrimaryKey val id: Long, val name: String, @Ignore val isSelected: Boolean = false )加上@Ignore之后，Room 不会为isSelected建列，自然也就不会报“不知道如何存”的错误。等于是告诉 Room：这个字段你不需要管。
但要明确一点，@Ignore是“放弃持久化”，不是“解决问题”。如果某个字段是核心业务数据，你只是因为不想写转换器而把它@Ignore掉，那等于数据丢了都不知道。这个注解的适用场景是临时状态、派生缓存、UI 控制字段。另外被忽略的字段不会在 DAO 查询结果里被赋值，所以访问前要想好默认值，否则容易出现空指针。
3.2 一对多关系：别把 List 直接塞进实体里
有段时间我经常在项目里看到这种操作：一个订单实体里塞了List<OrderItem>，报错后不管三七二十一转 JSON。短期能编译过，到了后面要按商品名查订单、要统计某商品销量，全都抓瞎，还得写一堆字符串 LIKE。这是典型的把对象关系硬塞成单表存储。
正确做法是拆表。Order存订单主表，OrderItem存明细表，明细表里用外键关联订单：
@Entity(tableName = "order_items") data class OrderItem( @PrimaryKey val id: Long, val orderId: Long, val sku: String, val count: Int )查询时如果需要一次把订单和明细都查出来，可以用@Relation：
data class OrderWithItems( @Embedded val order: Order, @Relation( parentColumn = "id", entityColumn = "orderId" ) val items: List<OrderItem> )注意@Relation是查询阶段的“组装工具”，不是存储阶段的魔法。Order实体本身不会去存items，Room 会在你查询OrderWithItems时自动执行第二条查询，把明细装好再返回。这样既没有Cannot figure out how to save this field into database，又能真正支持 SQL 条件查询。
如果你只有一个自定义对象，并且它没有自己的主键、不需要单独查询，也可以考虑@Embedded。它的作用是把内嵌对象的字段平铺到同一个表的多列里，比如订单里的收货地址：
@Entity(tableName = "orders") data class Order( @PrimaryKey val id: Long, @Embedded val address: Address )这样Order表里会多出city、street等列，不需要 JSON、不需要转换器，这是更轻量的方案。缺点是嵌套层级太多时可读性差，Room 也不支持无限嵌套。
3.3 那些实在不适合入库的字段怎么办
有些类型确实让人头大，比如Bitmap、Bundle、某个第三方 SDK 的返回值。硬要存，也能写转换器，比如把图片压缩成 BLOB，但大多得不偿失。
以Bitmap为例，如果你需要保存用户头像，正确思路是保存图片文件的 URI 或路径字符串，图片本身放文件系统。把图片塞数据库 BLOB 的做法，每次查询都会带来内存压力和反序列化开销，数据库文件也会迅速膨胀。业务需要裁剪的图片，更是要提前处理好压缩再写文件。
再比如接口类型、抽象类型、泛型嵌套特别复杂的容器，Room 根本不知道运行时具体是哪个子类。遇到这类字段，我一般会回到建模层面：为什么实体类需要一个接口字段？能不能在业务层把接口解析成具体的几个字段后入库？如果能，就拆开存；如果完全只是临时传递的数据，@Ignore也行。数据库建模的第一原则永远是：表是业务事实的快照，不是 UI 对象的垃圾桶。
4. 完整实战：一个订单实体从编译失败到正常读写
4.1 复现现场：三类问题字段一起报错
我经常在项目里一次性看到多个字段同时报错。为了演示，定义一个包含三种典型问题字段的实体：
@Entity(tableName = "orders") data class Order( @PrimaryKey(autoGenerate = true) val id: Long, val customerName: String, val createdAt: Date, // 问题一：Date val status: OrderStatus, // 问题二：枚举 val tags: List<Tag> // 问题三：自定义对象集合 )编译时 Room 会一次性输出三条类似下面的错误：
error: Cannot figure out how to save this field into database. You can consider adding a type converter for it. private final java.util.Date createdAt; error: Cannot figure out how to save this field into database. You can consider adding a type converter for it. private final com.example.app.OrderStatus status; error: Cannot figure out how to save this field into database. You can consider adding a type converter for it. private final java.util.List<com.example.app.Tag> tags;这三条报错看着多，其实也说明 Room 的检查很彻底：把所有不认识的字段都点出来，方便你一次处理完。
4.2 写转换器、注册、编译通过
按第 2 章的方式统一写一个AppConverters，然后注册到数据库：
@Database( entities = [Order::class], version = 1 ) @TypeConverters(AppConverters::class) abstract class AppDatabase : RoomDatabase() { abstract fun orderDao(): OrderDao }注册后重新编译，错误消失。这时候写 DAO，业务侧完全不用关心底层是怎么存的：
@Dao interface OrderDao { @Insert suspend fun insert(order: Order) @Query("SELECT * FROM orders WHERE id = :id") suspend fun findById(id: Long): Order? }调用的地方直接用一个Order对象读写即可。写入时createdAt会被转成 INTEGER 时间戳，status转成字符串，tags转成 JSON 文本；读取时再各自还原回Date、枚举和List<Tag>。
4.3 查看生成的 SQL，确认转换真的生效
有时候你以为注册成功了，结果还是不对，这时候最好的办法是看 Room 生成的实现代码。用 kapt 时路径一般在：
app/build/generated/source/kapt/debug/你的包名/Order_Impl.java如果用 KSP，路径类似：
app/build/generated/ksp/debug/java/你的包名/Order_Impl.java打开之后看createAllTables方法，能直接看到建表语句长什么样。如果转换器生效，你会发现类似这样的定义：
CREATE TABLE IF NOT EXISTS `orders` ( `id` INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL, `customerName` TEXT NOT NULL, `createdAt` INTEGER NOT NULL, `status` TEXT NOT NULL, `tags` TEXT )确认createdAt是 INTEGER、status是 TEXT、tags是 TEXT，就说明 Room 已经把转换规则编进去了。这个技能在排查“为什么查询结果对不上”“为什么字段没存进去”时也很管用。
4.4 顺带补一节课：新增字段后别忘了数据库 Migration
实体类变了，数据库版本号一般也要变。比如原来数据库 version = 1，现在加了createdAt这些字段，版本要升到 2，并提供一个 Migration。
val MIGRATION_1_2 = object : Migration(1, 2) { override fun migrate(db: SupportSQLiteDatabase) { db.execSQL( "ALTER TABLE orders ADD COLUMN createdAt INTEGER NOT NULL DEFAULT 0" ) } }注意新增列如果声明为 NOT NULL，ALTER TABLE时必须给默认值，否则迁移会失败。这里createdAt的默认值用了 0，也就是 epoch 时间戳，不一定符合业务语义，只是保证迁移能跑通。更好的做法是先不加 NOT NULL 约束，迁移完成后在业务层逐步填充数据。
如果是把旧字段从 TEXT 改成 INTEGER，光靠ALTER TABLE改不了列类型，得新建临时表、拷贝数据、删旧表、改新表名。这一整套都要写进 Migration，不能指望 Room 自动帮你搞定。以前见过有人只改了实体类和版本号，没写 Migration，结果用户升级后直接抛IllegalStateException: Room cannot verify the data integrity，这是比Cannot figure out...更难看的错误。
5. 疑难杂症与避坑清单
5.1 加了转换器还是报错？按这个顺序查
| 现象 | 可能原因 | 排查方向 |
|---|---|---|
| 加了 converter 后仍然报错 | 没有在正确位置注册@TypeConverters | 确认标注是写在Database类、实体类还是字段上；字段级标注是否遗漏 |
| 加了 converter 后 IDE 还是报错 | 注解处理器缓存未更新 | Clean Project 后 Rebuild，KSP/kapt 都适用 |
| 编译报 duplicate converter | 全局和局部重复注册了同类型转换器 | 检查两个@TypeConverters是否包含相同的源类型到目标类型 |
| 运行时找不到 converter 方法 | R8/ProGuard 混淆了类名或方法名 | 在 keep 规则中保留 converter 类 |
| 读出来的 Date 是 1970 年 | 存了秒，读成毫秒，或反过来 | 统一以毫秒为单位，写测试验证边界值 |
| 读出来的枚举值错乱 | 之前存了 ordinal，后面枚举顺序变了 | 如果还没上线，清库重来；如果已上线，写 Migration 修正 |
| 新增字段后旧用户升级崩溃 | 没写 Migration | 每个版本增量都要有对应 Migration，升级前先测试 |
这条表是我这些年排查 Room 问题时的主心骨。真正花时间调一个“加了转换器还报错”的 bug，往往不是代码本身难，而是没按顺序查。
5.2 两个高频问题展开细看
第一个高频问题是“明明注册了，还是找不到”。我遇到最多的情况是 IDE 增量编译没有重新跑注解处理器。你新加的AppConverters可能没有被 Room 的注解处理器感知到，所以旧的报错信息还留在原地。这个问题的通用解法是不管三七二十一先 Clean 再 Rebuild。要是用 KSP，偶尔还需要Invalidate Caches / Restart一下。不是玄学，是 Kotlin 注解处理在某些版本里的缓存机制不够聪明。
第二个高频问题是 Kotlin 空安全导致的类型匹配失败。比如实体字段写的是Date?，但 converter 方法参数是Date，Room 在生成代码时可能匹配不上。我的建议是 converter 两个方法都写成可空参数、可空返回值，反正 Room 实际调用时如果列值为 NULL，会直接给 null，不会硬调一个非空参数方法。这样写虽然在 Kotlin 里看着啰嗦，但配合Date?字段时最稳。
5.3 性能与长期维护的两三句话
TypeConverter 不是免费的。查询 1 万行订单，每行都要走一次 Gson 反序列化，累计开销非常可观。如果你的 JSON 字段特别大、查询特别频繁，可以重新评估是不是该拆表或者改为只查询必要字段。Room 支持 DAO 方法返回自定义 POJO，你可以只映射那张表里的几个列出来，避免无谓的 JSON 解析。
对于转换器本身，我会把它当成纯函数来对待，不接受外部上下文、不做 I/O、不访问数据库。它只是“值到值的翻译”，这样才好测试、才好保证可空值不炸。R8 开启后如果发现 Release 包读取数据时抛找不到转换方法，记得加上 keep 规则：
-keep class com.yourpackage.db.converter.** { *; }还有一点要提醒：如果项目从 kapt 切到 KSP，或者反过来，生成的代码路径会变，但报错内容和排查思路基本一致，不需要推翻重学。
最后分享一个我实际工作中的习惯。这些年遇到Cannot figure out how to save this field into database的次数，少说几十回，后来我养成了一个固定动作：拿到报错先不急着写转换器，先问自己三个问题——这个字段是否真的必须入库？能不能用Long、String这种 Room 原生支持的类型表示？如果要写转换器，用什么存储格式最匹配未来的查询需求？想清楚再动手，通常一次就能改完。再一个笨办法：写完一个实体类，先扫一遍所有字段类型，发现混进Date、枚举、自定义集合的，提前把转换器补好再触发编译。这件事看着不起眼，但能帮你省掉很多次“改一行编译半天”的等待时间。
