API 概览

Fetcher 生态系统在多个包中暴露 API，每个包处理 HTTP 客户端生命周期中的特定关注点。本页提供所有公共 API 接口的摘要及快速导航链接。

包 API 摘要

包	npm 名称	主要导出	描述
Fetcher	@ahoo-wang/fetcher	Fetcher、NamedFetcher、FetcherRegistrar、InterceptorManager	带拦截器管道的核心 HTTP 客户端
Decorator	@ahoo-wang/fetcher-decorator	@api、@get、@post、@put、@del、@patch、@path、@query、@header、@body	通过装饰器实现声明式 API 客户端
React Hooks	@ahoo-wang/fetcher-react	useFetcher、useQuery、useExecutePromise、createQueryApiHooks	用于数据获取的 React Hooks
EventStream	@ahoo-wang/fetcher-eventstream	toJsonServerSentEventStream、EventStreamResultExtractor	SSE 和 LLM 流式支持
EventBus	@ahoo-wang/fetcher-eventbus	EventBus、TypedEventBus、ParallelTypedEventBus、SerialTypedEventBus	类型安全的事件总线
OpenAPI	@ahoo-wang/fetcher-openapi	OpenAPI 3.x 的 TypeScript 接口	规范类型定义
Storage	@ahoo-wang/fetcher-storage	存储抽象	浏览器存储封装
CoSec	@ahoo-wang/fetcher-cosec	安全拦截器	认证与授权
Wow	@ahoo-wang/fetcher-wow	CQRS 命令/查询客户端	DDD + 事件溯源支持
Viewer	@ahoo-wang/fetcher-viewer	React + Ant Design 组件	API 文档查看器
Generator	@ahoo-wang/fetcher-generator	fetcher-generator CLI	OpenAPI 到 TypeScript 代码生成

导入模式

核心 Fetcher

import { Fetcher, NamedFetcher, fetcherRegistrar } from '@ahoo-wang/fetcher';
import { HttpMethod, ResultExtractors } from '@ahoo-wang/fetcher';
import type { FetchRequest, FetchExchange, FetcherOptions } from '@ahoo-wang/fetcher';

Decorator

import 'reflect-metadata'; // Required before any decorator usage
import { api, get, post, put, del, patch } from '@ahoo-wang/fetcher-decorator';
import { path, query, header, body, request, attribute } from '@ahoo-wang/fetcher-decorator';
import { autoGeneratedError } from '@ahoo-wang/fetcher-decorator';

React Hooks

import { useFetcher, useFetcherQuery } from '@ahoo-wang/fetcher-react';
import { useQuery, useExecutePromise, usePromiseState } from '@ahoo-wang/fetcher-react';
import { createQueryApiHooks } from '@ahoo-wang/fetcher-react';

EventStream（副作用导入）

// Importing this module patches Response.prototype with eventStream() and jsonEventStream()
import '@ahoo-wang/fetcher-eventstream';

EventBus

import { EventBus, ParallelTypedEventBus, SerialTypedEventBus } from '@ahoo-wang/fetcher-eventbus';
import type { EventHandler } from '@ahoo-wang/fetcher-eventbus';

架构图

graph TB
    subgraph sg_1 ["Application Layer"]
        REACT["@ahoo-wang/fetcher-react"]
        VIEWER["@ahoo-wang/fetcher-viewer"]
        GENERATOR["@ahoo-wang/fetcher-generator"]
    end

    subgraph sg_2 ["Service Layer"]
        DECO["@ahoo-wang/fetcher-decorator"]
        WOW["@ahoo-wang/fetcher-wow"]
        OPENAI["@ahoo-wang/fetcher-openai"]
        COSEC["@ahoo-wang/fetcher-cosec"]
    end

    subgraph sg_3 ["Core Layer"]
        FETCHER["@ahoo-wang/fetcher"]
        ESTREAM["@ahoo-wang/fetcher-eventstream"]
        EBUS["@ahoo-wang/fetcher-eventbus"]
        STORAGE["@ahoo-wang/fetcher-storage"]
        OPENAPI["@ahoo-wang/fetcher-openapi"]
    end

    REACT --> FETCHER
    REACT --> ESTREAM
    REACT --> EBUS
    REACT --> STORAGE
    REACT --> WOW
    REACT --> COSEC
    VIEWER --> REACT
    VIEWER --> OPENAPI
    DECO --> FETCHER
    WOW --> FETCHER
    WOW --> ESTREAM
    WOW --> DECO
    OPENAI --> FETCHER
    OPENAI --> ESTREAM
    OPENAI --> DECO
    COSEC --> FETCHER
    COSEC --> EBUS
    COSEC --> STORAGE
    ESTREAM --> FETCHER
    EBUS --> FETCHER
    STORAGE --> EBUS

    style FETCHER fill:#2d333b,stroke:#6d5dfc,color:#e6edf3
    style DECO fill:#2d333b,stroke:#6d5dfc,color:#e6edf3
    style REACT fill:#2d333b,stroke:#6d5dfc,color:#e6edf3
    style ESTREAM fill:#2d333b,stroke:#6d5dfc,color:#e6edf3
    style EBUS fill:#2d333b,stroke:#6d5dfc,color:#e6edf3
    style STORAGE fill:#2d333b,stroke:#6d5dfc,color:#e6edf3
    style OPENAPI fill:#2d333b,stroke:#6d5dfc,color:#e6edf3
    style VIEWER fill:#2d333b,stroke:#6d5dfc,color:#e6edf3
    style GENERATOR fill:#2d333b,stroke:#6d5dfc,color:#e6edf3
    style WOW fill:#2d333b,stroke:#6d5dfc,color:#e6edf3
    style OPENAI fill:#2d333b,stroke:#6d5dfc,color:#e6edf3
    style COSEC fill:#2d333b,stroke:#6d5dfc,color:#e6edf3

请求生命周期

sequenceDiagram
autonumber

    participant App as Application
    participant Fetcher as Fetcher
    participant IM as InterceptorManager
    participant ReqInt as Request Interceptors
    participant ResInt as Response Interceptors
    participant ErrInt as Error Interceptors

    App->>Fetcher: fetch(url, request, options)
    Fetcher->>Fetcher: resolveExchange()
    Fetcher->>IM: exchange(fetchExchange)
    IM->>ReqInt: intercept(exchange)
    ReqInt-->>IM: modified exchange
    IM->>ResInt: intercept(exchange)
    ResInt-->>IM: validated exchange
    IM-->>Fetcher: processed exchange
    Fetcher->>Fetcher: extractResult()
    Fetcher-->>App: result
    Note over IM,ErrInt: On error: error interceptors run
    IM->>ErrInt: intercept(exchange)
    ErrInt-->>IM: handled or re-thrown

拦截器管道详解

graph LR
    subgraph sg_1 ["Request Phase"]
        R1["RequestBodyInterceptor<br>(order: MIN_SAFE + STEP)"]
        R2["UrlResolveInterceptor<br>(near MAX_SAFE)"]
        R3["FetchInterceptor<br>(MAX_SAFE - STEP)"]
    end

    subgraph sg_2 ["Response Phase"]
        S1["ValidateStatusInterceptor<br>(MAX_SAFE - STEP)"]
        S2["Custom Response<br>Interceptors"]
    end

    subgraph sg_3 ["Error Phase"]
        E1["Custom Error<br>Interceptors"]
    end

    R1 --> R2 --> R3
    R3 -->|"success"| S1
    S1 --> S2
    R3 -->|"error"| E1
    S1 -->|"validation error"| E1

    style R1 fill:#2d333b,stroke:#6d5dfc,color:#e6edf3
    style R2 fill:#2d333b,stroke:#6d5dfc,color:#e6edf3
    style R3 fill:#2d333b,stroke:#6d5dfc,color:#e6edf3
    style S1 fill:#2d333b,stroke:#6d5dfc,color:#e6edf3
    style S2 fill:#2d333b,stroke:#6d5dfc,color:#e6edf3
    style E1 fill:#2d333b,stroke:#6d5dfc,color:#e6edf3

相关页面

• Fetcher 客户端 API -- 核心 HTTP 客户端类和选项
• 装饰器 API -- 声明式 API 服务定义
• React Hooks API -- React 数据获取 Hooks
• 类型定义 -- TypeScript 接口和类型
• 测试概览 -- 测试策略和工具