# useFetch SSR Hook

这是一个专为 Vue 3 SSR 应用设计的 `useFetch` hook，支持服务端预取和客户端水合。

## 特性

- ✅ **SSR 兼容**: 支持服务端预取和客户端水合
- ✅ **数据缓存**: 避免重复请求，提升性能
- ✅ **错误处理**: 完整的错误处理机制
- ✅ **加载状态**: 内置 loading 状态管理
- ✅ **TypeScript**: 完整的类型支持
- ✅ **灵活配置**: 支持自定义缓存键、转换函数等

## 基本用法

```typescript
import { useFetch } from './compose/useFetch'

// 基本用法
const { data, error, pending, refresh } = useFetch('/api/users')

// 带配置的用法
const { data, error, pending, refresh } = useFetch(
  'https://api.example.com/users/1',
  {
    key: 'user-1',           // 缓存键
    server: true,            // 启用服务端预取
    transform: (data) => ({   // 数据转换
      id: data.id,
      name: data.name
    }),
    onError: (err) => {      // 错误处理
      console.error(err)
    }
  }
)
```

## API 参考

### useFetch(url, options?)

#### 参数

- `url`: `string | (() => string) | (() => Promise<string>)` - 请求 URL
- `options`: `UseFetchOptions` - 配置选项

#### 返回值

- `data`: `Ref<T | null>` - 响应数据
- `error`: `Ref<Error | null>` - 错误信息
- `pending`: `Ref<boolean>` - 加载状态
- `refresh()`: `() => Promise<void>` - 刷新数据
- `execute()`: `() => Promise<void>` - 手动执行请求

### UseFetchOptions

```typescript
interface UseFetchOptions {
  key?: string                    // 缓存键
  server?: boolean               // 是否启用服务端预取
  default?: () => any            // 默认值
  transform?: (data: any) => any  // 数据转换函数
  onError?: (error: Error) => void // 错误处理函数
}
```

## SSR 集成

### 服务端设置

在 `entry-server.ts` 中：

```typescript
import { createSSRContext } from './compose/useFetch'

export async function render(url: string) {
  const { app } = createApp()
  
  // 创建 SSR 上下文
  const ssrContext = createSSRContext()
  app.config.globalProperties.$ssrContext = ssrContext
  
  const html = await renderToString(app)
  
  // 将数据序列化到 HTML
  const ssrData = JSON.stringify(Array.from(ssrContext.cache?.entries() || []))
  const head = `
    <script>
      window.__SSR_CONTEXT__ = {
        cache: new Map(${ssrData})
      };
    </script>
  `
  
  return { html, head }
}
```

### 客户端设置

在 `entry-client.ts` 中：

```typescript
import { hydrateSSRContext, clearSSRContext } from './compose/useFetch'

// 水合 SSR 数据
if (typeof window !== 'undefined' && window.__SSR_CONTEXT__) {
  hydrateSSRContext(window.__SSR_CONTEXT__)
}

app.mount('#app')

// 水合完成后清理
clearSSRContext()
```

## 高级用法

### 动态 URL

```typescript
const userId = ref(1)
const { data } = useFetch(() => `/api/users/${userId.value}`)
```

### 条件请求

```typescript
const shouldFetch = ref(false)
const { data } = useFetch(
  () => shouldFetch.value ? '/api/data' : null,
  { server: false } // 禁用服务端预取
)
```

### 错误处理

```typescript
const { data, error, pending } = useFetch('/api/data', {
  onError: (err) => {
    // 自定义错误处理
    console.error('请求失败:', err)
    // 可以显示用户友好的错误消息
  }
})
```

### 数据转换

```typescript
const { data } = useFetch('/api/users', {
  transform: (users) => users.map(user => ({
    id: user.id,
    name: user.name,
    email: user.email
  }))
})
```

## 注意事项

1. **缓存键**: 确保为不同的请求使用唯一的缓存键
2. **服务端预取**: 只在需要 SEO 或首屏性能的场景下启用
3. **错误处理**: 始终提供错误处理逻辑
4. **内存管理**: 在 SPA 模式下注意清理不需要的缓存

## 示例

查看 `src/components/DataFetch.vue` 获取完整的使用示例。