SQLiteData 通过 Swift 宏提供类型安全的 SQLite 访问,简化数据库建模与查询,并自动处理 CloudKit 同步、迁移和异步模式。
用途:用于 SQLite 持久化、查询、写入、迁移以及 CloudKit 私有数据库同步等场景。
主要能力:使用 @Table 宏定义表模型、主键、列和枚举;使用 @FetchAll、@FetchOne、@Selection 进行基础查询、过滤、排序和连接;使用 @Fetch 配合 FetchKeyRequest 实现动态查询、递归 CTE 或直接读取;支持插入、更新、upsert、删除和事务管理;可在 SwiftUI 视图中使用 @FetchAll/@FetchOne,支持 @Observable 模型和动画;支持 UIKit 集成、TCA 集成和 observe {};通过 DatabaseMigrator 或 #sql() 宏创建迁移;支持 CloudKit 私有数据库同步、共享和同步委托;通过 @Dependency 注入数据库或同步引擎;支持测试数据库、种子数据和断言;支持触发器、自定义数据库函数、全文搜索 FTS5、性能调优、索引、自定义聚合、JSON 聚合、自连接、@Selection 列组、单表继承和数据库视图。
使用方式:先用 @Table 定义表模型,在视图或 @Observable 模型中使用 @FetchAll/@FetchOne 属性包装器,通过 @Dependency(.defaultDatabase) 访问数据库,在 database.write { } 事务中执行写入,并在首次使用前设置迁移。
限制与注意事项:避免 N+1 查询模式,应使用连接或批量获取;修改 @Table 后必须创建迁移,否则运行时崩溃;写入块应保持简短,避免长时间事务导致死锁或数据丢失;生产环境需实现所有 SyncDelegate 方法以处理错误和冲突;SwiftUI 视图中应使用谓词、限制和排序避免过度获取导致 UI 冻结。