使用 Room 將資料儲存在本機資料庫 Android Jetpack 的一部分。

如果應用程式需要處理大量結構化資料, 將資料保存在本機最常見的用途是快取相關的 以便在裝置無法存取網路時 仍可在離線狀態下瀏覽這些內容

Room 持續性程式庫透過 SQLite 提供抽象層, 可以順暢存取資料庫,並充分發揮 SQLite 的效用我們要用 Room 具有以下優點:

  • 提供 SQL 查詢的編譯時間驗證。
  • 盡可能減少重複且容易出錯的樣板的便利註解 再也不是件繁重乏味的工作
  • 簡化資料庫遷移路徑。

基於這些考量,我們強烈建議改用 Room 直接使用 SQLite API

設定

如要在應用程式中使用 Room,請將下列依附元件新增至應用程式的 build.gradle 檔案:

Groovy

dependencies {
    def room_version = "2.6.1"

    implementation "androidx.room:room-runtime:$room_version"
    annotationProcessor "androidx.room:room-compiler:$room_version"

    // To use Kotlin annotation processing tool (kapt)
    kapt "androidx.room:room-compiler:$room_version"
    // To use Kotlin Symbol Processing (KSP)
    ksp "androidx.room:room-compiler:$room_version"

    // optional - RxJava2 support for Room
    implementation "androidx.room:room-rxjava2:$room_version"

    // optional - RxJava3 support for Room
    implementation "androidx.room:room-rxjava3:$room_version"

    // optional - Guava support for Room, including Optional and ListenableFuture
    implementation "androidx.room:room-guava:$room_version"

    // optional - Test helpers
    testImplementation "androidx.room:room-testing:$room_version"

    // optional - Paging 3 Integration
    implementation "androidx.room:room-paging:$room_version"
}

Kotlin

dependencies {
    val room_version = "2.6.1"

    implementation("androidx.room:room-runtime:$room_version")
    annotationProcessor("androidx.room:room-compiler:$room_version")

    // To use Kotlin annotation processing tool (kapt)
    kapt("androidx.room:room-compiler:$room_version")
    // To use Kotlin Symbol Processing (KSP)
    ksp("androidx.room:room-compiler:$room_version")

    // optional - Kotlin Extensions and Coroutines support for Room
    implementation("androidx.room:room-ktx:$room_version")

    // optional - RxJava2 support for Room
    implementation("androidx.room:room-rxjava2:$room_version")

    // optional - RxJava3 support for Room
    implementation("androidx.room:room-rxjava3:$room_version")

    // optional - Guava support for Room, including Optional and ListenableFuture
    implementation("androidx.room:room-guava:$room_version")

    // optional - Test helpers
    testImplementation("androidx.room:room-testing:$room_version")

    // optional - Paging 3 Integration
    implementation("androidx.room:room-paging:$room_version")
}

主要元件

Room 有三個主要元件:

  • 保留目標的資料庫類別 並做為 應用程式保留資料。
  • 代表的資料實體 納入應用程式資料庫中的資料表。
  • 資料存取物件 (DAO), 為應用程式提供可用於查詢、更新、插入及刪除的方法 儲存資料庫資料

資料庫類別為應用程式提供與 建立資料庫反過來,應用程式可以使用 DAO 從 視為關聯資料實體物件的執行個體。這個應用程式也可以 使用定義的資料實體更新對應資料表中的資料列,或者 即可建立要插入的新資料列。圖 1 說明瞭 Room 的不同元件

圖 1. Room 資料庫架構圖。

實作範例

本節說明採用單一標頭的 Room 資料庫實作範例 以及單一 DAO

資料實體

以下程式碼定義 User 資料實體。「User」的每個例項 代表應用程式資料庫中 user 資料表的某一列。

Kotlin

@Entity
data class User(
    @PrimaryKey val uid: Int,
    @ColumnInfo(name = "first_name") val firstName: String?,
    @ColumnInfo(name = "last_name") val lastName: String?
)

Java

@Entity
public class User {
    @PrimaryKey
    public int uid;

    @ColumnInfo(name = "first_name")
    public String firstName;

    @ColumnInfo(name = "last_name")
    public String lastName;
}

如要進一步瞭解 Room 中的資料實體,請參閱使用 Room 定義資料 實體

資料存取物件 (DAO)

以下程式碼定義了名稱為 UserDao 的 DAO。UserDao 會提供 應用程式的其餘部分會用來與 user 資料表中資料互動的方法。

Kotlin

@Dao
interface UserDao {
    @Query("SELECT * FROM user")
    fun getAll(): List<User>

    @Query("SELECT * FROM user WHERE uid IN (:userIds)")
    fun loadAllByIds(userIds: IntArray): List<User>

    @Query("SELECT * FROM user WHERE first_name LIKE :first AND " +
           "last_name LIKE :last LIMIT 1")
    fun findByName(first: String, last: String): User

    @Insert
    fun insertAll(vararg users: User)

    @Delete
    fun delete(user: User)
}

Java

@Dao
public interface UserDao {
    @Query("SELECT * FROM user")
    List<User> getAll();

    @Query("SELECT * FROM user WHERE uid IN (:userIds)")
    List<User> loadAllByIds(int[] userIds);

    @Query("SELECT * FROM user WHERE first_name LIKE :first AND " +
           "last_name LIKE :last LIMIT 1")
    User findByName(String first, String last);

    @Insert
    void insertAll(User... users);

    @Delete
    void delete(User user);
}

如要進一步瞭解 DAO,請參閱使用 Room 存取資料 DAO

資料庫

以下程式碼定義了用於保存資料庫的 AppDatabase 類別。 AppDatabase 定義了資料庫設定,並做為應用程式的主要設定 存取保留點。資料庫類別必須符合 下列情況:

  • 類別必須使用 @Database 註解, 包含 entities 陣列,列出所有與資料庫相關聯的資料實體。
  • 類別必須是可擴充的抽象類別 RoomDatabase
  • 針對與資料庫關聯的每個 DAO 類別,系統會提供資料庫類別 必須定義無引數並傳回例項的抽象方法 DAO 類別

Kotlin

@Database(entities = [User::class], version = 1)
abstract class AppDatabase : RoomDatabase() {
    abstract fun userDao(): UserDao
}

Java

@Database(entities = {User.class}, version = 1)
public abstract class AppDatabase extends RoomDatabase {
    public abstract UserDao userDao();
}

注意: 如果您的應用程式在單一程序中執行,請遵循 例項化 AppDatabase 時的單例設計模式 物件。每個 RoomDatabase 執行個體都非常昂貴 在單一程序中很少存取多個執行個體。

如果您的應用程式在多個程序中執行,請納入 資料庫建構工具中的 enableMultiInstanceInvalidation() 呼叫。這樣一來,當您有 AppDatabase 的執行個體時 您可以在每個程序中撤銷共用資料庫檔案 這項撤銷作業會自動套用至 其他程序中的 AppDatabase

用量

定義資料實體、DAO 和資料庫物件後, 可以使用下列程式碼建立資料庫執行個體:

Kotlin

val db = Room.databaseBuilder(
            applicationContext,
            AppDatabase::class.java, "database-name"
        ).build()

Java

AppDatabase db = Room.databaseBuilder(getApplicationContext(),
        AppDatabase.class, "database-name").build();

接著,您可以使用 AppDatabase 的抽象方法取得執行個體 YAML 檔案反過來,您可以使用 DAO 執行個體的方法 存取資料庫:

Kotlin

val userDao = db.userDao()
val users: List<User> = userDao.getAll()

Java

UserDao userDao = db.userDao();
List<User> users = userDao.getAll();

其他資源

如要進一步瞭解 Room,請參閱下列其他資源:

範例

程式碼研究室

網誌