4. @NonNull 与索引关系：非空约束对索引选择的影响、SQLite NULL 处理、Room 自动索引

4.1 原理：NULL 在 SQLite 索引中的特殊地位

SQLite 的 B-Tree 索引将 NULL 值视为小于所有非 NULL 值，并默认在索引中排在最前面。这一行为导致查询计划优化器在选择索引时，会因 IS NULL、IS NOT NULL 以及 = NULL 的语义差异而产生完全不同的执行路径。

当字段上存在 @NonNull 约束时，Room 会在生成的表定义中添加 NOT NULL，SQLite 据此可以做出更精准的索引选择决策：

• 完全忽略 NULL：优化器不再需要分配部分索引空间给 NULL 值分支，索引密度更高。
• 支持“仅索引扫描”：查询所需列全部包含在索引中时，可直接扫描 B-Tree 叶节点，无需回表。
• 避免“误判”：对于 WHERE col = ? 且 col 为 NOT NULL，优化器可确定不会产生 NULL 匹配，优先使用等值查找。

4.2 SQLite NULL 处理与索引选择规则

下表总结了不同 NULL 场景下索引的使用倾向：

查询条件	字段约束	索引使用情况	扫描类型
col = value	NOT NULL	优先生效	精确索引查找
col = value	可为 NULL	可能使用，但需跳过 NULL 分支	范围扫描 + NULL 跳过
col IS NULL	NOT NULL	不会使用索引（优化器推断无条件为假）	全表扫描（或直接返回空）
col IS NULL	可为 NULL	高效使用索引（NULL 在 B-Tree 左侧）	索引前缀扫描
col IS NOT NULL	NOT NULL	全索引扫描（所有行满足）	索引全覆盖扫描

4.3 Room 自动索引生成行为

Room 在编译时扫描实体类的 @NonNull 注解，自动生成以下索引策略：

• 主键：始终隐含 NOT NULL，自动创建唯一索引。
• 外键：如果关联字段标记为 @NonNull，Room 会生成 NOT NULL DDL，优化外键查找索引。
• @Index 注解：对 @NonNull 字段建立的索引，Room 在生成的 CREATE INDEX 中不会添加 WHERE 子句（因为不存在 NULL）。
• 联合索引：当索引第一列为 @NonNull 时，后续列可更高效地利用前缀匹配。

4.4 实现流程：从实体注解到查询计划验证

1. 定义实体：对需要查询的字段标记 @NonNull，同时添加 @Index 注解。
2. 编译生成 Schema：在 build.gradle 中配置 room.schemaLocation，观察生成的 create.sql 文件。
3. 执行 EXPLAIN QUERY PLAN：使用 Room 的 query() 方法或 Database Inspector 获取查询计划。
4. 对比测试：移除 @NonNull 后重新生成 Schema，比较查询计划中的 SEARCH vs SCAN 关键字。

4.5 代码/API 示例

实体定义（使用 @NonNull 和 @Index）：

@Entity(
    indices = {
        @Index(value = "email", unique = true)
    }
)
public class User {
    @PrimaryKey
    @NonNull
    public String id;

    @NonNull
    @ColumnInfo(name = "email")
    public String email;

    @Nullable
    public String nickname;
}

生成的 DDL（位于 schema 目录下的 .json 或 create.sql）：

CREATE TABLE User (
    id TEXT NOT NULL,
    email TEXT NOT NULL,
    nickname TEXT,
    PRIMARY KEY(id)
);
CREATE UNIQUE INDEX IF NOT EXISTS index_User_email ON User (email);

查询计划对比：

-- email 为 @NonNull 时的查询计划
EXPLAIN QUERY PLAN
SELECT * FROM User WHERE email = 'a@b.com';
-- 输出：0|0|0|SEARCH TABLE User USING INDEX index_User_email (email=?)

-- 若 email 未加 @NonNull，相同查询可能变为：
-- 0|0|0|SCAN TABLE User

4.6 调试：检查索引实际使用情况

• Android Studio 的 Database Inspector：打开 View → Tool Windows → App Inspection，选择数据库，执行 EXPLAIN QUERY PLAN，直接观察 detail 列中的 USING INDEX 或 SCAN。
• 命令行 sqlite3：如果使用测试数据库，通过 adb shell 或本地文件运行 sqlite3 your.db "EXPLAIN QUERY PLAN ..."。
• Room 日志：在 Room.databaseBuilder() 中启用 .setQueryCallback() 打印每条查询的 SQL，辅助定位索引命中情况。

4.7 常见错误与性能优化

错误/场景	影响	优化措施
为 @Nullable 字段建立索引并在 WHERE 中使用 =	索引需要保留 NULL 分支，导致 B-Tree 节点分裂增多，查询可能降级为全表扫描	尽量将该字段改为 @NonNull 或使用 IS NULL 条件配合复合索引
联合索引中首列可为 NULL	无法利用前缀最左匹配，即使后续列非空也需过滤大量 NULL	将非空列放在联合索引第一列
忘记给 @NonNull 字段建索引	尽管约束存在，但无索引时 WHERE 条件仍需全表扫描	对高频查询字段显式添加 @Index
在 OR 或 IN 子句中混合 NULL 可能性	优化器倾向对复杂条件使用全表扫描	拆分为多个 UNION ALL 子查询，并保证每个子查询的字段 NOT NULL

性能优化 checklist：

• 所有参与 WHERE、JOIN、ORDER BY 的字段，首选 @NonNull 类型。
• 对于业务上不可能为空的字段（如自增 ID、必填邮箱），使用 @NonNull 替代 @Nullable。
• 定期通过 EXPLAIN QUERY PLAN 审查索引覆盖情况，特别关注 SCAN 条目。
• 数据库迁移时通过 ALTER TABLE ADD COLUMN ... NOT NULL DEFAULT ... 避免引入 NULL。

4.8 部署与稳定性建议

• 发布前自动检查：在 CI 流水线中运行 Room Schema Export，解析 create.sql 确保所有 @Index 字段都包含 NOT NULL。
• 迁移兼容性：旧表增加列时，使用 ALTER TABLE ... ADD COLUMN ... NOT NULL DEFAULT ''，并确认索引重建。
• 监控：在 RoomDatabase 的 openHelper 回调中记录 EXPLAIN QUERY PLAN 日志，针对慢查询预警。
• 版本升级：保持实体中 @NonNull 与数据库 schema 的一致性，避免因注解错漏导致自动索引失效。