npm package: @hz52410/uni-query
Description: 一个专为 uni-app 生态设计的轻量级数据获取库
Latest version: 1.0.4

# UniQuery

一个专为 uni-app 生态设计的轻量级数据获取库，提供类似 React Query 的请求管理、缓存和自动刷新功能。

## 特性

- 🚀 **跨平台兼容**：一套 API 支持小程序、App 和 H5
- 💾 **智能缓存**：LRU 算法管理缓存，自动过期清理
- 🔄 **自动重试**：请求失败自动重试机制
- 📦 **请求去重**：相同请求自动合并，避免重复请求
- 🌊 **流式支持**：支持微信小程序流式数据传输
- 🎯 **TypeScript**：完整的 TypeScript 类型支持
- ⚡ **轻量高效**：针对小程序环境优化

## 安装

```bash
npm install z-query
# 或
yarn add z-query
# 或
pnpm add z-query
```

## 快速开始

### 全局配置

在项目的 `main.js` 中进行全局配置：

```javascript
import { createApp } from 'vue'
import { UniQueryPlugin } from 'z-query'

const app = createApp(App)

// 注册 UniQuery 插件
app.use(UniQueryPlugin, {
  staleTime: 5 * 60 * 1000, // 默认缓存5分钟
  cacheTime: 24 * 60 * 60 * 1000, // 默认保留24小时
  manual: false, // 自动执行查询
  retry: 3, // 自动重试次数
  retryDelay: 1000, // 重试延迟时间
  cacheCapacity: 100, // 缓存容量限制
})

app.mount('#app')
```

### 基本使用

```vue
<template>
  <view v-if="loading">加载中...</view>
  <view v-else-if="error">错误: {{ error?.message }}</view>
  <view v-else>{{ data?.title }}</view>
  <button @click="refetch">刷新</button>
</template>

<script setup>
import { useQuery, fetchData } from 'z-query'

const { data, loading, error, refetch } = useQuery({
  queryKey: ['post', 1],
  queryFn: () => fetchData('/api/posts/1'),
  staleTime: 30 * 1000, // 缓存30秒
  retry: 2, // 失败后重试2次
})
</script>
```

## API 参考

### useQuery

```typescript
interface UseQueryOptions<T> {
  queryKey: string[] // 唯一标识查询的键
  queryFn: () => Promise<T> // 执行查询的函数
  staleTime?: number // 缓存过期时间（毫秒）
  cacheTime?: number // 缓存保留时间（毫秒）
  manual?: boolean // 是否手动触发查询
  retry?: number // 自动重试次数
  retryDelay?: number // 重试延迟时间（毫秒）
}

function useQuery<T>(options: UseQueryOptions<T>): {
  data: Ref<T | null> // 在模板中自动解包，在 script 中使用 .value
  loading: Ref<boolean>
  isLoading: Ref<boolean>
  error: Ref<Error | null>
  refetch: () => Promise<T>
  status: Ref<'loading' | 'success' | 'error' | 'idle'>
}
```

### fetchData

通用的请求函数，自动适配小程序和 H5 环境：

```typescript
import { fetchData } from 'z-query'

// 基本用法
const data = await fetchData('/api/posts', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer token'
  }
})

// POST 请求
const result = await fetchData('/api/posts', {
  method: 'POST',
  body: { title: 'New Post' }
})
```

## 小程序特有功能

### 流式请求支持

```typescript
const { data, loading } = useQuery({
  queryKey: ['ai-response'],
  queryFn: () => fetchData('/api/ai-response', {
    method: 'POST',
    body: { question: '你好' },
    enableChunked: true, // 启用流式传输
    chunkDecoder: (data) => {
      // #ifdef MP-WEIXIN
      return new TextDecoder().decode(data as Uint8Array)
      // #endif
    },
  }),
  staleTime: 0,
  manual: true,
})
```

## 缓存管理

UniQuery 使用 LRU（最近最少使用）算法管理缓存，并自动处理过期清理：

```typescript
import { QueryCacheManager } from 'z-query'

// 手动管理缓存
const cacheManager = new QueryCacheManager(100) // 容量100

// 获取缓存
const cached = cacheManager.get('key')

// 设置缓存
cacheManager.set('key', data, staleTime, cacheTime)

// 删除缓存
cacheManager.delete('key')

// 清空所有缓存
cacheManager.clear()
```

## 最佳实践

### 1. 合理配置缓存时间

```typescript
// 静态数据（如配置信息）
useQuery({
  queryKey: ['config'],
  queryFn: () => fetchData('/api/config'),
  staleTime: 24 * 60 * 60 * 1000, // 缓存24小时
  cacheTime: 30 * 24 * 60 * 60 * 1000, // 保留30天
})

// 动态数据（如用户信息）
useQuery({
  queryKey: ['user-info'],
  queryFn: () => fetchData('/api/user-info'),
  staleTime: 5 * 60 * 1000, // 缓存5分钟
  cacheTime: 24 * 60 * 60 * 1000, // 保留24小时
})
```

### 2. 手动触发查询

```typescript
const { data, loading, refetch } = useQuery({
  queryKey: ['todos'],
  queryFn: () => fetchData('/api/todos'),
  manual: true, // 手动触发
})

// 在需要时触发
onMounted(() => {
  refetch()
})
```

### 3. 错误处理

```vue
<script setup>
import { useQuery, fetchData } from 'z-query'
import { watch } from 'vue'

const { data, loading, error } = useQuery({
  queryKey: ['posts'],
  queryFn: () => fetchData('/api/posts'),
  retry: 3, // 自动重试3次
  retryDelay: 1000, // 每次重试间隔1秒
})

watch(error, (err) => {
  if (err) {
    console.error('请求失败:', err)
    // 处理错误
  }
})
</script>
```

## 开发

```bash
# 安装依赖
npm install

# 开发模式（监听文件变化）
npm run dev

# 构建
npm run build

# 类型检查
npm run type-check
```

## 许可证

MIT

## 贡献

欢迎提交 Issue 和 Pull Request！