更新记录

1.0.0（2026-01-19）

首次发布

平台兼容性

uni-app x(4.65)

SQLite 插件说明文档

一、插件概述

1.1 插件简介

该SQLite插件是基于UniApp X + UTS开发的Android端本地数据库操作插件，封装了SQLite数据库的核心操作（连接管理、CRUD、事务、多表关联查询等），提供了面向对象的模型化开发方式，简化了原生SQLite的使用复杂度，同时保证了类型安全和操作规范性。

1.2 核心特性

• 开箱即用：封装数据库连接、表管理、数据操作等核心能力，无需编写原生SQL即可完成基础操作；
• 模型化开发：支持通过定义模型自动创建表结构，挂载CRUD方法，降低开发成本；
• 丰富的查询能力：支持基础单表查询、多表关联查询（一对一/一对多/多对多）、复杂条件过滤；
• 事务支持：提供事务开启、提交、回滚能力，保证批量操作的原子性；
• 类型安全：基于UTS强类型定义，所有入参、出参均有明确类型约束，减少运行时错误；
• 防SQL注入：参数化查询设计，避免直接拼接SQL带来的注入风险。

1.3 适用场景

• UniApp X 开发的Android端本地数据存储场景；
• 需要结构化存储、复杂查询的本地业务（如本地缓存、离线数据、小型业务数据）；
• 偏好模型化开发、不想编写原生SQL的开发场景；
• 需要多表关联查询、事务保障的本地数据操作场景。

二、快速开始

2.1 安装与引入

将插件文件放置在 uni_modules/se-sqlite 目录下，在业务代码中引入核心类：

import { SQLiteHelper } from '@/uni_modules/se-sqlite'

2.2 基础使用流程

步骤1：初始化数据库连接

// 初始化SQLiteHelper实例，参数为数据库名称（自动创建.db后缀）
const sqlite = new SQLiteHelper('demo');
// 检查连接状态
console.log(sqlite.isOpen()); // 输出：true

步骤2：定义数据模型

import { ModelDefType } from '@/uni_modules/se-sqlite'

// 定义用户表模型
export const userModelDef : ModelDefType = {
  tableName: 'user', // 表名（仅字母/数字，以字母开头）
  columns: [
    { name: "id", type: "INTEGER", primaryKey: true, autoIncrement: true },
    { name: "name", type: "TEXT" },
    { name: "age", type: "INTEGER", default: 0 },
    { name: "createAt", type: "DATE", default: "NOW" }
  ]
};

步骤3：挂载模型并使用

// 挂载模型（自动创建表）
const UserModel = sqlite.defineModel(userModelDef);

// 基础查询
const result = UserModel.query({
  where: { age: { $gt: 18 } } // 查询年龄大于18的用户
});
console.log(result);

三、核心API详解

3.1 SQLiteHelper 核心类

SQLiteHelper 是插件的核心入口类，负责数据库连接管理、基础操作执行、模型定义等，所有数据库操作均基于此类实例。

3.1.1 构造函数

3.1.2 连接管理

3.1.3 数据库信息查询

3.1.4 基础数据操作

3.1.5 事务操作

3.1.6 模型定义

3.2 Model 模型类

Model 类是基于模型定义生成的实例类，封装了针对具体表的CRUD方法，无需关注底层SQL，直接通过对象方法操作数据。

3.2.1 核心方法

3.3 工具方法（transform.uts）

工具方法主要用于内部转换，部分对外暴露，核心作用是将开发者友好的参数转换为SQLite可执行的SQL语句。

四、类型定义规范

4.1 核心类型说明

所有类型定义均在 interface.uts 中，核心类型如下：

4.2 字段类型映射

插件支持的字段类型与SQLite原生类型的映射关系：

五、最佳实践

5.1 目录结构规范

uni_modules/
└── se-sqlite/          # 插件核心目录
utils/
└── db/                     # 数据库管理目录
    ├── models/             # 模型定义目录
    │   ├── user.uts        # 用户表模型
    │   ├── house.uts       # 房产表模型
    │   └── relUserHouse.uts # 多对多关联表模型
    └── index.uts           # 数据库初始化与模型导出
pages/
└── index/
    └── index.uvue          # 业务页面使用模型

5.2 模型定义规范

1. 表名/字段名仅包含字母/数字，且以字母开头；
2. 主键建议命名为id，类型为INTEGER且开启autoIncrement；
3. 时间字段建议命名为createAt/updateAt，类型为DATE，默认值设为NOW；
4. 外键字段建议命名为“关联表名+Id”（如ownerId关联user表的id）；
5. 多对多关联表建议命名为rel+主表名+关联表名（如relUserHouse）。

5.3 多表关联查询示例

一对一/一对多关联

// 查询用户及关联的房产
const result = UserModel.queryComplex({
  where: { age: { $gt: 15 } },
  include: [
    {
      model: HouseModel.modelDef, // 关联房产模型
      as: 'houses', // 结果嵌套别名
      columns: ['label'], // 关联表查询字段
      foreignKey: 'ownerId', // 房产表的外键
      targetKey: 'id', // 用户表的主键
      required: false // LEFT JOIN（true为INNER JOIN）
    }
  ]
});

多对多关联（通过中间表）

// 查询用户及通过中间表关联的房产
const result = UserModel.queryComplex({
  columns: ['name', 'age'],
  include: [{
    model: HouseModel.modelDef,
    as: 'houses',
    columns: ['label'],
    through: {
      table: 'relUserHouse', // 中间表名
      mainKey: 'id', // 用户表主键
      mainForeignKey: 'ownerId', // 中间表关联用户的外键
      otherKey: 'id', // 房产表主键
      otherForeignKey: 'houseId', // 中间表关联房产的外键
      columns: ['ownerId', 'houseId'], // 中间表返回字段
      as: 'Rel' // 中间表嵌套别名
    }
  }]
});

5.4 事务使用示例

// 批量插入数据，事务保障
try {
  sqlite.beginTransaction(); // 开启事务
  const result1 = UserModel.insert({ name: '张三', age: 20 });
  const result2 = HouseModel.insert({ label: '北京某小区', ownerId: result1.data.rowId });
  sqlite.submitTransaction(); // 标记事务成功
  sqlite.endTransaction(); // 结束事务（提交）
  console.log('批量插入成功');
} catch (e) {
  sqlite.endTransaction(); // 结束事务（回滚）
  console.error('批量插入失败，事务回滚：', e);
}

六、注意事项

6.1 通用注意事项

1. 数据库名称/表名/字段名仅支持字母/数字，且必须以字母开头，否则会抛出异常；
2. 所有操作均需保证数据库连接已开启（isOpen返回true），否则会返回失败结果；
3. 批量操作建议使用事务，避免部分成功部分失败；
4. 查询结果的游标会自动关闭，无需手动处理，但复杂查询需注意结果集大小，避免内存溢出；
5. 外键约束需在模型定义中配置，SQLite默认开启外键支持，插件已适配。

6.2 性能注意事项

1. 大量数据查询建议使用分页（limit/offset），避免一次性查询全部数据；
2. 多表关联查询尽量指定columns，只查询需要的字段，减少数据传输；
3. 频繁的插入/更新操作建议使用批量方法（insertBatch），减少数据库IO；
4. 复杂查询建议先通过getTableInfo确认表结构，避免字段名错误。

6.3 兼容性注意事项

1. 该插件仅支持Android端，基于UniApp X的UTS开发，不支持iOS/小程序；
2. 依赖UniApp X的UTS环境，需确保项目已配置正确的UTS编译环境；
3. SQLite版本由设备系统决定，插件已兼容主流版本（3.x）。

七、常见问题

7.1 连接相关

• Q：初始化时抛出“获取应用上下文失败”？ A：检查UniApp X项目配置，确保UTS环境初始化完成，应用上下文正常获取。
• Q：isOpen返回false？ A：可能是数据库名称不合法，或应用权限不足，检查名称规范并确保应用有存储权限。

7.2 模型定义相关

• Q：defineModel抛出“表名不符合命名规则”？ A：表名包含特殊字符或数字开头，修改为仅字母/数字且以字母开头。
• Q：外键约束不生效？ A：检查外键配置的field/refTable/refField是否正确，确保关联表已创建。

7.3 查询相关

• Q：where条件中的$gt/$in等操作符不生效？ A：检查条件格式是否正确，如$gt需传入对象格式：{ age: { $gt: 18 } }。
• Q：多表关联查询结果为空？ A：检查include配置的foreignKey/targetKey是否正确，required为true时会过滤无关联的数据。

总结

核心要点回顾

1. 该插件是UniApp X Android端的SQLite封装，核心入口为SQLiteHelper，模型化开发是核心特性；
2. 核心能力包括数据库连接管理、模型定义、CRUD操作、事务、多表关联查询，所有操作均返回ExecuteResult类型结果；
3. 开发规范：表名/字段名仅字母/数字且以字母开头，多表关联通过queryComplex实现，批量操作建议使用事务。

关键使用原则

• 优先使用模型化开发（defineModel），减少原生SQL编写；
• 复杂查询使用queryComplex，基础查询使用query；
• 所有条件查询均使用参数化方式（where对象），避免直接拼接SQL；
• 操作完成后根据ExecuteResult的success字段判断是否成功，msg字段获取详细信息。