Room框架

// kotlin
// 定义一个 User Entity，对应数据库中的 users 表
@Entity
data class User(
    // uid 作为主键，Room 会自动生成自增 ID
    @PrimaryKey(autoGenerate = true)
    val uid: Int = 0,
 
    // first_name 和 last_name 对应表中的列
    val firstName: String?,
    val lastName: String?,
 
    // age 对应 age 列
    val age: Int
)

// java
// Java 版本的 Entity 定义
@Entity
public class User {
    // 主键，自动生成
    @PrimaryKey(autoGenerate = true)
    private int uid;
 
    private String firstName;
    private String lastName;
    private int age;
 
    // 无参构造函数（Room 需要）
    public User() {}
 
    // 带参构造函数
    public User(String firstName, String lastName, int age) {
        this.firstName = firstName;
        this.lastName = lastName;
        this.age = age;
    }
 
    // Getter 和 Setter（Room 使用字段或 Getter，取决于注解配置）
    public int getUid() { return uid; }
    public void setUid(int uid) { this.uid = uid; }
    public String getFirstName() { return firstName; }
    public void setFirstName(String firstName) { this.firstName = firstName; }
    public String getLastName() { return lastName; }
    public void setLastName(String lastName) { this.lastName = lastName; }
    public int getAge() { return age; }
    public void setAge(int age) { this.age = age; }
}

CREATE TABLE users (
    uid INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL,
    firstName TEXT,
    lastName TEXT,
    age INTEGER NOT NULL
);

@Entity
data class Book(
    @PrimaryKey  // 简单主键，无自增
    val isbn: String,
 
    val title: String,
    val author: String
)

@Entity
data class Article(
    @PrimaryKey(autoGenerate = true)  // 设为自动生成，插入时无需指定
    val id: Long = 0,  // 注意：必须提供默认值或使用可空类型
 
    val title: String,
    val content: String
)

@Entity(primaryKeys = ["firstName", "lastName"])
// 复合主键：firstName 和 lastName 的组合唯一
data class Person(
    val firstName: String,
    val lastName: String,
    val age: Int
)

@Entity
data class UserProfile(
    @PrimaryKey(autoGenerate = true)
    val userId: Long = 0,
 
    @ColumnInfo(name = "user_name")  // 列名为 user_name，而非 userName
    val userName: String,
 
    @ColumnInfo(name = "created_at", typeAffinity = ColumnInfo.TEXT)
    // 存储为 ISO 8601 格式的时间戳字符串
    val createdAt: String,
 
    @ColumnInfo(name = "is_active", index = true)
    // 创建索引，加速按状态查询
    val isActive: Boolean = true
)

@Entity(tableName = "tb_user")  // 使用 tb_user 作为表名，而非 User
data class User(
    @PrimaryKey
    val id: Int,
    val name: String
)

@Entity
data class Employee(
    @PrimaryKey
    val id: Int,
 
    val firstName: String,
    val lastName: String,
 
    @Ignore  // 不会被存入数据库，仅存在于内存中的对象
    val fullName: String = "$firstName $lastName",  // 这其实无法工作
 
    // 正确做法：使用 @Transient（在 Java 中）或用函数代替
    // 这里演示正确的忽略方式
    val departmentId: Int
) {
    // 派生属性应该用普通属性（而非 data class 的 copy/equals 生成）
    // 如果必须标注，用 @Ignore
    // @Ignore
    // val avatarUrl: String? = null
}

// 实际开发中更常见的场景：
@Entity
data class User(
    @PrimaryKey
    val id: Int,
 
    val name: String,
 
    // 一个从服务器获取的头像 URL，不持久化到本地数据库
    @Ignore
    val avatarUrl: String? = null
)

// 定义一个嵌入对象：地址
data class Address(
    val street: String?,
    val city: String?,
    val state: String?,
    val zipCode: String?,
    val country: String?
)
 
// 定义 User Entity，使用 @Embedded 将 Address 的字段展开到 users 表中
@Entity
data class UserWithAddress(
    @PrimaryKey
    val id: Int,
 
    val name: String,
 
    @Embedded  // Address 的所有字段会被展开为 users 表的列
    val address: Address,
 
    // 嵌套的嵌入对象（前缀冲突时使用 prefix 参数区分）
    @Embedded(prefix = "mailing_")
    val mailingAddress: Address? = null
)

// 定义一个 DAO 接口，专门负责操作 User 表
@Dao  // Data Access Object 注解
interface UserDao {
 
    // 插入操作：返回新插入行的主键值（Long 类型）
    @Insert
    suspend fun insertUser(user: User): Long
 
    // 批量插入：返回插入的行数
    @Insert
    suspend fun insertAll(vararg users: User)
 
    // 查询操作：返回所有用户列表
    @Query("SELECT * FROM user")
    suspend fun getAllUsers(): List<User>
 
    // 带条件的查询：按年龄查询
    @Query("SELECT * FROM user WHERE age > :minAge")
    suspend fun getUsersOlderThan(minAge: Int): List<User>
 
    // 更新操作：返回受影响的行数
    @Update
    suspend fun updateUser(user: User): Int
 
    // 删除操作：返回受影响的行数
    @Delete
    suspend fun deleteUser(user: User): Int
 
    // 删除所有数据
    @Query("DELETE FROM user")
    suspend fun deleteAllUsers()
}

@Dao
interface ProductDao {
    // 查询所有商品
    @Query("SELECT * FROM product")
    fun getAllProducts(): Flow<List<Product>>  // 使用 Flow 实现响应式查询
 
    // 带条件的单值查询
    @Query("SELECT * FROM product WHERE id = :productId")
    suspend fun getProductById(productId: Int): Product?
 
    // 统计查询：返回满足条件的记录数量
    @Query("SELECT COUNT(*) FROM product WHERE price < :maxPrice")
    suspend fun countCheapProducts(maxPrice: Double): Int
 
    // 聚合查询：计算平均价格
    @Query("SELECT AVG(price) FROM product")
    suspend fun getAveragePrice(): Double?
 
    // 分页查询：LIMIT 和 OFFSET
    @Query("SELECT * FROM product ORDER BY name ASC LIMIT :limit OFFSET :offset")
    suspend fun getProductsPaged(limit: Int, offset: Int): List<Product>
}

// 搜索用户名中包含指定关键词的用户
@Query("SELECT * FROM user WHERE firstName LIKE '%' || :keyword || '%' OR lastName LIKE '%' || :keyword || '%'")
suspend fun searchUsers(keyword: String): List<User>

// 查询指定 ID 列表中的所有用户
@Query("SELECT * FROM user WHERE uid IN (:userIds)")
suspend fun getUsersByIds(userIds: List<Int>): List<User>
 
// 也可以使用 vararg（可变参数）方式传入
@Query("SELECT * FROM user WHERE uid IN (:userIds)")
suspend fun getUsersByIds(vararg userIds: Int): List<User>

// 查询备注为 NULL 的记录
@Query("SELECT * FROM task WHERE note IS NULL")
suspend fun getTasksWithNoNote(): List<Task>
 
// 查询备注不为 NULL 的记录
@Query("SELECT * FROM task WHERE note IS NOT NULL")
suspend fun getTasksWithNotes(): List<Task>

@Dao
interface UserDao {
 
    // 单条插入
    @Insert
    suspend fun insert(user: User): Long
 
    // 批量插入：Room 会自动将多条插入包装在一个事务中
    @Insert
    suspend fun insertAll(users: List<User>)
 
    // 使用 @Insert(onConflict = OnConflictStrategy.REPLACE)
    // 可以实现“存在则替换”语义，类似于 UPSERT
    @Insert(onConflict = OnConflictStrategy.REPLACE)
    suspend fun insertOrReplace(user: User)
 
    // @Update 会根据主键判断，如果记录不存在则不产生任何影响
    @Update
    suspend fun update(user: User): Int
 
    // @Delete 同样基于主键匹配来删除记录
    @Delete
    suspend fun delete(user: User): Int
 
    // 也可以使用 @Query 执行自定义的 DELETE 语句
    @Query("DELETE FROM user WHERE age > :age")
    suspend fun deleteUsersOlderThan(age: Int): Int
}

@Dao
interface UserDao {
    // 返回 LiveData，数据库变化会自动通知观察者
    @Query("SELECT * FROM user")
    fun getAllUsersLiveData(): LiveData<List<User>>
 
    // 带过滤条件的 LiveData 查询
    @Query("SELECT * FROM user WHERE age >= :minAge ORDER BY age DESC")
    fun getAdultsLiveData(minAge: Int): LiveData<List<User>>
}

@Dao
interface UserDao {
    // Room 会自动将数据库的 ContentObserver 转换为 Kotlin Flow
    // Room 会将 Flow 的发射放在主线程上（与 LiveData 行为一致）
    @Query("SELECT * FROM user ORDER BY age ASC")
    fun getAllUsersFlow(): Flow<List<User>>
 
    // 带过滤条件的 Flow 查询
    @Query("SELECT * FROM user WHERE age >= :minAge")
    fun getAdultsFlow(minAge: Int): Flow<List<User>>
 
    // 也可以使用 flowOf() 配合 withContext(IO) 实现后台发射
    // 但 Room 2.2+ 会在后台线程执行查询并在主线程发射
    @Query("SELECT * FROM user WHERE name LIKE :pattern")
    fun searchUsers(pattern: String): Flow<List<User>>
}

// 在 ViewModel 中使用 Flow 的典型模式
class UserViewModel(private val userDao: UserDao) : ViewModel() {
 
    // 只暴露 Flow 给 UI 层，不暴露 DAO 的具体引用
    val allUsers: Flow<List<User>> = userDao.getAllUsersFlow()
 
    // 带转换的 Flow：筛选出成年人并转换为 UI 模型
    val adultUsers: Flow<List<UserUiModel>> = userDao.getAllUsersFlow()
        .map { users -> users.filter { it.age >= 18 } }
        .map { adults -> adults.map { UserUiModel.fromEntity(it) } }
}

@Dao
abstract class UserDao {
 
    // 方式一：@Transaction 注解批量方法
    @Insert
    abstract suspend fun insertUser(user: User): Long
 
    @Insert
    abstract suspend fun insertProfile(profile: UserProfile): Long
 
    @Transaction  // 确保整个方法在一个事务中执行
    open suspend fun insertUserWithProfile(user: User, profile: UserProfile) {
        val userId = insertUser(user)
        // 如果这里抛出异常，整个事务会回滚
        insertProfile(profile.copy(userId = userId))
    }
 
    // 方式二：使用 withTransaction 协程函数（更灵活）
    @Transaction
    @Query("SELECT * FROM user WHERE id = :userId")
    abstract fun getUserWithProfile(userId: Int): Flow<UserWithProfile?>
}

// 在 Repository 或 ViewModel 中使用 withTransaction
class UserRepository(private val database: AppDatabase) {
 
    private val userDao = database.userDao()
 
    suspend fun transferUser(fromId: Int, toId: Int, amount: Double) {
        // 在事务中执行：扣款 -> 加款 -> 记录日志
        database.withTransaction {
            val fromUser = userDao.getUserById(fromId)
            val toUser = userDao.getUserById(toId)
 
            if (fromUser != null && fromUser.balance >= amount) {
                userDao.updateBalance(fromId, fromUser.balance - amount)
                userDao.updateBalance(toId, toUser.balance + amount)
                userDao.insertTransferLog(
                    TransferLog(fromId, toId, amount, System.currentTimeMillis())
                )
            }
        }
    }
}

// AppDatabase.kt
// AppDatabase 类需要同时继承 RoomDatabase
@Database(
    entities = [User::class, Book::class, Author::class],  // 声明所有参与数据库的 Entity
    version = 1,  // 数据库版本号，从 1 开始，每次 schema 变化必须递增
    exportSchema = true  // 导出 schema 到指定目录，用于迁移和版本管理
)
abstract class AppDatabase : RoomDatabase() {
 
    // 提供各表的 DAO 访问入口
    abstract fun userDao(): UserDao
    abstract fun bookDao(): BookDao
    abstract fun authorDao(): AuthorDao
 
    // 可以定义一些全局方法，如清除所有表的数据
    companion object {
        // @Volatile 确保多线程间的可见性
        @Volatile
        private var INSTANCE: AppDatabase? = null
 
        // 使用 Dagger/Hilt 或手动方式获取 Database 实例
        fun getDatabase(context: Context): AppDatabase {
            return INSTANCE ?: synchronized(this) {
                val instance = Room.databaseBuilder(
                    context.applicationContext,  // 使用 ApplicationContext 避免内存泄漏
                    AppDatabase::class.java,     // Database 类的 Class 对象
                    "app_database"              // 数据库文件名（不含扩展名）
                )
                .build()  // 同步构建（实际为异步），也可使用 addCallback
                INSTANCE = instance
                instance
            }
        }
    }
}

val database = Room.databaseBuilder(
    context.applicationContext,
    AppDatabase::class.java,
    "app_database"
)
    // 数据库创建和打开时的回调，可用于预填充数据
    .addCallback(object : Callback() {
        override fun onCreate(db: SupportSQLiteDatabase) {
            super.onCreate(db)
            // 数据库首次创建时执行，可以在这里插入初始数据
            // 注意：此回调在后台线程中执行
        }
 
        override fun onOpen(db: SupportSQLiteDatabase) {
            super.onOpen(db)
            // 数据库每次打开时执行
        }
 
        override fun onConfigure(db: SupportSQLiteDatabase) {
            super.onConfigure(db)
            // 在数据库配置之前调用，可以设置外键约束等
            db.setForeignKeyConstraintsEnabled(true)
        }
    })
 
    // 当版本不匹配且没有 Migration 时，摧毁旧数据库重建
    // ⚠️ 警告：这会导致旧数据全部丢失，仅适用于开发阶段
    .fallbackToDestructiveMigration()
 
    // 指定在 schema 版本回退时也执行破坏性迁移
    .fallbackToDestructiveMigrationFrom(2, 3)  // 仅在从版本 2 或 3 回退时允许破坏
 
    // 设置数据库打开模式的工厂（默认使用标准模式）
    // .openHelperFactory(factory)
 
    // 设置查询执行线程（默认返回董氏线程，用于观察 LiveData/Flow）
    // Room 2.2+ 不推荐修改此设置
    // .setTransactionExecutor(Executors.newSingleThreadExecutor())
 
    // 设置 Journal 模式（废弃，Room 3.0 已移除）
    // .setJournalMode(JournalMode.WRITE_AHEAD_LOGGING)
 
    // 添加迁移策略（详见“数据库迁移”章节）
    .addMigrations(MigrationFrom1To2(), MigrationFrom2To3())
 
    // 自动关闭时间（达到空闲连接超时后自动关闭数据库）
    .setAutoCloseTimeout(30, TimeUnit.SECONDS)
 
    .build()

// 双重检查锁定模式的详细解释
@Volatile  // 确保 INSTANCE 对所有线程可见
private var INSTANCE: AppDatabase? = null
 
fun getDatabase(context: Context): AppDatabase {
    return INSTANCE ?: synchronized(this) {  // 同步块确保线程安全
        INSTANCE ?: buildDatabase(context).also { INSTANCE = it }
        // 第一次检查在同步块外（提升性能）
        // 第二次检查在同步块内（确保单例）
    }
}

// 多数据库实例场景
val readOnlyDb = Room.databaseBuilder(
    context,
    AppDatabase::class.java,
    "preloaded_database.db"  // 指向 assets 中的预置数据库
)
    .createFromAsset("databases/preloaded_database.db")  // 从 APK assets 复制
    .openHelperFactory(null)  // 打开为只读模式
    .build()
 
val writableDb = Room.databaseBuilder(
    context,
    AppDatabase::class.java,
    "user_database.db"
)
    .build()

// 在协程中执行批量操作，自动包装在事务中
suspend fun insertBatch(items: List<Entity>) {
    database.runInTransaction {
        items.forEach { entityDao.insert(it) }
    }
}
 
// 清除所有表中的数据（TRUNCATE TABLE 的替代方式）
database.clearAllTables()
 
// 执行不返回结果的原始 SQL（谨慎使用，绕过了编译期检查）
database.openHelper.writableDatabase.execSQL("PRAGMA foreign_keys = ON")
 
// 获取底层 SQLiteDatabase（仅在万不得已时使用）
val sqliteDb = database.openHelper.writableDatabase

@Dao
interface UserDao {
    // 不使用 suspend，返回 LiveData（Room 自动在后台线程执行查询）
    @Query("SELECT * FROM user")
    fun getAllUsersLiveData(): LiveData<List<User>>
 
    // 不使用 suspend，返回 Flow（Room 自动在后台线程执行查询）
    @Query("SELECT * FROM user")
    fun getAllUsersFlow(): Flow<List<User>>
 
    // 不使用 suspend，返回 RxJava 的 Single
    @Query("SELECT * FROM user WHERE id = :id")
    fun getUserById(id: Int): Single<User>
 
    // 不使用 suspend，也不返回任何响应式类型
    // Room 会在后台线程执行，并忽略返回值
    @Insert
    fun insertSync(user: User)  // 虽然不推荐，但语法正确
}

@Entity(tableName = "users")
data class User(
    @PrimaryKey
    val id: Long,
    val name: String,
    val email: String
)

@Entity(tableName = "users")
public class User {
    @PrimaryKey
    public long id;
    public String name;
    public String email;
}

@Entity(tableName = "products")
data class Product(
    @PrimaryKey(autoGenerate = true)
    val id: Long,
 
    @ColumnInfo(name = "product_name", typeAffinity = ColumnInfo.TEXT)
    val productName: String,
 
    @ColumnInfo(name = "price", typeAffinity = ColumnInfo.REAL, defaultValue = "0.0")
    val price: Double,
 
    @ColumnInfo(collate = ColumnInfo.NOCASE)
    val category: String? = null,
 
    // transientField 不会被 Room 持久化，因为用 @Ignore 修饰
    @Ignore
    val isFavorite: Boolean = false
)

@Entity(tableName = "articles")
data class Article(
    @PrimaryKey
    val id: String, // 使用 UUID 作为主键
 
    val title: String,
 
    val content: String,
 
    val authorId: Long,
 
    val createdAt: Long, // 时间戳，单位毫秒
 
    val updatedAt: Long,
 
    // 以下字段仅存在于内存中，不持久化
    @Ignore
    var parsedContent: Spannable? = null, // 富文本解析后的内容
 
    @Ignore
    var readProgress: Float = 0f, // 阅读进度（0.0 ~ 1.0）
 
    @Ignore
    var isBookmarked: Boolean = false // 是否已收藏（运行时状态）
)

@Entity(tableName = "categories")
data class Category(
    @PrimaryKey
    val categoryId: Long, // 显式管理的自增长 ID
 
    val name: String,
 
    val description: String?
)

@Entity(tableName = "orders")
data class Order(
    @PrimaryKey(autoGenerate = true)
    val orderId: Long = 0, // 显式默认值 0，SQLite 会忽略此值并自动生成
 
    val customerId: Long,
 
    val totalAmount: Double,
 
    val status: String,
 
    val createdTime: Long = System.currentTimeMillis()
)

@Entity(
    tableName = "enrollments",
    primaryKeys = ["studentId", "courseId"]
)
data class Enrollment(
    val studentId: Long,
    val courseId: Long,
    val enrolledAt: Long = System.currentTimeMillis(),
    val grade: String? = null
)

@Entity(
    tableName = "order_items",
    primaryKeys = ["orderId", "productId"],
    indices = [Index(value = ["orderId"]), Index(value = ["productId"])]
)
data class OrderItem(
    val orderId: Long,
    val productId: Long,
    val quantity: Int,
    val unitPrice: Double
)

@Entity(
    tableName = "posts",
    foreignKeys = [
        ForeignKey(
            entity = User::class,
            parentColumns = ["id"],
            childColumns = ["authorId"],
            onDelete = ForeignKey.CASCADE
        )
    ],
    indices = [Index(value = ["authorId"])]
)
data class Post(
    @PrimaryKey(autoGenerate = true)
    val id: Long,
 
    val title: String,
 
    val content: String,
 
    // 外键列：引用 users 表的 id 列
    val authorId: Long,
 
    val publishedAt: Long? = null
)

// 定义被引用的父表：部门表
@Entity(tableName = "departments")
data class Department(
    @PrimaryKey
    val deptId: Long,
    val name: String,
    val budget: Double
)
 
// 定义引用子表：员工表
@Entity(
    tableName = "employees",
    foreignKeys = [
        ForeignKey(
            entity = Department::class,
            parentColumns = ["deptId"],
            childColumns = ["departmentId"],
            onDelete = ForeignKey.SET_NULL // 部门删除后，员工记录保留但部门字段置空
        )
    ],
    indices = [Index(value = ["departmentId"])]
)
data class Employee(
    @PrimaryKey(autoGenerate = true)
    val empId: Long,
    val name: String,
    val position: String,
    val departmentId: Long? = null // 可空，因为 SET_NULL 要求列允许为空
)

@Entity(
    tableName = "order_items",
    foreignKeys = [
        ForeignKey(
            entity = Order::class,
            parentColumns = ["orderId"],
            childColumns = ["orderId"],
            onDelete = ForeignKey.CASCADE
        ),
        ForeignKey(
            entity = Product::class,
            parentColumns = ["productId"],
            childColumns = ["productId"],
            onDelete = ForeignKey.RESTRICT // 禁止删除正在被订单引用的商品
        )
    ],
    indices = [Index(value = ["orderId"]), Index(value = ["productId"])]
)
data class OrderItem(
    @PrimaryKey(autoGenerate = true)
    val itemId: Long,
 
    val orderId: Long,
    val productId: Long,
    val quantity: Int,
    val unitPrice: Double
)

// 用户实体
@Entity(tableName = "users")
data class User(
    @PrimaryKey(autoGenerate = true)
    val id: Long,
    val username: String,
    val email: String
)
 
// 文章实体
@Entity(
    tableName = "articles",
    foreignKeys = [
        ForeignKey(
            entity = User::class,
            parentColumns = ["id"],
            childColumns = ["authorId"],
            onDelete = ForeignKey.CASCADE
        )
    ],
    indices = [Index("authorId")]
)
data class Article(
    @PrimaryKey(autoGenerate = true)
    val id: Long,
    val title: String,
    val body: String,
    val authorId: Long,
    val publishedAt: Long
)
 
// 标签实体
@Entity(tableName = "tags")
data class Tag(
    @PrimaryKey(autoGenerate = true)
    val id: Long,
    val name: String
)
 
// 文章-标签关联实体（多对多关系的中间表）
@Entity(
    tableName = "article_tag_cross_ref",
    primaryKeys = ["articleId", "tagId"]
)
data class ArticleTagCrossRef(
    val articleId: Long,
    val tagId: Long
)

@Embed(prefix = "home_")
data class Address(
    val street: String,
    val city: String,
    val province: String,
    val postalCode: String
)
 
@Entity(tableName = "users")
data class User(
    @PrimaryKey(autoGenerate = true)
    val id: Long,
    val name: String,
    val email: String,
 
    // 将 Address 的所有字段平铺展开到 users 表中
    // 对应的列名分别为 home_street, home_city, home_province, home_postal_code
    @Embedded
    val homeAddress: Address,
 
    // 可以在同一个 Entity 中嵌入多个对象
    @Embedded(prefix = "work_")
    val workAddress: Address? = null
)

class Converters {
    // 将枚举转换为字符串存储
    @TypeConverter
    fun fromOrderStatus(status: OrderStatus): String {
        return status.name // OrderStatus.PENDING -> "PENDING"
    }
 
    // 从字符串恢复为枚举
    @TypeConverter
    fun toOrderStatus(value: String): OrderStatus {
        return OrderStatus.valueOf(value) // "PENDING" -> OrderStatus.PENDING
    }
 
    // 将 Date 转换为 Long（毫秒时间戳）存储
    @TypeConverter
    fun fromTimestamp(value: Long?): Date? {
        return value?.let { Date(it) }
    }
 
    @TypeConverter
    fun dateToTimestamp(date: Date?): Long? {
        return date?.time
    }
}

@Database(
    entities = [User::class, Order::class, Product::class],
    version = 1,
    exportSchema = false,
    converters = [Converters::class]
)
abstract abstract AppDatabase : RoomDatabase()

// Kotlin
@Dao  // @Dao 注解标记此类为 DAO 接口
interface UserDao {
 
    // 方法定义...
}

// Java
@Dao  // @Dao 注解标记此类为 DAO 接口
public interface UserDao {
 
    // 方法定义...
}

@Dao
interface UserDao {
 
    // 返回 List<User>：Room 自动将所有结果行映射为 User 对象列表
    @Query("SELECT * FROM user")
    fun getAllUsers(): List<User>
 
    // 返回 Single<User>：表示期望恰好返回一条记录
    @Query("SELECT * FROM user WHERE id = :id")
    fun getUserById(id: Long): User?
 
    // 返回 Flow<List<User>>：实时数据流，结果集变化时自动推送新值
    @Query("SELECT * FROM user")
    fun getAllUsersFlow(): Flow<List<User>>
 
    // 返回 LiveData<List<User>>：与 Android 生命周期组件集成
    @Query("SELECT * FROM user")
    fun getAllUsersLiveData(): LiveData<List<User>>
}

@Query("SELECT * FROM user WHERE age > :minAge AND city = :city ORDER BY name ASC")
//                        ↑                 ↑ 参数名绑定
//                        参数名必须与方法参数名完全一致
fun getUsersByCondition(minAge: Int, city: String): List<User>

// 当 city 参数为 null 时，WHERE 子句被忽略，返回所有年龄符合条件但城市任意的用户
@Query("SELECT * FROM user WHERE age > :minAge" +
       " AND (:city IS NULL OR city = :city)")
fun searchUsers(minAge: Int, city: String?): List<User>

// 计算所有用户的平均年龄。Room 会将聚合函数的返回值映射为 Double 类型
@Query("SELECT AVG(age) FROM user WHERE city = :city")
fun getAverageAgeByCity(city: String): Double?
 
// 统计符合条件的用户数量，返回值直接映射为 Int
@Query("SELECT COUNT(*) FROM user WHERE age >= :minAge")
fun countUsersAboveAge(minAge: Int): Int
 
// 获取每个城市的用户数量，按城市分组
// Room 要求查询多列时使用 data class 或 Object 接收结果
data class CityCount(val city: String, val count: Int)
 
@Query("SELECT city, COUNT(*) as count FROM user GROUP BY city")
fun getUserCountByCity(): List<CityCount>

data class UserWithBook(
    val userName: String,
    val userAge: Int,
    val bookTitle: String,
    val bookAuthor: String
)
 
@Query("""
    SELECT user.name AS userName, user.age AS userAge,
           book.title AS bookTitle, book.author AS bookAuthor
    FROM user
    INNER JOIN book ON user.id = book.ownerId
    WHERE user.id = :userId
""")
fun getUserWithBooks(userId: Long): List<UserWithBook>

@Query("SELECT * FROM user ORDER BY name ASC LIMIT :pageSize OFFSET :offset")
// :pageSize 指定每页加载多少条记录
// :offset 指定跳过多少条记录（offset = pageSize * (pageIndex - 1)）
fun getUsersPaged(pageSize: Int, offset: Int): List<User>

@Dao
interface UserDao {
 
    // 插入单个 User 对象。返回值可以是 void、long（新记录的主键）、或 List<Long>（批量插入时）
    @Insert
    fun insertUser(user: User): Long
    // ↑ 返回值类型为 Long，表示新插入记录的自增主键值。
    // 如果插入失败（违反约束等），Room 会抛出 SQLiteConstraintException。
 
    // 插入多个 User 对象。Room 会将这些对象全部插入，返回所有新记录的主键列表
    @Insert
    fun insertUsers(users: List<User>): List<Long>
 
    // 插入一个用户并等待Completable完成（RxJava3环境）
    @Insert
    fun insertUserRx(user: User): Completable
}

// onConflict = OnConflictStrategy.REPLACE：冲突时用新记录替换旧记录（先DELETE再INSERT）
@Insert(onConflict = OnConflictStrategy.REPLACE)
fun insertUser(user: User): Long
 
// onConflict = OnConflictStrategy.IGNORE：冲突时忽略插入操作，保留已有记录
@Insert(onConflict = OnConflictStrategy.IGNORE)
fun insertUserIgnore(user: User): Long
 
// onConflict = OnConflictStrategy.ABORT：冲突时中止事务并抛出异常（默认行为）
@Insert(onConflict = OnConflictStrategy.ABORT)
fun insertUserAbort(user: User): Long

// 带关系数据的插入：需要在一个事务中同时插入 User 和关联的 Books
// 具体实现在 Repository 层完成，详见后续 Relation 章节
@Transaction
fun insertUserWithBooks(user: User, books: List<Book>) {
    // 1. 先插入 User，获取其生成的主键
    // 2. 为每本书设置 ownerId 为新插入的 User 主键
    // 3. 批量插入 Books
}

@Dao
interface UserDao {
 
    // 更新单个 User 对象。Room 根据 user.id 找到对应行，更新其他字段
    // 返回值为 int，表示受影响的行数（通常为 1）
    @Update
    fun updateUser(user: User): Int
 
    // 批量更新多个 User 对象。Room 会执行多次 UPDATE 行更新操作
    @Update
    fun updateUsers(users: List<User>): Int
 
    // 支持部分字段更新：传入只包含需要更新字段的对象（利用 Kotlin 的 data class copy）
    @Update
    fun updateUserNameOnly(user: User): Int
}

// 使用 @Query 实现部分字段更新：只更新用户名称和邮箱
// UPDATE 语句中明确指定需要更新的列，ID 作为条件列
@Query("UPDATE user SET name = :name, email = :email WHERE id = :userId")
fun updateUserNameAndEmail(userId: Long, name: String, email: String): Int
 
// 使用 @Query 实现批量条件更新：所有年龄超过指定值且城市匹配的用户，年龄增加指定岁数
@Query("UPDATE user SET age = age + :years WHERE age > :thresholdAge AND city = :city")
fun incrementAgeForEligibleUsers(thresholdAge: Int, city: String, years: Int): Int
 
// 使用 @Query 实现原子递增：更新计数器（并发安全）
@Query("UPDATE counter SET value = value + 1 WHERE id = :counterId")
fun incrementCounter(counterId: Long): Int

@Dao
interface UserDao {
 
    // 删除单个 User 对象。Room 根据 user.id 找到对应行并删除
    // 返回值为 int，表示受影响的行数
    @Delete
    fun deleteUser(user: User): Int
 
    // 批量删除多个 User 对象
    @Delete
    fun deleteUsers(users: List<User>): Int
 
    // 删除 Entity 的所有记录（传入一个只包含主键值的对象）
    @Delete
    fun deleteUserById(user: User): Int
}

@Dao
interface UserDao {
 
    // 删除所有年龄低于指定值的用户
    @Query("DELETE FROM user WHERE age < :minAge")
    fun deleteUsersBelowAge(minAge: Int): Int
 
    // 删除指定城市的所有用户
    @Query("DELETE FROM user WHERE city = :city")
    fun deleteUsersByCity(city: String): Int
 
    // 删除所有用户（截断表，速度最快）
    @Query("DELETE FROM user")
    fun deleteAllUsers()
 
    // 删除重复记录：保留每个名字最新插入的那条（保留ID最大的）
    @Query("""
        DELETE FROM user
        WHERE id NOT IN (
            SELECT MAX(id) FROM user GROUP BY name
        )
    """)
    fun deleteDuplicateUsers(): Int
}

@Dao
interface UserDao {
 
    // @RawQuery 接收一个 SupportSQLiteQuery 对象作为参数
    // SupportSQLiteQuery 可以在运行时动态构建
    fun getUsersByRawQuery(query: SupportSQLiteQuery): List<User>
 
    // 结合 Kotlin 的 lambda 扩展，可以更便捷地构建动态查询
    fun getUsersByDynamicQuery(
        tableName: String,
        whereClause: String?,
        args: Array<String>
    ): List<User> {
        val queryBuilder = SimpleSQLiteQuery(
            "SELECT * FROM $tableName" +
            (if (whereClause != null) " WHERE $whereClause" else ""),
            args  // 绑定参数，防止 SQL 注入
        )
        return getUsersByRawQuery(queryBuilder)
    }
}

// 在 ViewModel 或 Repository 中调用 DAO 方法
class UserRepository(private val userDao: UserDao) {
 
    // 方式一：使用 Kotlin 协程（推荐）
    fun insertUser(user: User) {
        // io dispatcher 是专门用于 I/O 操作的线程池
        CoroutineScope(Dispatchers.IO).launch {
            userDao.insertUser(user)
        }
    }
 
    // 方式二：使用 LiveData/Flow 自动切线程（Room 内部处理）
    fun getAllUsersFlow(): Flow<List<User>> {
        return userDao.getAllUsersFlow()
    }
 
    // 方式三：使用 RxJava
    fun getAllUsersRx(): Single<List<User>> {
        return userDao.getAllUsersRx()
            .subscribeOn(Schedulers.io())
    }
}

@Dao  // 标记为 Room DAO 接口
interface UserDao {
 
    // ========== 查询操作 ==========
 
    // 查询所有用户，返回 LiveData 自动在后台线程执行，UI 自动观察变化
    @Query("SELECT * FROM user ORDER BY name ASC")
    fun getAllUsersLiveData(): LiveData<List<User>>
 
    // 查询所有用户，返回 Flow（热流），数据变化时自动推送新值
    @Query("SELECT * FROM user ORDER BY name ASC")
    fun getAllUsersFlow(): Flow<List<User>>
 
    // 按 ID 查询单个用户，? 允许返回 null（ID 不存在时）
    @Query("SELECT * FROM user WHERE id = :userId")
    fun getUserById(userId: Long): User?
 
    // 带条件的多参数查询
    @Query("""
        SELECT * FROM user
        WHERE (:minAge IS NULL OR age >= :minAge)
          AND (:city IS NULL OR city = :city)
        ORDER BY age DESC
    """)
    fun searchUsers(minAge: Int?, city: String?): Flow<List<User>>
 
    // 聚合查询：统计用户总数
    @Query("SELECT COUNT(*) FROM user")
    fun getUserCount(): Int
 
    // 分页查询
    @Query("SELECT * FROM user ORDER BY name ASC LIMIT :limit OFFSET :offset")
    fun getUsersPaged(limit: Int, offset: Int): List<User>
 
    // ========== 插入操作 ==========
 
    // 插入单个用户，返回新记录的自增主键
    @Insert(onConflict = OnConflictStrategy.REPLACE)
    // REPLACE 策略：若主键冲突则替换旧记录
    suspend fun insertUser(user: User): Long
    // suspend 关键字：Room 生成协程兼容的协程实现，可在挂起函数中调用
 
    // 批量插入，返回所有新记录的主键列表
    @Insert(onConflict = OnConflictStrategy.REPLACE)
    suspend fun insertUsers(users: List<User>): List<Long>
 
    // ========== 更新操作 ==========
 
    // 更新单个用户（基于主键）
    @Update
    suspend fun updateUser(user: User): Int
 
    // 使用 @Query 精细化更新：只更新指定字段
    @Query("UPDATE user SET age = :newAge, city = :newCity WHERE id = :userId")
    suspend fun updateUserProfile(userId: Long, newAge: Int, newCity: String): Int
 
    // ========== 删除操作 ==========
 
    // 删除单个用户（基于主键）
    @Delete
    suspend fun deleteUser(user: User): Int
 
    // 条件删除
    @Query("DELETE FROM user WHERE age < :minAge")
    suspend fun deleteYoungUsers(minAge: Int): Int
 
    // 清空全表
    @Query("DELETE FROM user")
    suspend fun deleteAllUsers()
 
    // ========== 批量操作（组合使用）==========
 
    // 在一个事务中执行多个操作
    @Transaction
    fun replaceAllUsers(newUsers: List<User>) {
        // Transaction 注解确保以下两个操作在同一个数据库事务中执行
        // 原子性保证：要么全部成功，要么全部回滚
        deleteAllUsers()           // 先清空
        insertUsers(newUsers)      // 再批量插入
    }
}

@Query("SELECT COUNT(*) FROM user WHERE city = :city")
fun getUserCountByCity(city: String): Int  // 无结果时返回 0
 
@Query("SELECT AVG(age) FROM user")
fun getAverageAge(): Double?  // 使用可空类型区分“无结果”和“结果为0”的情况

// Flow 版本：数据流式推送
userDao.getAllUsersFlow().collect { users ->
    // 每当数据库中 user 表发生变化（插入/更新/删除），
    // 此 lambda 会被重新调用，users 为最新的数据快照
    updateUI(users)
}
 
// LiveData 版本：带生命周期感知的观察
userDao.getAllUsersLiveData().observe(viewLifecycleOwner) { users ->
    // 当 Activity/Fragment 处于 RESUMED 状态时才更新 UI
    // 在后台时自动暂停观察，避免无谓的资源消耗
    updateUI(users)
}

// 定义一个包含关系数据的 data class
data class UserWithBooks(
    @Embedded val user: User,          // 将 User 实体的所有字段展开嵌入到此 data class 中
    @Relation(
        parentColumn = "id",           // User 表中的主键列名
        entityColumn = "ownerId"       // Book 表中的外键列名
    )
    val books: List<Book>              // Room 会自动执行第二条查询获取关联的 Books
)
 
// DAO 中使用 @Relation 的方法必须使用 @Transaction 修饰
@Transaction
@Query("SELECT * FROM user WHERE id = :userId")
fun getUserWithBooks(userId: Long): UserWithBooks?

// kotlin
// build.gradle 中声明自动迁移模块依赖
// implementation "androidx.room:room-runtime:2.6.1"
// implementation "androidx.room:room-ktx:2.6.1"  // KTX 支持
 
@Database(
    version = 3,
    entities = [User::class, Article::class],
    // 声明自动迁移规范，Room 会自动推断 Schema 变化
    autoMigrations = [
        AutoMigration(from = 1, to = 2),
        AutoMigration(from = 2, to = 3)
    ]
)
abstract class AppDatabase : RoomDatabase() {
 
    companion object {
        @Volatile
        private var INSTANCE: AppDatabase? = null
 
        fun getInstance(context: Context): AppDatabase {
            return INSTANCE ?: synchronized(this) {
                val builder = Room.databaseBuilder(
                    context.applicationContext,
                    AppDatabase::class.java,
                    "app_database"
                )
 
                // 如果找不到对应版本的 Migration，
                // 则销毁数据库并重建（注意：会丢失所有数据）
                builder.fallbackToDestructiveMigration()
 
                // 更精细的控制：仅在降级时允许破坏性重建
                // builder.fallbackToDestructiveMigrationFrom(2, 3)
 
                builder.build().also { INSTANCE = it }
            }
        }
    }
}

// kotlin
// User 实体类 - 版本 1
@Entity(tableName = "users")
data class User(
    @PrimaryKey(autoGenerate = true)
    val id: Long = 0,
    val name: String,
    val email: String,
    val createdAt: Long = System.currentTimeMillis()
)

// kotlin
// User 实体类 - 版本 3（最终形态）
@Entity(
    tableName = "users",
    indices = [Index(value = ["username"], unique = true)]  // 用户名唯一约束
)
data class User(
    @PrimaryKey(autoGenerate = true)
    val id: Long = 0,
    val username: String,
    val phone: String,
    val createdAt: Long = System.currentTimeMillis()
)
 
// Article 实体类 - 版本 3 新增
@Entity(
    tableName = "articles",
    foreignKeys = [
        ForeignKey(
            entity = User::class,
            parentColumns = ["id"],
            childColumns = ["authorId"],
            onDelete = ForeignKey.CASCADE  // 删除用户时级联删除其文章
        )
    ],
    indices = [Index(value = ["authorId"])]  // 外键列建立索引
)
data class Article(
    @PrimaryKey(autoGenerate = true)
    val id: Long = 0,
    val title: String,
    val content: String,
    val authorId: Long,
    val publishedAt: Long = System.currentTimeMillis()
)
 
// 一对多关系
data class UserWithArticles(
    @Embedded val user: User,
    @Relation(
        parentColumn = "id",
        entityColumn = "authorId"
    )
    val articles: List<Article>
)

// kotlin
import androidx.room.migration.Migration
import androidx.sqlite.db.SupportSQLiteDatabase
 
// 第一个迁移：从版本 1 升级到版本 2
// 这个迁移的核心任务是将 email 字段拆分为 username 和 phone
// 同时需要处理旧数据的迁移策略
val MIGRATION_1_2 = object : Migration(1, 2) {
    override fun migrate(database: SupportSQLiteDatabase) {
        // 步骤 1：创建一张临时表，结构与版本 2 的 User 表一致
        // 这里使用临时表的原因是 SQLite 不支持直接 ALTER COLUMN
        database.execSQL("""
            CREATE TABLE users_new (
                id INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL,
                username TEXT NOT NULL,
                phone TEXT NOT NULL,
                createdAt INTEGER NOT NULL
            )
        """.trimIndent())
 
        // 步骤 2：将旧表中的数据迁移到新表
        // 旧表中只有 email 字段，我们假设旧 email 的本地部分（@ 符号前）
        // 作为新的 username，完整的 email 作为新的 phone
        // 这是一种常见的数据推断策略，实际项目中应与产品确认
        database.execSQL("""
            INSERT INTO users_new (id, username, phone, createdAt)
            SELECT
                id,
                -- 提取 email 中 @ 符号前的字符串作为用户名
                -- SUBSTR(..., 1, INSTR(...)-1) 是 SQLite 中截取子字符串的写法
                CASE
                    WHEN INSTR(email, '@') > 1
                    THEN SUBSTR(email, 1, INSTR(email, '@') - 1)
                    ELSE 'user_' || id  -- 如果 email 格式异常，生成默认用户名
                END AS username,
                phone,
                createdAt
            FROM (
                -- 步骤 2a：创建临时 phone 列，初始为空字符串
                SELECT id, name, email, '', createdAt FROM users
            )
        """.trimIndent())
 
        // 步骤 3：删除旧表
        database.execSQL("DROP TABLE users")
 
        // 步骤 4：将临时表重命名为正式表名
        database.execSQL("ALTER TABLE users_new RENAME TO users")
    }
}
 
// 第二个迁移：从版本 2 升级到版本 3
// 这个迁移的任务是新增 articles 表并建立外键关系
val MIGRATION_2_3 = object : Migration(2, 3) {
    override fun migrate(database: SupportSQLiteDatabase) {
        // 步骤 1：创建 Article 表
        database.execSQL("""
            CREATE TABLE articles (
                id INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL,
                title TEXT NOT NULL,
                content TEXT NOT NULL,
                authorId INTEGER NOT NULL,
                publishedAt INTEGER NOT NULL,
                FOREIGN KEY(authorId) REFERENCES users(id) ON DELETE CASCADE
            )
        """.trimIndent())
 
        // 步骤 2：为 authorId 列建立索引，加速按作者查询文章的场景
        database.execSQL("""
            CREATE INDEX index_articles_authorId ON articles(authorId)
        """.trimIndent())
 
        // 步骤 3：为 users 表的 username 列建立唯一索引
        database.execSQL("""
            CREATE UNIQUE INDEX index_users_username ON users(username)
        """.trimIndent())
    }
}

// kotlin
@Database(
    version = 3,
    entities = [User::class, Article::class],
    exportSchema = true  // 必须开启 Schema 导出，用于自动迁移和版本对比
)
abstract class AppDatabase : RoomDatabase() {
 
    abstract fun userDao(): UserDao
    abstract fun articleDao(): ArticleDao
 
    companion object {
        private const val DATABASE_NAME = "app_database"
 
        @Volatile
        private var INSTANCE: AppDatabase? = null
 
        fun getInstance(context: Context): AppDatabase {
            return INSTANCE ?: synchronized(this) {
                val builder = Room.databaseBuilder(
                    context.applicationContext,
                    AppDatabase::class.java,
                    DATABASE_NAME
                )
 
                // 将所有手动迁移对象添加到构建器中
                builder.addMigrations(MIGRATION_1_2, MIGRATION_2_3)
 
                builder.build().also { INSTANCE = it }
            }
        }
    }
}

// groovy - build.gradle (app module)
android {
    defaultConfig {
        // roomSchemaExportDir 的配置方式在较新版本中已更改为 ksp 参数
        // 但 room { } 闭包的方式仍然广泛使用
    }
}
 
room {
    schemaLocation = "$projectDir/schemas"
    // 开启注解处理器以支持自动迁移
    annotationProcessorOptions {
        arguments += ["room.schemaLocation": "$projectDir/schemas".toString()]
    }
}

// kotlin
val MIGRATION_COMPLEX = object : Migration(3, 4) {
    override fun migrate(database: SupportSQLiteDatabase) {
        // 显式开启事务，确保迁移的原子性
        database.beginTransaction()
        try {
            // 执行多个 SQL 操作
            database.execSQL("CREATE TABLE category_new (...)")
            database.execSQL("INSERT INTO category_new SELECT * FROM category")
            database.execSQL("DROP TABLE category")
            database.execSQL("ALTER TABLE category_new RENAME TO category")
 
            // 标记事务成功
            database.setTransactionSuccessful()
        } finally {
            // 无论成功或失败，都必须结束事务
            database.endTransaction()
        }
    }
}

// kotlin
// 使用 AutoMigrationSpec 进行自定义数据转换
@Database(
    version = 4,
    entities = [User::class, Article::class],
    autoMigrations = [
        AutoMigration(
            from = 3,
            to = 4,
            spec = UserAutoMigrationSpec::class  // 指定自定义迁移规格
        )
    ],
    exportSchema = true
)
abstract class AppDatabase : RoomDatabase()
 
// 自定义迁移规格类，可以实现更精细的自动迁移控制
@DeleteTable(tableName = "users")
@RenameTable(fromTableName = "articles", toTableName = "posts")
class UserAutoMigrationSpec : AutoMigrationSpec {
    // 可以在迁移前或迁移后执行额外的处理逻辑
    override fun onPostMigrate(database: SupportSQLiteDatabase) {
        // 迁移完成后的回调，例如初始化默认数据
        database.execSQL("""
            INSERT OR IGNORE INTO users (username, phone)
            VALUES ('system', '00000000000')
        """.trimIndent())
    }
}

// kotlin
import androidx.room.Room
import androidx.room.testing.MigrationTestHelper
import androidx.sqlite.db.framework.FrameworkSQLiteOpenHelperFactory
import androidx.test.platform.app.InstrumentationRegistry
 
class MigrationTest {
 
    private val helper = MigrationTestHelper(
        InstrumentationRegistry.getInstrumentation(),
        AppDatabase::class.java.qualifiedName,
        FrameworkSQLiteOpenHelperFactory()
    )
 
    @Test
    fun testMigration1To2() {
        // 步骤 1：创建版本 1 的数据库（使用旧的 Schema 文件）
        val database = helper.createDatabase("test_db", 1)
 
        // 步骤 2：向版本 1 的数据库中插入测试数据
        database.apply {
            execSQL("INSERT INTO users (name, email, createdAt) VALUES ('Alice', 'alice@example.com', 1000)")
            execSQL("INSERT INTO users (name, email, createdAt) VALUES ('Bob', 'bob@example.com', 2000)")
            close()
        }
 
        // 步骤 3：执行迁移到版本 2
        val migratedDatabase = helper.runMigrationsAndValidate(
            "test_db",
            2,          // 目标版本
            true,       // 是否验证迁移后的内容
            MIGRATION_1_2  // 使用的迁移对象
        )
 
        // 步骤 4：验证迁移结果
        val cursor = migratedDatabase.query("SELECT username, phone FROM users ORDER BY id")
        cursor.moveToFirst()
 
        // Alice 的 email 是 alice@example.com
        // 预期迁移后 username 为 "alice"，phone 为 "alice@example.com"
        assert(cursor.getString(0) == "alice")
        assert(cursor.getString(1) == "alice@example.com")
 
        cursor.moveToNext()
 
        // Bob 的 email 是 bob@example.com
        assert(cursor.getString(0) == "bob")
        assert(cursor.getString(1) == "bob@example.com")
 
        cursor.close()
        migratedDatabase.close()
    }
}