🚀 Fetcher

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

Fetcher v2.3.0 发布日志

🎊 激动人心的时刻到了！Fetcher v2.3.0 正式发布！ 这个版本带来了革命性的代码生成器和一系列强大的新特性，让您的开发体验更加流畅高效！

✨ 重磅新功能

🚀 全新代码生成器（Generator）

• 🎯 OpenAPI 3.0+ 支持：完整支持 OpenAPI 3.0+ 规范（JSON/YAML）
• 📦 TypeScript 代码生成：生成类型安全的 TypeScript 接口、枚举和类
• 🏗️ 领域驱动设计：专为 Wow 框架打造，支持聚合、命令、查询和领域事件
• 🔧 CLI 工具：易用的命令行界面，用于代码生成
• 🎨 装饰器式 API：生成装饰器式的客户端类，实现清晰的 API 交互
• 📋 全面的模型：处理复杂的模式，包括联合、交集、枚举和引用
• 🚀 Fetcher 生态集成：无缝集成 Fetcher 生态系统包
• 📊 进度日志：生成过程中的友好日志记录和进度指示器
• 📁 自动索引生成：自动生成 index.ts 文件，实现清晰的模块组织
• 🌐 远程规范支持：直接从 HTTP/HTTPS URL 加载 OpenAPI 规范
• 🎭 事件流：生成常规和事件流命令客户端

📖 生成器使用示例

从本地 OpenAPI 规范生成代码

fetcher-generator generate -i ./api-spec.json -o ./src/generated

从远程规范生成代码

fetcher-generator generate -i https://api.example.com/openapi.json -o ./src/generated

生成的代码结构：

output/
├── {bounded-context}/
│   ├── index.ts                   # 自动生成的索引文件，导出所有聚合
│   ├── boundedContext.ts          # 有界上下文别名常量
│   ├── types.ts                   # 有界上下文的共享类型
│   └── {aggregate}/               # 聚合特定文件
│       ├── index.ts               # 聚合的自动生成索引文件
│       ├── types.ts               # 聚合特定类型、模型和枚举
│       ├── queryClient.ts         # 查询客户端工厂，用于状态和事件查询
│       └── commandClient.ts       # 命令客户端类（常规和流式）
├── index.ts                       # 根索引文件，导出所有有界上下文
└── tsconfig.json                  # 生成代码的 TypeScript 配置

🔥 OpenAPI 全面增强

• 全新 OpenAPI 包：独立的 OpenAPI 规范支持包
• 扩展支持：OpenAPI 规范接口现在支持扩展功能
• 类型优化：SchemaType 新增 'null' 类型支持，字段可选性优化

💪 装饰器（Decorator）全面升级

• 生命周期钩子：为 API 服务添加完整的生命周期钩子支持
• 参数装饰器增强：支持对象展开功能，简化参数处理
• 元数据管理：新增 API 元数据和请求执行器能力
• 类型安全：端点返回类型能力增强，提升开发体验

🎯 查询系统重大改进

• 泛型类型支持：Condition 接口和查询接口全面支持泛型类型参数
• 领域事件流增强：新增状态和操作符能力，支持更复杂的数据处理
• 类型安全查询：事件流查询的类型安全性大幅提升

🔧 核心功能优化

• TRACE 方法支持：HTTP TRACE 方法现在得到完整支持
• 命令系统增强：新增批处理结果接口和等待信号机制
• 类型定义完善：新增 MessageHeaderSqlType 枚举和 WowMetadata 接口

📚 文档与工具

🎨 代码质量提升

• 统一代码风格：ESLint 和 Prettier 自动化代码格式化
• 测试优化：使用 MSW 替换模拟 fetch，提升测试可靠性

⚡ 性能与稳定性

• 依赖更新：所有工作区依赖更新至最新版本
• Docker 支持：Wow 示例服务器更新至 v6.1.12
• MongoDB 支持：MongoDB 客户端更新至 v8.0.14

🎉 破坏性变更

• 移除过时功能：废弃的 @attributes 参数装饰器已被移除
• 类型重命名：PathParams 重命名为 UrlPathParams，提升语义清晰度
• 架构优化：查询客户端迁移至 fetcher-decorator，架构更加统一

🚀 开始使用

这次更新为 Fetcher 生态系统带来了前所未有的开发体验！无论是全新的代码生成器，还是全面增强的类型系统，都将显著提升您的开发效率。

立即升级到 v2.3.0，体验下一代 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-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); // 实时令牌输出
  }
}

# 安装依赖
pnpm install

# 构建所有包
pnpm build

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

# 格式化代码
pnpm format

# 清理构建产物
pnpm clean

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

pnpm update-version <new-version>