akmon/components/supadb/SIMPLIFIED_API_GUIDE.md

AkSupa 简化API指南

概述

AkSupa 现在采用了简化的单一方法设计：只提供 executeAs<T>() 方法进行类型安全的数据访问，移除了所有冗余的类型转换方法。

重要变化

🚫 已移除的方法

• selectAs<T>()
• insertAs<T>()
• updateAs<T>()
• deleteAs<T>()
• rpcAs<T>()

✅ 统一的方法

• executeAs<T>() - 唯一的类型转换方法

设计理念

简洁性原则

• 一个方法解决所有问题：所有查询操作最终都要调用 execute()，executeAs<T>() 是其类型安全版本
• 减少API复杂性：不需要记住多个不同的方法名
• 保持一致性：无论是查询、插入、更新还是删除，都使用相同的方法

链式友好

// 所有操作都遵循相同的模式
const result = await supa
  .from('table')
  .operation() // select(), insert(), update(), delete(), rpc()
  .conditions() // eq(), gt(), like(), etc.
  .executeAs<T>(); // 统一的类型转换方法

使用示例

查询数据

// 多条记录
const users = await supa
  .from('users')
  .select('*')
  .eq('status', 'active')
  .executeAs<User[]>();

// 单条记录
const user = await supa
  .from('users')
  .select('*')
  .eq('id', 1)
  .single()
  .executeAs<User>();

插入数据

const newUser = await supa
  .from('users')
  .insert({
    name: 'John',
    email: 'john@example.com'
  })
  .executeAs<User>();

更新数据

const updatedUser = await supa
  .from('users')
  .update({ name: 'Jane' })
  .eq('id', 1)
  .executeAs<User>();

删除数据

const deletedUser = await supa
  .from('users')
  .delete()
  .eq('id', 1)
  .executeAs<User>();

RPC调用

const result = await supa
  .from('any_table')
  .rpc('my_function', { param1: 'value1' })
  .executeAs<ResultType>();

平台兼容性

平台	类型转换机制	说明
Android	UTSJSONObject.parse<T>()	真正的类型转换
HarmonyOS	UTSJSONObject.parse<T>()	真正的类型转换
Web/iOS	as T	类型断言

从旧版本迁移

旧代码

// 旧方式 - 多个方法
const users = await supa.selectAs<User[]>('users', null, { limit: 10 });
const newUser = await supa.insertAs<User>('users', userData);
const updated = await supa.updateAs<User>('users', filter, updateData);

新代码

// 新方式 - 统一方法
const users = await supa
  .from('users')
  .select('*')
  .limit(10)
  .executeAs<User[]>();

const newUser = await supa
  .from('users')
  .insert(userData)
  .executeAs<User>();

const updated = await supa
  .from('users')
  .update(updateData)
  .eq('id', userId)
  .executeAs<User>();

优势

1. API简洁：只需要记住一个方法
2. 类型安全：TypeScript 编译时检查
3. 平台兼容：Android/HarmonyOS 使用真正的类型转换
4. 链式友好：与现有的链式方法无缝集成
5. 维护性强：单一方法，减少维护成本

注意事项

1. 泛型类型：确保传入正确的类型参数 <T>
2. 错误处理：检查 result.error 和 result.data 的有效性
3. 性能考虑：Android 平台的类型转换有轻微性能开销
4. 调试模式：开发时会有转换过程的控制台输出

总结

通过采用单一的 executeAs<T>() 方法，AkSupa 现在提供了：

• 更简洁的API
• 更好的类型安全
• 更一致的使用体验
• 更容易维护的代码

这个设计遵循了"简单就是美"的原则，让开发者能够更专注于业务逻辑而不是API的复杂性。