🚀 Fetcher

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

🎯 Fetcher v2.11.2 发布：显著提升前后端开发协作效率 ✨

本次更新通过多项优化，大幅提升了前后端开发协作效率，让 TypeScript API 客户端代码生成更加智能、高效，为团队协作带来质的飞跃。

💡 协作效率的价值

传统前后端协作的痛点：

• API 变更需要手动同步前后端代码，容易产生不一致
• 类型定义重复编写，浪费开发时间且容易出错
• 接口文档与实现脱节，导致理解偏差
• 新成员熟悉项目周期长，影响团队整体效率

Fetcher Generator 的解决方案：

• 自动化同步：基于 OpenAPI 规范，前后端定义实时同步
• 单一数据源：API 规范作为唯一权威，消除理解偏差
• 快速上手：生成的代码自解释性强，新成员快速融入项目
• 减少联调时间：类型安全保证，大幅减少接口调试时间

🚀 协作效率突破

前后端协作增强

• 智能 JSDoc 集成：生成的客户端代码完整包含 operationId 和 API 路径信息，前后端开发者在调用 API 时无需频繁查阅文档，显著减少沟通成本
• 语义化方法命名：改进的命名算法生成直观的方法名，让前端开发者能够快速理解 API 功能，加速开发进程
• 结构化代码组织：优化的 API 分组逻辑生成清晰的代码结构，便于团队协作维护和代码审查

开发流程优化

• 简化的生成工具：精简 CLI 命令，新成员快速上手，降低团队学习成本
• 灵活的类型支持：扩展的响应类型处理，适应多样化后端 API 设计，减少前后端类型定义摩擦
• 智能参数处理：新增 URL 参数配置能力，简化复杂 API 调用场景

代码质量保障

• 标准化输出：统一的代码风格和最佳实践，确保团队代码一致性
• 类型安全保障：编译时错误检测，减少前后端联调时的类型不匹配问题
• 清洁的代码结构：优化的导入导出语句，提升代码可维护性

🛠 快速集成

# 安装生成工具
npm install -g @ahoo-wang/fetcher-generator

# 从后端 API 文档生成前端客户端代码
fetcher-generator generate -i ./openapi-spec.json -o ./src/api

# 支持远程规范，便于持续集成
fetcher-generator generate -i https://api.yourcompany.com/openapi.json -o ./src/api

📈 工程化改进

• 生成性能优化：内部重构提升代码生成速度，加快 CI/CD 流程
• 日志输出优化：更清晰的进度提示，便于调试生成过程
• 依赖版本管理：确保生成工具的稳定性和兼容性

🎯 团队协作场景

• 新项目启动：快速搭建前后端协作基础，统一技术规范
• API 迭代升级：无缝处理接口变更，保持前后端同步
• 多团队协作：为不同前端团队生成统一标准的客户端 SDK
• 微服务架构：为多个后端服务生成一致的客户端调用方式

立即升级到 v2.11.2，体验前后端协作效率的显著提升！告别手动同步的繁琐流程，拥抱自动化、标准化的高效开发模式。

🌟 为什么选择 Fetcher?

# 安装核心包
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);

# 全局安装生成器 CLI
npm install -g @ahoo-wang/fetcher-generator

# 从 OpenAPI 规范生成 TypeScript 代码
fetcher-generator generate -i ./openapi-spec.json -o ./src/generated

# 或者从远程 URL 生成
fetcher-generator generate -i https://api.example.com/openapi.json -o ./src/generated

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 { OpenAI } from '@ahoo-wang/fetcher-openai';

// 初始化 OpenAI 客户端
const openai = new OpenAI({
  baseURL: 'https://api.openai.com/v1',
  apiKey: process.env.OPENAI_API_KEY!,
});

// 非流式聊天补全
const response = await openai.chat.completions({
  model: 'gpt-3.5-turbo',
  messages: [{ role: 'user', content: '你好，你怎么样？' }],
  stream: false,
});

console.log(response.choices[0].message.content);

// 流式聊天补全
const stream = await openai.chat.completions({
  model: 'gpt-3.5-turbo',
  messages: [{ role: 'user', content: '给我讲个故事' }],
  stream: true,
});

for await (const chunk of stream) {
  const content = chunk.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),
});

// 本地发射事件并广播到其他标签页

# 安装依赖
pnpm install

# 构建所有包
pnpm build

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

# 格式化代码
pnpm format

# 清理构建产物
pnpm clean

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

pnpm update-version <new-version>