🚀 Fetcher

超轻量级 • 模块化 • TypeScript 优先 • 拦截器驱动 • LLM 流式 API 支持

🎯 Fetcher v2.9.1：从数据获取到全栈解决方案的华丽蜕变 ✨

🎉 Fetcher 框架迎来重大更新！v2.9.1 版本带来了全方位的功能增强和开发体验优化

✨ 核心亮点

🚀 React Hooks 全面升级

• 增强版 useFetcher Hook：新增超时控制和结果提取器，让数据获取更智能
• 全新查询 Hook 家族：引入 useQuery、usePagedQuery、useSingleQuery、useCountQuery、useListQuery 等专用钩子
• 自动执行功能：useQuery 支持自动执行查询，简化开发流程
• 竞态条件防护：内置请求 ID 跟踪，有效防止过时响应

📚 完整的 Storybook 文档生态

• 交互式演示：为所有 React Hooks 提供生动的 Storybook 示例
• 组件展示：新增 Fetcher 组件演示，包含 URL 参数和请求日志
• Ant Design 集成：完美整合 Antd 组件和配置提供器
• 详细 API 文档：全面更新使用指南和接口说明
• 在线文档：访问 https://fetcher.ahoo.me/ 查看完整的 Storybook 文档和交互示例

🔥 事件总线系统

• 跨标签页通信：基于 BroadcastChannel 和 StorageMessenger 实现多标签页消息同步
• 类型安全事件：完整的 TypeScript 支持，提供类型安全的事件总线
• 灵活的消息传递：支持自定义频道和通用事件总线模式
• 存储集成：KeyStorage 采用事件总线模式重新实现

🎯 可视化组件库

• 条件过滤器：新增 ID 条件过滤组件，支持多种过滤类型
• 标签输入组件：全新的 TagInput 组件，包含完整测试用例
• 多语言支持：过滤器操作符支持本地化翻译
• React Compiler 集成：提升组件性能和开发体验

⚡ 性能与开发体验

• 异步操作优化：全面支持 async/await，提升代码可读性
• 泛型错误处理：增强类型安全性，支持自定义错误类型
• 内存优化：使用 useMemo 优化 Hook 性能，减少不必要的重渲染
• Vitest 测试框架：引入现代化测试配置，提升测试效率

🔧 代码生成器增强

• OpenAPI 客户端生成：自动生成类型安全的 API 客户端代码
• 增强的 JSDoc 生成：支持模式约束和更丰富的文档注释
• 路径参数提取：改进的类型解析和参数处理
• 事件流支持：为客户端生成器添加事件流功能

🛠 技术栈更新

• React 最新版本：更新相关类型和依赖
• TypeScript 5.9.3：享受最新的类型系统特性
• ESLint 和 Vite：开发工具链全面升级
• PNPM v10.18.2：更快的包管理和磁盘空间效率

🎊 开发者体验

这个版本标志着 Fetcher 框架的成熟化进程，从纯粹的数据获取库演进为完整的全栈开发解决方案。无论是前端 React 开发、后端 API 集成，还是组件库建设，Fetcher v2.9.1 都提供了开箱即用的优秀体验。

立即升级，体验更智能、更高效的数据流管理！欢迎访问 Storybook 文档 查看详细的组件演示和 API 说明。

Fetcher 是一个现代化、类型安全的数据获取框架，致力于简化前端数据管理，提升开发效率。

import { createLlmFetcher, LlmClient } from './llmClient';

// 使用您的 API 配置初始化 LLM 客户端
const llmFetcher = createLlmFetcher({
  baseURL: 'https://api.openai.com/v1',
  apiKey: process.env.OPENAI_API_KEY || 'your-api-key',
  model: 'gpt-3.5-turbo',
});

const llmClient = new LlmClient();

// 流式聊天完成，逐个令牌输出
async function streamChatExample() {
  const stream = await llmClient.streamChat({
    messages: [
      { role: 'system', content: 'You are a helpful assistant.' },
      { role: 'user', content: 'Explain quantum computing in simple terms.' },
    ],
    stream: true,
  });

  for await (const event of stream) {
    if (event.data) {
      const chunk = event.data;
      const content = chunk.choices[0]?.delta?.content || '';
      process.stdout.write(content); // 实时输出
    }
  }
}

# 安装核心包
npm install @ahoo-wang/fetcher

# 或安装所有扩展，包括 LLM 流支持
npm install @ahoo-wang/fetcher @ahoo-wang/fetcher-decorator @ahoo-wang/fetcher-eventbus @ahoo-wang/fetcher-eventstream @ahoo-wang/fetcher-cosec

# 使用 pnpm (推荐)
pnpm add @ahoo-wang/fetcher

# 使用 yarn
yarn add @ahoo-wang/fetcher

import { Fetcher } from '@ahoo-wang/fetcher';

// 创建 fetcher 实例
const fetcher = new Fetcher({
  baseURL: 'https://api.example.com',
  timeout: 5000,
});

// 带路径和查询参数的 GET 请求
const response = await fetcher.get('/users/{id}', {
  urlParams: {
    path: { id: 123 },
    query: { include: 'profile' },
  },
});
const userData = await response.json<User>();

// 自动 JSON 转换的 POST 请求
const createUserResponse = await fetcher.post('/users', {
  body: { name: 'John Doe', email: 'john@example.com' },
});

import { NamedFetcher } from '@ahoo-wang/fetcher';
import {
  api,
  get,
  post,
  path,
  query,
  body,
} from '@ahoo-wang/fetcher-decorator';

// 注册命名 fetcher
const apiFetcher = new NamedFetcher('api', {
  baseURL: 'https://api.example.com',
});

// 使用装饰器定义服务
@api('/users', { fetcher: 'api' })
class UserService {
  @get('/')
  getUsers(@query('limit') limit?: number): Promise<User[]> {
    throw autoGeneratedError(limit);
  }

  @post('/')
  createUser(@body() user: User): Promise<User> {
    throw autoGeneratedError(user);
  }

  @get('/{id}')
  getUser(@path('id') id: number): Promise<User> {
    throw autoGeneratedError(id);
  }
}

// 使用服务
const userService = new UserService();
const users = await userService.getUsers(10);

import { Fetcher } from '@ahoo-wang/fetcher';

const fetcher = new Fetcher({ baseURL: 'https://api.example.com' });

// 添加带排序的请求拦截器
fetcher.interceptors.request.use({
  name: 'auth-interceptor',
  order: 100,
  intercept(exchange) {
    exchange.request.headers.Authorization = 'Bearer ' + getAuthToken();
  },
});

// 添加响应拦截器用于日志记录
fetcher.interceptors.response.use({
  name: 'logging-interceptor',
  order: 10,
  intercept(exchange) {
    console.log('Response:', exchange.response.status);
  },
});

import { Fetcher } from '@ahoo-wang/fetcher';
import { EventStreamInterceptor } from '@ahoo-wang/fetcher-eventstream';

const fetcher = new Fetcher({ baseURL: 'https://api.example.com' });
fetcher.interceptors.response.use(new EventStreamInterceptor());

// 流式实时事件 (通用 SSE)
const response = await fetcher.get('/events');
if (response.eventStream) {
  for await (const event of response.eventStream()) {
    console.log('Real-time event:', event);
  }
}

// 流式 LLM 响应，逐个令牌输出
const llmResponse = await fetcher.post('/chat/completions', {
  body: {
    model: 'gpt-3.5-turbo',
    messages: [{ role: 'user', content: 'Hello!' }],
    stream: true,
  },
});

if (llmResponse.jsonEventStream) {
  // 专门用于 LLM API 的 JSON SSE 事件
  for await (const event of llmResponse.jsonEventStream<ChatCompletionChunk>()) {
    const content = event.data.choices[0]?.delta?.content || '';
    process.stdout.write(content); // 实时令牌输出
  }
}

import {
  BroadcastTypedEventBus,
  SerialTypedEventBus,
} from '@ahoo-wang/fetcher-eventbus';

// 创建本地事件处理的委托
const delegate = new SerialTypedEventBus<string>('shared-events');

// 创建跨标签页通信的广播事件总线
const eventBus = new BroadcastTypedEventBus(delegate);

// 添加事件处理器
eventBus.on({
  name: 'user-action',
  order: 1,
  handle: action => console.log('用户操作:', action),
});

// 本地发射事件并广播到其他标签页
await eventBus.emit('button-clicked');

# 安装依赖
pnpm install

# 构建所有包
pnpm build

# 运行单元测试和覆盖率
pnpm test:unit

# 格式化代码
pnpm format

# 清理构建产物
pnpm clean

# 运行集成测试
#pnpm test:it

pnpm update-version <new-version>