# 存储库模式 ## 概述此技能有助于实现此锻炼跟踪器应用程序中使用的存储库模式。该模式提供了对 Dexie (IndexedDB) 的干净抽象，具有类型安全接口、一致的错误处理和标准化的 CRUD 操作。 ## 架构概述 **分层方法：** 接口→实现→提供者→公共API ↓ ↓ ↓ ↓ db/接口 db/impl/dexie db/provider db/index **流量：** 1. 在`db/interfaces.ts`中定义存储库接口 2. 在 `db/implementations/dexie/[entity].ts` 中使用 Dexie 实现 3. 在工厂提供程序中注册 (`db/implementations/dexie/index.ts`) 4. 导出公共 getter (`db/index.ts`) 5. 通过 `getEntityRepository()` 在功能中使用 ## 核心工作流程创建新存储库时请遵循以下 6 个步骤： ### 第 1 步：定义接口位置：`src/db/interfaces.ts` 使用标准 CRUD 方法定义存储库接口：导出类型 EntityRepository = { getAll(): Promise> getById(id: 字符串): Promise 创建（实体：省略）：Promise 更新（id：字符串，更新：部分>）：Promise 删除（id：字符串）：Promise // ... 特定于实体的查询 } 添加到“RepositoryProvider”：导出类型 RepositoryProvider = { // ... 现有的实体：EntityRepository } **指南：** * 使用 `ReadonlyArray` 和 `Readonly` 作为参数 * 未找到时`getById`返回`undefined`（不抛出） * `create` 返回创建的实体以及生成的 ID * `update` 和 `delete` 返回 `void` * 使用 `Omit<>` 排除自动生成的字段（`id`、`createdAt`） ### 第 2 步：添加架构类型位置：`src/db/schema.ts` 使用“Db”前缀定义数据库类型： /** * 实体存储在数据库中。 * 使用 null 而不是 undefined 来表示显式的“无值”语义。 */ 导出类型 DbEntity = { id: 字符串名称：字符串值：字符串| null // 使用null，而不是undefined 创建于：编号更新时间：数量 | null // null 直到第一次更新 } **主要约定：** * **始终** 对数据库类型使用 `Db` 前缀 * 使用“null”表示“无值”（而不是“未定义”） * 将用户输入的数字存储为“string”（例如，“kg: string”、“reps: string”） * 对变体使用具有“kind”属性的可区分联合 * 如果需要，包括类型保护：`导出函数 isDbEntity(x:unknown): x is DbEntity` ### 步骤 3：更新数据库类位置：`src/db/implementations/dexie/database.ts` 添加表和索引：导出类 WorkoutTrackerDb 扩展 Dexie { // ... 现有表实体！：表构造函数（）{ 超级（'锻炼追踪器'） // 增加版本号 this.version(3).stores({ // ... 现有表 Entity: 'id, name,createdAt', // 索引：主要+经常查询的字段 }) } } **索引指南：** * 始终索引主键（自动） * `where()`、`orderBy()`、`equals()` 中使用的索引字段 * 连接的索引外键 * 连接表的复合索引：`'[field1+field2], field1, field2'` ### 步骤 4：实施存储库位置：`src/db/implementations/dexie/[entity].ts` 创建返回存储库实现的工厂函数：从 '@/db/interfaces' 导入类型 { EntityRepository } 从 '@/db/schema' 导入类型 { DbEntity } 从 '@/lib/tryCatch' 导入 { createDatabaseError, tryCatch } 从 './database' 导入类型 { WorkoutTrackerDb } 从'./database'导入{generateId} /** * EntityRepository 的 Dexie 实现。 */ 导出函数 createDexieEntityRepository(db: WorkoutTrackerDb): EntityRepository { 返回{ 异步 getAll(): Promise> { const [错误，实体] =等待 tryCatch( db.entities.orderBy('createdAt').reverse().toArray(), ）如果（错误）{ throw createDatabaseError('LOAD_FAILED', '检索实体', 错误) } 返回实体 }, 异步 getById(id: string): Promise { const [错误，实体] =等待 tryCatch(db.entities.get(id)) 如果（错误）{ throw createDatabaseError('LOAD_FAILED', `检索 ID 为 ${id} 的实体`, error) } 返回实体 }, 异步创建（实体：省略 , ): Promise { const newEntity: DbEntity = { ...实体， id: 生成Id(), 创建时间：Date.now(), } const [错误] =等待 tryCatch(db.entities.add(newEntity)) 如果（错误）{ 抛出 createDatabaseError('SAVE_FAILED', '创建实体', 错误) } 返回新实体 }, 异步更新( id：字符串，更新： Partial>, ): 承诺 { const [错误，updatedCount] = 等待 tryCatch( db.entities.update(id, { ...更新， updateAt: Date.now(), // 自动注入时间戳 }), ）如果（错误）{ throw createDatabaseError('SAVE_FAILED', `用 id ${id} 更新实体`, error) } if (updatedCount === 0) { throw createDatabaseError('NOT_FOUND', `id 为 ${id} 的实体未找到`) } }, 异步删除（id：字符串）：Promise { const [错误] =等待 tryCatch(db.entities.delete(id)) 如果（错误）{ throw createDatabaseError('SAVE_FAILED', `删除 ID 为 ${id} 的实体`, error) } // 软删除：没有 NOT_FOUND 检查 }, } } **关键模式：** * 对所有操作使用 `tryCatch()` 包装器（首选模式） * 两阶段错误检查：操作失败+未找到 * 自动注入时间戳：`createdAt`、`updatedAt` * 使用 `generateId()` 获取新 ID * 软删除：如果实体不存在则不会出错 ### 步骤 5：在 Factory Provider 中注册位置：`src/db/implementations/dexie/index.ts` 导入并添加到提供程序：从 './entity' 导入 { createDexieEntityRepository } 导出函数 createDexieRepositoryProvider(): RepositoryProvider { 返回{ activeWorkout：createDexieActiveWorkoutRepository（db），锻炼：createDexieWorkoutsRepository(db), // ...现有存储库实体：createDexieEntityRepository(db), // 添加此内容 } } ### 步骤 6：导出公共 Getter 位置：`src/db/index.ts` 添加 getter 函数：导出函数 getEntityRepository(): EntityRepository { 返回 getRepositoryProvider().entity } ## 功能中的用法从 '@/db' 导入 { getEntityRepository } 从 '@/db/schema' 导入类型 { DbEntity } 导出函数 useEntities() { const 实体 = ref>([]) constEntityRepo = getEntityRepository() 异步函数 loadEntities() { Entity.value =等待entityRepo.getAll() } 异步函数 createEntity(名称: 字符串, 值: 字符串 | null) { const newEntity =等待entityRepo.create（{名称，值，updatedAt：null}）实体.值 = [...实体.值, newEntity] } 异步函数 updateEntity(id: string, 更新: Partial) { 等待entityRepo.update（id，更新）等待加载实体（） } 异步函数deleteEntity(id: string) { 等待entityRepo.delete(id) 实体.值 = 实体.值.过滤器(e => e.id !== id) } onMounted(() => loadEntities()) 返回{ 实体：只读（实体），创建实体，更新实体，删除实体， } } ## 关键原则 ### 1\.错误处理 **首选：tryCatch 包装器** const [错误，结果] = wait tryCatch(操作) 如果（错误）{ 抛出 createDatabaseError('ERROR_CODE', '描述', 错误) } **错误代码：** * `SAVE_FAILED` \- 创建、更新、删除操作 * `LOAD_FAILED` \- 读取操作 * `NOT_FOUND` \- 实体不存在 ### 2\.时间戳管理在存储库方法中自动注入时间戳： * `create()` 中的 `createdAt: Date.now()` * `update()` 中的 `updatedAt: Date.now()` * 访问实体时`lastUsedAt: Date.now()` ### 3\. ID生成始终使用“database.ts”中的“generateId()”：从'./database'导入{generateId} 常量新实体 = { ...实体， id:generateId(), // crypto.randomUUID() } ### 4\.软删除如果实体不存在，则删除操作不会抛出：异步删除（id：字符串）：Promise { 等待 tryCatch(db.entities.delete(id)) // 没有 NOT_FOUND 检查 - 静默成功 } ### 5\.类型安全 * 使用 `Readonly` 和 `ReadonlyArray` 作为函数参数 * 使用 `Omit<>` 排除自动生成的字段 * 使用受歧视的联合并进行详尽的检查 * 定义类型保护以进行运行时类型检查 ## 文件参考 **创建存储库时的关键文件：** * `src/db/interfaces.ts` \- 接口定义 + RepositoryProvider * `src/db/schema.ts` \- Db 前缀的类型定义 * `src/db/implementations/dexie/database.ts` \- 表 + 索引 * `src/db/implementations/dexie/[entity].ts` \- 实现 * `src/db/implementations/dexie/index.ts` \- 工厂注册 * `src/db/index.ts` \- 公共 getter 导出 **公用事业进口：** * `@/lib/tryCatch` \- 错误处理实用程序 * `@/db/implementations/dexie/database` \-generateId() ## 详细参考资料有关完整示例和高级模式，请参阅： * **[references/examples.md]()** \- 完整的端到端示例： * 示例1：简单的CRUD存储库（注释） * 示例 2：复杂转换（具有多对多的标签） * 示例 3：通过函数重载扩展设置 * **[references/patterns.md]()** \- 详细模式目录： * 错误处理模式（直接抛出 vs tryCatch） * CRUD 模式（getAll、创建、更新、删除、时间戳） * 类型转换模式（辅助实用程序、深度克隆） * 高级模式（函数重载、单例、事务、批量操作） * 模式设计模式（可区分联合、索引、嵌入与引用） ## 常见场景 ### 场景 1：简单的 CRUD 存储库实体需要基本存储吗？请参阅 **examples.md → 示例 1（注释）**。 **快速清单：** 1.用getAll/getById/create/update/delete定义接口 2.添加带有Db前缀的DbEntity类型 3.添加带索引的表 4.使用tryCatch模式实现 5. 注册与导出 ### 场景 2：复杂关系需要多对多关系或复杂查询？请参阅 **examples.md → 示例 2（标签）**。 **模式：** 连接表+事务处理+使用跟踪。 ### 场景 3：扩展设置添加新设置？请参阅 **examples.md → 示例 3**。 **模式：** 添加可区分的联合成员 + 函数重载 + 默认值。 ### 场景 4：类型之间的转换需要在模板和锻炼之间进行转换吗？请参阅 **patterns.md → 类型转换模式**。 **模式：** 具有详尽 switch 语句的辅助实用程序。 ### 场景 5：批量操作导入/导出还是批量删除？请参阅 **patterns.md → 高级模式 → 批量操作**。 **模式：** 交易 + `Promise.all()` \+ `bulkAdd()`。 ## 测试支持用于单元测试的模拟存储库：从 '@/__tests__/helpers/mockRepositories' 导入 { createMockRepositories } const mockRepos = createMockRepositories() mockRepos.entity.getAll.mockResolvedValue([...]) 与 fake-indexeddb 的集成测试是通过测试助手自动设置的。 ## 迁移策略更新架构版本时： 1.增加`database.ts`中的版本号 2. 在 `.stores({})` 中添加新表/索引 3. Dexie自动处理迁移 4. 对于数据迁移，使用`.upgrade()`回调这个版本(3) .商店({ 实体：'id，名称，创建时间'， }) .upgrade(tx => { // 可选的数据迁移逻辑 return tx.table('entities').toCollection().modify(entity => { 实体.newField = '默认' }) }) ## 项目特定的存储库 ### `Db*` 类型与域类型方面|数据库（`Db*`）|域名 ---|---|--- 文件 | `src/db/schema.ts` | `src/类型/` 前缀| `DbWorkout`、`DbSet` | “锻炼”、“设置” 没有价值| `空` | `未定义` 优化为 |存储|应用逻辑 ### 可用的存储库 **SettingsRepository** \- 具有默认值的键值存储： const repo = getSettingsRepository() 等待 repo.get('主题') // '轻' | '黑暗' | ‘系统’ 等待 repo.get('defaultRestTimer') // 数字 wait repo.set({ key: '主题', value: '黑暗' }) wait repo.getAll() // 所有设置与默认值合并等待 repo.reset('主题') **CustomExercisesRepository** \- 练习 CRUD： const repo = getCustomExercisesRepository() 等待 repo.getAll() 等待 repo.getById(id) 等待 repo.add({ id:generateId(), name: 'Squat', ... }) wait repo.update(id, { name: '后蹲' }) 等待 repo.delete(id) **锻炼存储库** \- 已完成的锻炼： const repo = getWorkoutsRepository() 等待 repo.getAll() 等待 repo.getById(id) 等待 repo.create(convertWorkoutToDb(workout)) 等待 repo.delete(id) **ActiveWorkoutRepository** \- 单例主动锻炼： const repo = getActiveWorkoutRepository() 等待 repo.load() 等待 repo.save(dbActiveWorkout) 等待 repo.delete() 等待 repo.exists() **BenchmarksRepository** \- 基准训练： const repo = getBenchmarksRepository() 等待 repo.getAll() 等待 repo.getById(id) 等待 repo.create({ id:generateId(), name: 'Fran', ... }) 等待 repo.update(id, { name: 'Fran (Scaled)' }) 等待 repo.delete(id) **TemplatesRepository** \- 锻炼模板： const repo = getTemplatesRepository() 等待 repo.getAll() 等待 repo.getById(id) 等待 repo.create(模板) 等待 repo.update(id, 更改) 等待 repo.delete(id) ### 使用转换器跨越域/数据库边界时始终进行转换：从'@/db/converters'导入{convertWorkoutToDb，convertDbToWorkout} // 域 → 数据库 const dbWorkout = ConvertWorkoutToDb(锻炼) 等待 getWorkoutsRepository().create(dbWorkout) // 数据库 → 域 const dbWorkout = 等待 getWorkoutsRepository().getById(id) 常量锻炼=convertDbToWorkout(dbWorkout) ### 使用 buildPartialUpdate 进行部分更新 Dexie 的 update() 会覆盖对象中的所有键。使用 `buildPartialUpdate` 仅修改提供的字段：从 '@/db/partialUpdate' 导入 { buildPartialUpdate } const NULLABLE_FIELDS = ['装备', '肌肉', '图像'] // 只包含更新中存在的键 // 将 undefined → null 转换为可空字段 const dbUpdates = buildPartialUpdate(更新, NULLABLE_FIELDS) 等待 repo.update(id, dbUpdates) **为什么**：如果没有过滤，`{ name: 'Squat', Equipment: undefined }` 会将 Equipment 设置为 null，即使您只想更新名称。 ## 项目特定的问题 ### 1\.在数据库中使用“null”，在域中使用“undefined” IndexedDB 不支持“未定义”： // 数据库类型类型 DbExercise = { 设备：设备 | null // 使用 null } // 域类型类型练习 = { Equipment?: 设备//使用未定义 } ### 2\.在测试中始终重置数据库从'@/__tests__/setup'导入{resetDatabase} beforeEach(异步() => { 等待重置数据库() }) ### 3\.在边界处转换类型 // 不好 - 类型不匹配等待 getWorkoutsRepository().create(workout) // 好 - 首先转换 const dbWorkout = ConvertWorkoutToDb(锻炼) 等待 getWorkoutsRepository().create(dbWorkout)

存储库模式

包含技能