4. 一对一关系映射定义与实现

一对一关系是数据库关系映射中最基础的形式。在 Room 中实现一对一关系需要掌握四个核心元素：外键约束用于强制引用完整性，嵌套对象用于承载关联数据，@Relation 注解用于声明关系类型，DAO 查询方法用于返回组合后的数据对象。本章通过一个用户与其地址的经典案例，带您完成从实体定义到查询返回的完整闭环。

4.1 实体定义与外键约束

以 User 和 Address 为例，每个用户只能拥有一个地址。在 Address 实体中通过外键引用 User 的主键，并设置级联删除策略。

@Entity
public class User {
    @PrimaryKey(autoGenerate = true)
    public long userId;
    public String name;
    public int age;
}

@Entity(
    foreignKeys = @ForeignKey(
        entity = User.class,
        parentColumns = "userId",
        childColumns = "userOwnerId",
        onDelete = ForeignKey.CASCADE
    ),
    indices = @Index(value = "userOwnerId")
)
public class Address {
    @PrimaryKey(autoGenerate = true)
    public long addressId;
    public String street;
    public String city;
    public long userOwnerId;  // 外键，关联 User.userId
}

4.2 定义关系嵌套对象

创建一个 POJO 类，包含主实体 User 和关联实体 Address，通过 @Relation 注解声明一对一关系。Room 要求被关联的字段类型必须是实体类或实体类的集合，且注解中需要指定 parentColumn 和 entityColumn。

public class UserWithAddress {
    @Embedded
    public User user;

    @Relation(
        parentColumn = "userId",
        entityColumn = "userOwnerId"
    )
    public Address address;
}

4.3 DAO 查询方法编写

Room 会识别 @Relation 注解并生成内部 JOIN 查询，开发者只需编写返回关系 POJO 的方法即可。注意：查询语句必须使用标准的 SQL JOIN 语法，Room 无法自动推断关联条件。

@Dao
public interface UserDao {
    // 一对一：查询所有用户及其地址
    @Transaction
    @Query("SELECT * FROM User")
    List<UserWithAddress> getUsersWithAddresses();

    // 通过用户 ID 查询单个用户及其地址
    @Transaction
    @Query("SELECT * FROM User WHERE userId = :userId")
    UserWithAddress getUserWithAddress(long userId);
}

4.4 编译时验证与常见错误

Room 在编译阶段会严格检查一对一映射的正确性：

• 外键列类型不匹配：parentColumn 与 entityColumn 必须类型兼容（如 long 与 Long 可以，但 long 与 int 会报错）。
• 缺少 @Transaction：若返回关系 POJO 的方法未标注 @Transaction，编译时提示 relationship without @Transaction。
• 关联字段为 null：若某用户没有地址，返回的 UserWithAddress.address 字段为 null，需要在业务层处理空值。

4.5 数据迁移与性能优化

当表结构变更（如新增外键列）时，需编写 Migration 脚本。一对一场景中，外键约束可能影响数据库写入顺序，需确保先插入主实体再插入关联实体。

static final Migration MIGRATION_2_3 = new Migration(2, 3) {
    @Override
    public void migrate(@NonNull SupportSQLiteDatabase database) {
        database.execSQL("ALTER TABLE Address ADD COLUMN userOwnerId INTEGER NOT NULL DEFAULT 0");
        database.execSQL("CREATE INDEX IF NOT EXISTS index_address_userOwnerId ON Address(userOwnerId)");
        // 注意：若已有数据，需手动修复外键关系
    }
};

4.6 一对一关系映射全景图

下方 SVG 展示了从实体定义到查询返回的完整数据流，包括编译时验证、外键关系、@Relation 注解映射以及 DAO 执行过程。