156 lines
3.6 KiB
Markdown
156 lines
3.6 KiB
Markdown
# AkSupa 简化API指南
|
||
|
||
## 概述
|
||
|
||
AkSupa 现在采用了**简化的单一方法**设计：只提供 `executeAs<T>()` 方法进行类型安全的数据访问，移除了所有冗余的类型转换方法。
|
||
|
||
## 重要变化
|
||
|
||
### 🚫 已移除的方法
|
||
- `selectAs<T>()`
|
||
- `insertAs<T>()`
|
||
- `updateAs<T>()`
|
||
- `deleteAs<T>()`
|
||
- `rpcAs<T>()`
|
||
|
||
### ✅ 统一的方法
|
||
- `executeAs<T>()` - 唯一的类型转换方法
|
||
|
||
## 设计理念
|
||
|
||
### 简洁性原则
|
||
- **一个方法解决所有问题**：所有查询操作最终都要调用 `execute()`，`executeAs<T>()` 是其类型安全版本
|
||
- **减少API复杂性**：不需要记住多个不同的方法名
|
||
- **保持一致性**：无论是查询、插入、更新还是删除，都使用相同的方法
|
||
|
||
### 链式友好
|
||
```typescript
|
||
// 所有操作都遵循相同的模式
|
||
const result = await supa
|
||
.from('table')
|
||
.operation() // select(), insert(), update(), delete(), rpc()
|
||
.conditions() // eq(), gt(), like(), etc.
|
||
.executeAs<T>(); // 统一的类型转换方法
|
||
```
|
||
|
||
## 使用示例
|
||
|
||
### 查询数据
|
||
```typescript
|
||
// 多条记录
|
||
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>();
|
||
```
|
||
|
||
### 插入数据
|
||
```typescript
|
||
const newUser = await supa
|
||
.from('users')
|
||
.insert({
|
||
name: 'John',
|
||
email: 'john@example.com'
|
||
})
|
||
.executeAs<User>();
|
||
```
|
||
|
||
### 更新数据
|
||
```typescript
|
||
const updatedUser = await supa
|
||
.from('users')
|
||
.update({ name: 'Jane' })
|
||
.eq('id', 1)
|
||
.executeAs<User>();
|
||
```
|
||
|
||
### 删除数据
|
||
```typescript
|
||
const deletedUser = await supa
|
||
.from('users')
|
||
.delete()
|
||
.eq('id', 1)
|
||
.executeAs<User>();
|
||
```
|
||
|
||
### RPC调用
|
||
```typescript
|
||
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` | 类型断言 |
|
||
|
||
## 从旧版本迁移
|
||
|
||
### 旧代码
|
||
```typescript
|
||
// 旧方式 - 多个方法
|
||
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);
|
||
```
|
||
|
||
### 新代码
|
||
```typescript
|
||
// 新方式 - 统一方法
|
||
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的复杂性。
|