第3章 单列索引设计与创建

3.1 单列索引核心原理

单列索引是数据库索引中最基础的结构，它在表的某一列上构建一个排好序的键值对集合，每个键值对应一个行ID（ROWID）。当执行 WHERE 条件查询时，数据库不需要逐行扫描整个表，而是通过索引的B+树结构进行 O(log n) 级别的二分查找，直接定位目标行。

B+树索引的核心特征包括：

• 有序性：所有键值在叶子节点上按升序排列，相邻叶子节点通过指针形成单向链表，支持高效范围扫描。
• 多级路由：内部节点仅存储键值用于路由，不存储实际数据，叶子节点才存储键值与行ID指针。
• 扇出效应：每个内部节点可包含几十到几百个键值，使得3~4层B+树即可管理数百万条记录。

3.2 @Index注解参数详解

Room使用 @Index 注解在 @Entity 中声明索引，编译期自动生成对应的 CREATE INDEX SQL语句。注解定义在 androidx.room.Index 中，包含三个关键参数：

3.3 索引命名规范

统一的命名规范能让团队成员从名称上快速识别索引类型、归属表和字段，避免重复创建。以下是推荐的命名规则：

• 普通单列索引：idx_表名_列名（示例：idx_users_email）
• 唯一单列索引：uidx_表名_列名（示例：uidx_users_phone）
• 复合索引：idx_表名_列1_列2（示例：idx_orders_userid_status）
• 全小写：统一使用小写字母 + 下划线，避免大小写混用带来的SQLite兼容问题

3.4 在@Entity中定义单列索引

下面以用户实体 User 为例，展示如何创建两个单列索引：唯一索引（邮箱）和普通索引（姓名）。

步骤1：定义Entity与索引

import androidx.room.ColumnInfo
import androidx.room.Entity
import androidx.room.Index
import androidx.room.PrimaryKey

@Entity(
    tableName = "users",
    indices = [
        Index(value = ["email"], name = "idx_users_email", unique = true),
        Index(value = ["name"], name = "idx_users_name")
    ]
)
data class User(
    @PrimaryKey
    val uid: Long,
    @ColumnInfo(name = "name")
    val name: String,
    @ColumnInfo(name = "email")
    val email: String
)

步骤2：Room编译后生成的等效SQL

-- 创建表（包含索引）
CREATE TABLE IF NOT EXISTS users (
    uid INTEGER NOT NULL PRIMARY KEY,
    name TEXT,
    email TEXT
);

-- 创建唯一索引
CREATE UNIQUE INDEX IF NOT EXISTS idx_users_email ON users(email);

-- 创建普通索引
CREATE INDEX IF NOT EXISTS idx_users_name ON users(name);

步骤3：DAO中的查询示例

import androidx.room.Dao
import androidx.room.Query

@Dao
interface UserDao {
    @Query("SELECT * FROM users WHERE email = :email")
    suspend fun findByEmail(email: String): User?

    @Query("SELECT * FROM users WHERE name = :name")
    suspend fun findByName(name: String): List<User>
}

3.5 验证索引生效

索引创建后，必须通过 EXPLAIN QUERY PLAN 确认查询是否真正使用了索引，而不是执行全表扫描。以下是两种验证方式。

3.5.1 使用SQLite命令行直接验证

-- 假设数据库文件为 room_db.db，先用sqlite3打开
sqlite3 room_db.db

-- 查看已创建的索引
sqlite> .indices users

-- 输出示例：
-- idx_users_email
-- idx_users_name

-- 使用EXPLAIN QUERY PLAN分析查询计划
sqlite> EXPLAIN QUERY PLAN SELECT * FROM users WHERE email = 'test@example.com';

-- 期望输出（使用索引）：
-- SEARCH TABLE users USING INDEX idx_users_email (email=?)

-- 对比：未使用索引的查询计划（全表扫描）
sqlite> EXPLAIN QUERY PLAN SELECT * FROM users WHERE name LIKE '%张三%';

-- 输出（全表扫描）：
-- SCAN TABLE users

3.5.2 通过Room的Database Inspector验证（Android Studio）

• 运行App并打开 View → Tool Windows → App Inspection
• 选择 Database Inspector 标签页
• 打开目标数据库，点击 Query 选项卡
• 输入 EXPLAIN QUERY PLAN SELECT * FROM users WHERE email = 'test@example.com';
• 查看结果集中的 detail 列，包含 USING INDEX 即为命中索引

3.6 性能对比分析

以下数据来自对100万行记录的 users 表进行的基准测试，硬件环境为：骁龙8 Gen2、12GB RAM、Android 14。每个查询重复100次取中位数。

3.7 常见错误与解决方案

• 错误1：索引列被表达式包裹
  WHERE LOWER(email) = 'test@example.com' → 索引失效。
  解决：存储时统一小写，查询时直接匹配原始值。
• 错误2：隐式类型转换
  WHERE phone = 13800138000（phone列为TEXT）→ 索引失效。
  解决：查询参数类型与列类型严格一致，使用 "13800138000"。
• 错误3：索引名称自动生成导致迁移混乱
  未指定 name，表结构变更后索引名变，Migration 脚本因索引名不匹配而失败。
  解决：始终显式声明 name，并将索引名纳入数据库版本变更记录。
• 错误4：对低选择性列建索引
  如性别列（只有 'M'/'F' 两种值），全表扫描比使用索引更高效。
  解决：选择度 < 0.1 的列不建议建单列索引，考虑复合索引或直接全表扫描。

3.8 优化结果验证清单

完成单列索引设计与创建后，使用以下清单逐项验证优化效果：