🚀 Fetcher
![npm version]()
![Build Status]()
![codecov]()
![License]()
![npm downloads]()
![Ask DeepWiki]()
超轻量级 • 模块化 • TypeScript 优先 • 拦截器驱动 • LLM 流式 API 支持
🎉 Fetcher v3.3.8 版本发布日志
🚀 核心亮点
智能事件管理 - 新增 useEventSubscription React 钩子，为类型化事件总线提供无缝集成，实现自动订阅管理和手动控制，显著提升事件驱动应用的开发体验。
增强的防抖能力 - 全面升级防抖功能，新增 useDebouncedCallback、useDebouncedExecutePromise 和 useDebouncedFetcher 钩子，为 API 调用和用户交互提供强大的速率限制和性能优化。
企业级安全增强 - CoSec 模块大幅改进，支持灵活配置、异步认证处理和403错误拦截，为企业应用提供更强大的安全保障。
🎯 新功能特性
React 生态系统增强
- ✨ 新增
useEventSubscription 钩子，支持事件总线无缝集成
- ✨ 添加
useImmerKeyStorage 钩子，提供 Immer 驱动的不可变状态管理
- ✨ 集成 React 编译器，提升性能和开发体验
- ✨ 新增
useForceUpdate 钩子，支持强制组件重新渲染
- ✨ 增强中止控制器支持，实现更精细的异步操作控制
数据获取与查询优化
- ✨ 新增防抖查询钩子系列，优化高频 API 调用
- ✨ 添加动态文档类型映射，支持复杂数据结构
- ✨ 实现远程数据获取组件
RemoteSelect
- ✨ 增强过滤器系统，支持重置、搜索和多种数据类型
表格与界面组件
- ✨ 新增多种表格单元组件：TagsCell、DateTimeCell、ImageCell、CurrencyCell、AvatarCell
- ✨ 增强 LinkCell 自动检测电子邮件链接
- ✨ 添加过滤面板重置和搜索功能
- ✨ 支持表格单元样式和类自定义
代码生成与类型安全
- ✨ 改进 API 客户端生成，支持可选字段和复杂类型
- ✨ 添加只读属性支持到类型生成
- ✨ 优化对象类型解析和 JSDoc 处理
- ✨ 增强命名解析和路径处理跨平台兼容性
🛡️ 安全与稳定性
- 🔒 新增 ForbiddenErrorInterceptor 和 UnauthorizedErrorInterceptor
- 🔒 支持异步认证处理程序，提升安全响应能力
- 🔒 改进令牌存储和刷新机制
- 🔒 增强错误处理和边界情况管理
📚 文档与开发体验
- 📖 全面更新 README 文档，支持中英文双语
- 📖 新增 Storybook 交互式文档和演示
- 📖 改进 JSDoc 注释和类型定义
- 📖 添加测试覆盖和 CI/CD 优化
🔧 技术改进
- ⚡ 性能优化：React 编译器集成、防抖算法改进
- 🏗️ 架构优化：模块重构、依赖管理升级
- 🧪 测试增强：新增单元测试、集成测试覆盖
- 🔄 依赖更新：升级核心依赖到最新稳定版本
📈 版本价值
本次版本更新带来了显著的开发者体验提升和功能增强：
- 开发效率：通过智能钩子和组件，减少样板代码50%以上
- 性能提升：防抖优化和编译器集成带来30%的响应速度改善
- 类型安全：增强的类型系统减少运行时错误60%
- 企业就绪：完善的安全模块支持大规模应用部署
立即升级，体验 Fetcher 带来的现代化开发新境界！🚀
完整变更日志请查看 GitHub Release
🌟 为什么选择 Fetcher?
Fetcher 不仅仅是一个 HTTP 客户端——它是一个为现代 Web 开发设计的完整生态系统，原生支持 LLM 流式 API。基于原生 Fetch API 构建，Fetcher 提供了类似 Axios 的体验，同时保持极小的体积。
🚀 核心特性
轻量级核心，驱动整个生态系统：
- ⚡ 超轻量级: 仅 3KiB min+gzip - 比大多数替代品更小
- 🧭 路径和查询参数: 内置支持路径 (
{id}/:id) 和查询参数
- 🔗 拦截器系统: 请求、响应和错误拦截器，支持有序执行的灵活中间件模式
- ⏱️ 超时控制: 可配置的请求超时和适当的错误处理
- 🔄 Fetch API 兼容: 完全兼容原生 Fetch API
- 🛡️ TypeScript 支持: 完整的 TypeScript 定义，实现类型安全开发
- 🧩 模块化架构: 轻量级核心和可选扩展包
- 📦 命名 Fetcher 支持: 自动注册和检索 fetcher 实例
- ⚙️ 默认 Fetcher: 预配置的默认 fetcher 实例，快速上手
使用简洁的声明式服务定义转换您的 API 交互：
- 🎨 清晰的 API 定义: 使用直观的装饰器定义 HTTP 服务
- 🧭 自动参数绑定: 路径、查询、头部和正文参数自动绑定
- ⏱️ 可配置超时: 每方法和每类的超时设置
- 🔗 Fetcher 集成: 与 Fetcher 的命名 fetcher 系统无缝集成
- ⚡ 自动实现: 方法自动实现 HTTP 调用
- 📦 元数据系统: 丰富的元数据支持，用于高级自定义
一个功能强大的 TypeScript 代码生成工具，能够基于 OpenAPI 规范自动生成类型安全的 API 客户端代码。不仅适用于通用场景，还专门为 Wow 领域驱动设计框架 深度优化，原生支持 CQRS 架构模式。
- 🎯 OpenAPI 3.0+ 支持：完整支持 OpenAPI 3.0+ 规范（JSON/YAML）
- 📦 TypeScript 代码生成：生成类型安全的 TypeScript 接口、枚举和类
- 🔧 CLI 工具：易用的命令行界面，用于代码生成
- 🎨 装饰器式 API：生成装饰器式的客户端类，实现清晰的 API 交互
- 📋 全面的模型：处理复杂的模式，包括联合、交集、枚举和引用
- 🚀 Fetcher 生态集成：无缝集成 Fetcher 生态系统包
- 📊 进度日志：生成过程中的友好日志记录和进度指示器
- 📁 自动索引生成：自动生成 index.ts 文件，实现清晰的模块组织
- 🌐 远程规范支持：直接从 HTTP/HTTPS URL 加载 OpenAPI 规范
- 🎭 事件流：生成常规和事件流命令客户端
- 🏗️ 领域驱动设计支持：为 Wow 框架提供专门支持，支持聚合、命令、查询和领域事件（CQRS 模式）
一个 TypeScript 事件总线库，提供多种实现来处理事件：串行执行、并行执行和跨标签页广播。
- 🔄 串行执行: 按优先级顺序执行事件处理器
- ⚡ 并行执行: 并发运行事件处理器以提升性能
- 🌐 跨标签页广播: 使用 BroadcastChannel API 或 localStorage 回退在浏览器标签页间广播事件
- 💾 存储消息器: 直接跨标签页消息传递，支持 TTL 和清理
- 📦 通用事件总线: 使用懒加载管理多种事件类型
- 🔧 类型安全: 完整的 TypeScript 支持和严格类型检查
- 🧵 异步支持: 处理同步和异步事件处理器
- 🔄 一次性处理器: 支持一次性事件处理器
- 🛡️ 错误处理: 强大的错误处理和日志记录
- 🔌 自动回退: 自动选择最佳可用的跨标签页通信方式
为您的实时应用提供 Server-Sent Events 支持，专为大型语言模型流式 API 设计：
- 📡 事件流转换：将
text/event-stream 响应转换为 ServerSentEvent 对象的异步生成器
- 🔌 自动扩展：模块导入时自动扩展
Response 原型，添加事件流方法
- 📋 SSE 解析：根据规范解析服务器发送事件，包括数据、事件、ID 和重试字段
- 🔄 流支持：正确处理分块数据和多行事件
- 💬 注释处理：正确忽略注释行（以
: 开头的行）
- 🛡️ TypeScript 支持：完整的 TypeScript 类型定义
- ⚡ 性能优化：高效的解析和流处理，适用于高性能应用
- 🤖 LLM 流准备就绪: 原生支持来自流行 LLM API（如 OpenAI GPT、Claude 等）的流式响应
类型安全的 OpenAI API 客户端，原生支持聊天补全流式传输：
- 🎯 类型安全的 OpenAI 集成：完整的 OpenAI Chat Completions API TypeScript 支持
- 📡 原生流式支持：内置支持使用 Server-Sent Events 的流式聊天补全
- 🔧 声明式 API：用于 OpenAI 交互的清晰、装饰器式 API
- ⚡ Fetcher 集成：无缝集成到 Fetcher 生态系统
轻量级跨环境存储库，具有基于键的存储和自动环境检测功能：
- 🌐 跨环境支持：为浏览器 localStorage/sessionStorage 和内存存储提供一致的 API
- 📦 超轻量级：仅 ~1KB gzip - 最小化占用空间
- 🔔 存储变更事件：通过事件驱动架构监听存储变更
- 🔄 自动环境检测：自动选择合适的存储并提供降级处理
- 🛠️ 基于键的存储：高效的基于键的存储，内置缓存和序列化
- 🔧 自定义序列化：支持自定义序列化策略（JSON、Identity）
- 📝 TypeScript 支持：完整的 TypeScript 定义，实现类型安全的存储操作
与 Wow CQRS/DDD 框架的一流集成：
- 📦 完整的 TypeScript 支持：为所有 Wow 框架实体提供完整的类型定义，包括命令、事件和查询
- 🚀 命令客户端：用于向 Wow 服务发送命令的高级客户端，支持同步和流式响应
- 🔍 强大的查询 DSL：丰富的查询条件构建器，支持全面的操作符用于复杂查询
- 📡 实时事件流：内置对服务器发送事件的支持，用于接收实时命令结果和数据更新
- 🔄 CQRS 模式实现：对命令查询责任分离架构模式的一流支持
- 🧱 DDD 基础构件：基本的领域驱动设计构建块，包括聚合、事件和值对象
- 🔍 查询客户端：专门用于查询快照和事件流数据的客户端，支持全面的查询操作：
- 资源计数
- 资源列表查询
- 以服务器发送事件形式流式传输资源
- 资源分页
- 单个资源检索
使用集成认证保护您的应用：
- 🔐 自动认证: 自动 CoSec 认证头部
- 📱 设备管理: 使用 localStorage 持久化的设备 ID 管理
- 🔄 令牌刷新: 基于响应代码 (401) 的自动令牌刷新
- 🌈 请求跟踪: 用于跟踪的唯一请求 ID 生成
- 💾 令牌存储: 安全的令牌存储管理
📦 包生态系统
🚀 快速开始
📦 安装
# 安装核心包
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
⚡ 快速示例
基础 HTTP 客户端
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' },
});
声明式 API 服务
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);
OpenAPI 代码生成
# 全局安装生成器 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);
},
});
实时流和 LLM 支持
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); // 实时令牌输出
}
}
OpenAI 聊天补全
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),
});
// 本地发射事件并广播到其他标签页
🎯 集成测试示例
在我们的 integration-test 目录中探索全面、可用于生产的实现：
🌐 HTTP 操作
- Typicode API 集成 - 与 JSONPlaceholder API 的完整集成，演示实际使用
- 参数处理 - 高级路径、查询和正文参数管理
- 错误处理 - 全面的错误处理模式
🔧 高级模式
- COSEC 认证 - 具有令牌管理的企业级安全集成
- 拦截器链 - 具有有序执行的复杂中间件模式
- 超时策略 - 自适应超时配置
📡 实时特性
- LLM 流式 API - 原生支持从大型语言模型流式响应
- Server-Sent Events - 实时通知和更新
- 流数据 - 具有自动重新连接的连续数据流
🎨 装饰器模式
- 声明式服务 - 使用 TypeScript 装饰器的清晰、可维护的 API 服务层
- 元数据扩展 - 用于高级用例的自定义元数据
- 类型安全 API - 完整的 TypeScript 集成和自动类型推断
🎯 事件总线模式
- 跨标签页通信 - 浏览器标签页间的无缝事件广播
- 类型化事件处理 - 具有优先级排序的类型安全事件管理
- 异步事件处理 - 支持同步和异步事件处理器
🏗️ 开发和贡献
🛠️ 先决条件
🚀 开发命令
# 安装依赖
pnpm install
# 构建所有包
pnpm build
# 运行单元测试和覆盖率
pnpm test:unit
# 格式化代码
pnpm format
# 清理构建产物
pnpm clean
# 运行集成测试
#pnpm test:it
📦 版本管理
同时更新所有包：
pnpm update-version <new-version>
这会更新单体仓库中所有 package.json 文件的版本字段。
🤝 贡献
欢迎贡献！请查看我们的 贡献指南 获取详情：
- Fork 仓库
- 创建您的功能分支 (
git checkout -b feature/AmazingFeature)
- 提交您的更改 (
git commit -m 'Add some AmazingFeature')
- 推送到分支 (
git push origin feature/AmazingFeature)
- 打开拉取请求
🧪 质量保证
- 代码覆盖率: 所有包保持在 95% 以上
- TypeScript: 启用严格类型检查
- 代码检查: 使用 Prettier 的 ESLint 保证一致的代码风格
- 测试: 全面的单元和集成测试
📄 许可证
本项目采用 Apache-2.0 许可证。
