xxf_react 0.6.7 → 0.6.9

package/dist/http/models/CacheInterceptor.d.ts

@@ -0,0 +1,112 @@
+/**
+ * 缓存拦截器相关类型
+ *
+ * 用于根据响应内容动态决定是否缓存
+ */
+import type { CacheKeyRequest } from './CacheConfig';
+/**
+ * 缓存拦截器上下文
+ *
+ * 包含响应的完整信息，供拦截器判断是否应该缓存
+ *
+ * @template T 响应数据类型
+ *
+ * @example
+ * ```ts
+ * cacheInterceptor: (ctx) => {
+ *   // 可以访问响应数据、HTTP 状态码、响应头等
+ *   console.log(ctx.data)      // 响应数据
+ *   console.log(ctx.status)    // HTTP 状态码
+ *   console.log(ctx.headers)   // 响应头
+ *   console.log(ctx.request)   // 请求信息
+ *   console.log(ctx.cacheKey)  // 缓存 key
+ * }
+ * ```
+ */
+export interface CacheInterceptorContext<T = unknown> {
+    /** 响应数据（已解析的 JSON） */
+    data: T;
+    /** HTTP 状态码 */
+    status: number;
+    /** 响应头 */
+    headers: Headers;
+    /** 请求信息（用于调试或高级判断） */
+    request: CacheKeyRequest;
+    /** 缓存 key（用于调试或高级判断） */
+    cacheKey: string;
+}
+/**
+ * 缓存拦截器返回结果
+ *
+ * 当需要更精细控制时使用对象形式返回
+ *
+ * @example
+ * ```ts
+ * // 简单返回 boolean
+ * cacheInterceptor: (ctx) => ctx.status === 200
+ *
+ * // 返回对象，可以覆盖 TTL
+ * cacheInterceptor: (ctx) => ({
+ *   shouldCache: true,
+ *   ttl: 10 * 60 * 1000,  // 覆盖为 10 分钟
+ * })
+ * ```
+ */
+export interface CacheInterceptorResult {
+    /** 是否允许缓存 */
+    shouldCache: boolean;
+    /**
+     * 可选：覆盖缓存 TTL (ms)
+     * 如果不指定，使用请求配置中的 ttl
+     */
+    ttl?: number;
+}
+/**
+ * 缓存拦截器
+ *
+ * 在响应返回后、写入缓存前调用，用于根据响应内容决定是否缓存。
+ *
+ * ## 常见场景
+ * - 只缓存 HTTP 200 响应
+ * - 只缓存业务 code 为成功的响应
+ * - 根据响应头决定是否缓存
+ * - 根据响应内容动态调整缓存时间
+ *
+ * ## 返回值
+ * - `true`：允许缓存
+ * - `false`：不缓存
+ * - `CacheInterceptorResult`：精细控制（是否缓存 + 可选覆盖 TTL）
+ * - `Promise<...>`：支持异步判断
+ *
+ * @template T 响应数据类型
+ * @param context 拦截器上下文，包含响应的完整信息
+ *
+ * @example
+ * ```ts
+ * // 示例 1：只缓存 HTTP 200
+ * cacheInterceptor: (ctx) => ctx.status === 200
+ *
+ * // 示例 2：检查业务 code
+ * cacheInterceptor: (ctx) => {
+ *   const res = ctx.data as { code?: number }
+ *   return res.code === 200
+ * }
+ *
+ * // 示例 3：检查响应头
+ * cacheInterceptor: (ctx) => {
+ *   return ctx.headers.get('X-Cacheable') !== 'false'
+ * }
+ *
+ * // 示例 4：动态 TTL
+ * cacheInterceptor: (ctx) => {
+ *   const res = ctx.data as { code?: number; cacheTtl?: number }
+ *   if (res.code !== 200) return false
+ *   return {
+ *     shouldCache: true,
+ *     ttl: res.cacheTtl ?? 5 * 60 * 1000,
+ *   }
+ * }
+ * ```
+ */
+export type CacheInterceptor<T = unknown> = (context: CacheInterceptorContext<T>) => boolean | CacheInterceptorResult | Promise<boolean | CacheInterceptorResult>;
+//# sourceMappingURL=CacheInterceptor.d.ts.map

package/dist/http/models/CacheInterceptor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CacheInterceptor.d.ts","sourceRoot":"","sources":["../../../src/http/models/CacheInterceptor.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAA;AAEpD;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,WAAW,uBAAuB,CAAC,CAAC,GAAG,OAAO;IAChD,sBAAsB;IACtB,IAAI,EAAE,CAAC,CAAA;IACP,eAAe;IACf,MAAM,EAAE,MAAM,CAAA;IACd,UAAU;IACV,OAAO,EAAE,OAAO,CAAA;IAChB,sBAAsB;IACtB,OAAO,EAAE,eAAe,CAAA;IACxB,wBAAwB;IACxB,QAAQ,EAAE,MAAM,CAAA;CACnB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,sBAAsB;IACnC,aAAa;IACb,WAAW,EAAE,OAAO,CAAA;IACpB;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAA;CACf;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,MAAM,MAAM,gBAAgB,CAAC,CAAC,GAAG,OAAO,IAAI,CACxC,OAAO,EAAE,uBAAuB,CAAC,CAAC,CAAC,KAClC,OAAO,GAAG,sBAAsB,GAAG,OAAO,CAAC,OAAO,GAAG,sBAAsB,CAAC,CAAA"}

package/dist/http/models/CacheInterceptor.js

@@ -0,0 +1,6 @@
+/**
+ * 缓存拦截器相关类型
+ *
+ * 用于根据响应内容动态决定是否缓存
+ */
+export {};

package/dist/http/models/CacheMode.d.ts

@@ -0,0 +1,45 @@
+/**
+ * 缓存模式枚举
+ *
+ * 定义了 6 种缓存策略，覆盖各种业务场景
+ */
+export declare enum CacheMode {
+    /**
+     * 先从本地缓存拿，然后从服务器拿
+     * - 可能 yield 两次（先缓存后网络）
+     * - 适用于：需要快速展示旧数据，同时更新最新数据
+     */
+    FirstCache = "firstCache",
+    /**
+     * 先从服务器获取，没网络则读缓存
+     * - yield 1 次
+     * - 适用于：优先保证数据最新，网络异常时降级
+     */
+    FirstRemote = "firstRemote",
+    /**
+     * 只从服务器拿（默认模式）
+     * - yield 1 次
+     * - 适用于：实时性要求高的数据
+     */
+    OnlyRemote = "onlyRemote",
+    /**
+     * 只从缓存拿
+     * - yield 0-1 次（无缓存时不 yield）
+     * - 适用于：离线场景、纯本地数据
+     */
+    OnlyCache = "onlyCache",
+    /**
+     * 有缓存返回缓存，否则请求网络
+     * - yield 1 次
+     * - 适用于：缓存优先，减少网络请求
+     */
+    IfCache = "ifCache",
+    /**
+     * 读上次缓存，后台静默更新
+     * - yield 1 次（返回缓存或网络）
+     * - 有缓存时后台同步网络但不 yield
+     * - 适用于：SWR（stale-while-revalidate）策略
+     */
+    LastCache = "lastCache"
+}
+//# sourceMappingURL=CacheMode.d.ts.map

package/dist/http/models/CacheMode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CacheMode.d.ts","sourceRoot":"","sources":["../../../src/http/models/CacheMode.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,oBAAY,SAAS;IACjB;;;;OAIG;IACH,UAAU,eAAe;IAEzB;;;;OAIG;IACH,WAAW,gBAAgB;IAE3B;;;;OAIG;IACH,UAAU,eAAe;IAEzB;;;;OAIG;IACH,SAAS,cAAc;IAEvB;;;;OAIG;IACH,OAAO,YAAY;IAEnB;;;;;OAKG;IACH,SAAS,cAAc;CAC1B"}

package/dist/http/models/CacheMode.js

@@ -0,0 +1,45 @@
+/**
+ * 缓存模式枚举
+ *
+ * 定义了 6 种缓存策略，覆盖各种业务场景
+ */
+export var CacheMode;
+(function (CacheMode) {
+    /**
+     * 先从本地缓存拿，然后从服务器拿
+     * - 可能 yield 两次（先缓存后网络）
+     * - 适用于：需要快速展示旧数据，同时更新最新数据
+     */
+    CacheMode["FirstCache"] = "firstCache";
+    /**
+     * 先从服务器获取，没网络则读缓存
+     * - yield 1 次
+     * - 适用于：优先保证数据最新，网络异常时降级
+     */
+    CacheMode["FirstRemote"] = "firstRemote";
+    /**
+     * 只从服务器拿（默认模式）
+     * - yield 1 次
+     * - 适用于：实时性要求高的数据
+     */
+    CacheMode["OnlyRemote"] = "onlyRemote";
+    /**
+     * 只从缓存拿
+     * - yield 0-1 次（无缓存时不 yield）
+     * - 适用于：离线场景、纯本地数据
+     */
+    CacheMode["OnlyCache"] = "onlyCache";
+    /**
+     * 有缓存返回缓存，否则请求网络
+     * - yield 1 次
+     * - 适用于：缓存优先，减少网络请求
+     */
+    CacheMode["IfCache"] = "ifCache";
+    /**
+     * 读上次缓存，后台静默更新
+     * - yield 1 次（返回缓存或网络）
+     * - 有缓存时后台同步网络但不 yield
+     * - 适用于：SWR（stale-while-revalidate）策略
+     */
+    CacheMode["LastCache"] = "lastCache";
+})(CacheMode || (CacheMode = {}));

package/dist/http/models/DiskCacheConfig.d.ts

@@ -0,0 +1,56 @@
+/**
+ * 缓存存储配置
+ */
+/**
+ * DiskLruCache 配置
+ *
+ * 用于配置基于 IndexedDB 的磁盘 LRU 缓存
+ *
+ * @example
+ * ```ts
+ * const diskCache = new DiskLruCache({
+ *   dbName: 'my-app-cache',
+ *   storeName: 'http-cache',
+ *   maxSize: 500,
+ *   cleanupThreshold: 0.1,
+ * })
+ * ```
+ */
+export interface DiskLruCacheConfig {
+    /** IndexedDB 数据库名 */
+    dbName: string;
+    /** 存储名（ObjectStore 名称） */
+    storeName: string;
+    /** 最大条目数 */
+    maxSize: number;
+    /**
+     * 清理阈值
+     *
+     * 超过 maxSize * (1 + cleanupThreshold) 后触发清理
+     * 默认 0.1，即超过 110% 时清理到 100%
+     */
+    cleanupThreshold?: number;
+}
+/**
+ * HttpCache 配置
+ *
+ * 用于配置 HTTP 缓存（内存 + 磁盘双层）
+ *
+ * @example
+ * ```ts
+ * const cache = new HttpCache({
+ *   memoryMaxSize: 100,
+ *   diskMaxSize: 500,
+ *   dbName: 'my-app-cache',
+ * })
+ * ```
+ */
+export interface HttpCacheConfig {
+    /** 内存缓存最大条目数 */
+    memoryMaxSize: number;
+    /** 磁盘缓存最大条目数 */
+    diskMaxSize: number;
+    /** IndexedDB 数据库名 */
+    dbName: string;
+}
+//# sourceMappingURL=DiskCacheConfig.d.ts.map

package/dist/http/models/DiskCacheConfig.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DiskCacheConfig.d.ts","sourceRoot":"","sources":["../../../src/http/models/DiskCacheConfig.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,kBAAkB;IAC/B,qBAAqB;IACrB,MAAM,EAAE,MAAM,CAAA;IACd,0BAA0B;IAC1B,SAAS,EAAE,MAAM,CAAA;IACjB,YAAY;IACZ,OAAO,EAAE,MAAM,CAAA;IACf;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAA;CAC5B;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,eAAe;IAC5B,gBAAgB;IAChB,aAAa,EAAE,MAAM,CAAA;IACrB,gBAAgB;IAChB,WAAW,EAAE,MAAM,CAAA;IACnB,qBAAqB;IACrB,MAAM,EAAE,MAAM,CAAA;CACjB"}

package/dist/http/models/DiskCacheConfig.js

@@ -0,0 +1,4 @@
+/**
+ * 缓存存储配置
+ */
+export {};

package/dist/http/models/HttpClientConfig.d.ts

@@ -0,0 +1,77 @@
+/**
+ * HTTP 客户端配置
+ */
+import type { CacheConfig } from './CacheConfig';
+import type { CacheInterceptor } from './CacheInterceptor';
+/**
+ * HTTP 客户端配置
+ *
+ * 用于创建 HttpClient 或 ApiBuilder 时的全局配置
+ *
+ * @example
+ * ```ts
+ * const api = ApiBuilder.create({
+ *   baseUrl: 'https://api.example.com',
+ *   timeout: 10000,
+ *   headers: { 'X-App-Version': '1.0.0' },
+ *   defaultCache: {
+ *     mode: CacheMode.FirstRemote,
+ *     ttl: 5 * 60 * 1000,
+ *   },
+ *   cacheInterceptor: (ctx) => ctx.status === 200,
+ * })
+ * ```
+ */
+export interface HttpClientConfig {
+    /** 基础 URL */
+    baseUrl: string;
+    /** 默认请求头 */
+    headers?: Record<string, string>;
+    /** 默认超时时间 (ms)，默认 30000 */
+    timeout?: number;
+    /** 默认重试次数，默认 2 */
+    retry?: number;
+    /** 内存缓存最大条目数，默认 100 */
+    memoryCacheMaxSize?: number;
+    /** 磁盘缓存最大条目数，默认 500 */
+    diskCacheMaxSize?: number;
+    /** IndexedDB 数据库名，默认 'xxf-http-cache' */
+    dbName?: string;
+    /** 默认参与缓存 key 的 header，默认 ['Authorization'] */
+    defaultKeyHeaders?: string[];
+    /**
+     * 全局默认缓存配置
+     *
+     * 如果不设置，默认为 OnlyRemote（不缓存）
+     * 单个接口的 cache 配置会覆盖此全局配置
+     *
+     * @example
+     * ```ts
+     * defaultCache: {
+     *   mode: CacheMode.FirstRemote,
+     *   ttl: 5 * 60 * 1000,
+     * }
+     * ```
+     */
+    defaultCache?: Partial<CacheConfig>;
+    /**
+     * 全局缓存拦截器
+     *
+     * 在响应返回后、写入缓存前调用，用于根据响应内容决定是否缓存。
+     * 只有当缓存模式需要写入缓存时才会调用此拦截器。
+     *
+     * @example
+     * ```ts
+     * // 只缓存 HTTP 200 且业务 code 为 200 的响应
+     * cacheInterceptor: (ctx) => {
+     *   if (ctx.status !== 200) return false
+     *   const res = ctx.data as { code?: number }
+     *   return res.code === 200
+     * }
+     * ```
+     *
+     * @see CacheInterceptor 查看更多示例
+     */
+    cacheInterceptor?: CacheInterceptor;
+}
+//# sourceMappingURL=HttpClientConfig.d.ts.map

package/dist/http/models/HttpClientConfig.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HttpClientConfig.d.ts","sourceRoot":"","sources":["../../../src/http/models/HttpClientConfig.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAChD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAA;AAE1D;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,WAAW,gBAAgB;IAC7B,aAAa;IACb,OAAO,EAAE,MAAM,CAAA;IAEf,YAAY;IACZ,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAEhC,2BAA2B;IAC3B,OAAO,CAAC,EAAE,MAAM,CAAA;IAEhB,kBAAkB;IAClB,KAAK,CAAC,EAAE,MAAM,CAAA;IAEd,uBAAuB;IACvB,kBAAkB,CAAC,EAAE,MAAM,CAAA;IAE3B,uBAAuB;IACvB,gBAAgB,CAAC,EAAE,MAAM,CAAA;IAEzB,yCAAyC;IACzC,MAAM,CAAC,EAAE,MAAM,CAAA;IAEf,+CAA+C;IAC/C,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAA;IAE5B;;;;;;;;;;;;;OAaG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,CAAA;IAEnC;;;;;;;;;;;;;;;;;OAiBG;IACH,gBAAgB,CAAC,EAAE,gBAAgB,CAAA;CACtC"}

package/dist/http/models/HttpClientConfig.js

@@ -0,0 +1,4 @@
+/**
+ * HTTP 客户端配置
+ */
+export {};

package/dist/http/models/LruMetadata.d.ts

@@ -0,0 +1,28 @@
+/**
+ * LRU 缓存元数据
+ *
+ * 用于 DiskLruCache 内部管理缓存条目的访问顺序
+ */
+/**
+ * LRU 元数据条目
+ *
+ * 单个缓存条目的元数据信息
+ */
+export interface LruMetadataEntry {
+    /** 最后访问时间 (ms) */
+    accessTime: number;
+    /** 数据大小估算 (可选，用于未来扩展) */
+    size?: number;
+}
+/**
+ * LRU 元数据
+ *
+ * 存储在 IndexedDB 中的元数据，用于 LRU 淘汰算法
+ */
+export interface LruMetadata {
+    /** 所有缓存 key 及其元数据 */
+    entries: Record<string, LruMetadataEntry>;
+    /** 总条目数 */
+    count: number;
+}
+//# sourceMappingURL=LruMetadata.d.ts.map

package/dist/http/models/LruMetadata.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LruMetadata.d.ts","sourceRoot":"","sources":["../../../src/http/models/LruMetadata.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC7B,kBAAkB;IAClB,UAAU,EAAE,MAAM,CAAA;IAClB,yBAAyB;IACzB,IAAI,CAAC,EAAE,MAAM,CAAA;CAChB;AAED;;;;GAIG;AACH,MAAM,WAAW,WAAW;IACxB,qBAAqB;IACrB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAA;IACzC,WAAW;IACX,KAAK,EAAE,MAAM,CAAA;CAChB"}

package/dist/http/models/LruMetadata.js

@@ -0,0 +1,6 @@
+/**
+ * LRU 缓存元数据
+ *
+ * 用于 DiskLruCache 内部管理缓存条目的访问顺序
+ */
+export {};

package/dist/http/models/RequestConfig.d.ts

@@ -0,0 +1,67 @@
+/**
+ * 请求配置相关类型
+ */
+import type { CacheConfig } from './CacheConfig';
+/**
+ * 请求配置
+ *
+ * 用于定义单个 API 端点的配置
+ *
+ * @example
+ * ```ts
+ * .get<User>('getUser', {
+ *   path: '/users/{id}',
+ *   headers: { 'Accept': 'application/json' },
+ *   timeout: 5000,
+ *   cache: { mode: CacheMode.IfCache, ttl: 60000 },
+ * })
+ * ```
+ */
+export interface RequestConfig {
+    /** 请求方法 */
+    method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+    /** 请求路径，支持路径参数如 /users/{id} */
+    path: string;
+    /** 请求头 */
+    headers?: Record<string, string>;
+    /** 超时时间 (ms) */
+    timeout?: number;
+    /** 缓存配置 */
+    cache?: CacheConfig;
+    /** 重试次数 */
+    retry?: number;
+}
+/**
+ * API 调用选项
+ *
+ * 用于调用 API 时传入的运行时参数
+ *
+ * @example
+ * ```ts
+ * // 完整示例
+ * await api.getUser({
+ *   pathParams: { id: '123' },
+ *   query: { include: 'profile' },
+ *   headers: { 'X-Request-Id': 'abc' },
+ *   cache: { mode: CacheMode.OnlyRemote },  // 本次调用强制不缓存
+ * })
+ *
+ * // POST 请求
+ * await api.createUser({
+ *   body: { name: 'John', email: 'john@example.com' },
+ * })
+ * ```
+ */
+export interface ApiOptions {
+    /** URL 路径参数，用于替换路径中的 {param} */
+    pathParams?: Record<string, string | number>;
+    /** 查询参数，会自动过滤 undefined 和 null */
+    query?: Record<string, string | number | boolean | undefined>;
+    /** 请求体（用于 POST/PUT/PATCH） */
+    body?: unknown;
+    /** 覆盖缓存配置（优先级最高） */
+    cache?: Partial<CacheConfig>;
+    /** 覆盖请求头 */
+    headers?: Record<string, string>;
+}
+//# sourceMappingURL=RequestConfig.d.ts.map

package/dist/http/models/RequestConfig.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RequestConfig.d.ts","sourceRoot":"","sources":["../../../src/http/models/RequestConfig.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAEhD;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,aAAa;IAC1B,WAAW;IACX,MAAM,EAAE,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,QAAQ,GAAG,OAAO,CAAA;IACnD,+BAA+B;IAC/B,IAAI,EAAE,MAAM,CAAA;IACZ,UAAU;IACV,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAChC,gBAAgB;IAChB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,WAAW;IACX,KAAK,CAAC,EAAE,WAAW,CAAA;IACnB,WAAW;IACX,KAAK,CAAC,EAAE,MAAM,CAAA;CACjB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,WAAW,UAAU;IACvB,gCAAgC;IAChC,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,CAAA;IAC5C,kCAAkC;IAClC,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC,CAAA;IAC7D,6BAA6B;IAC7B,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,oBAAoB;IACpB,KAAK,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,CAAA;IAC5B,YAAY;IACZ,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CACnC"}

package/dist/http/models/RequestConfig.js

@@ -0,0 +1,4 @@
+/**
+ * 请求配置相关类型
+ */
+export {};

package/dist/http/models/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * HTTP 网络框架类型定义
+ *
+ * 按功能模块拆分：
+ * - CacheMode: 缓存模式枚举
+ * - CacheEntry: 缓存条目结构
+ * - ApiTypes: API 响应相关类型
+ * - CacheConfig: 缓存配置
+ * - CacheInterceptor: 缓存拦截器
+ * - HttpClientConfig: HTTP 客户端配置
+ * - RequestConfig: 请求配置
+ * - DiskCacheConfig: 磁盘缓存配置
+ * - LruMetadata: LRU 元数据
+ */
+export { CacheMode } from './CacheMode';
+export type { CacheEntry } from './CacheEntry';
+export type { ApiResult, ApiCallback } from './ApiTypes';
+export type { CacheConfig, CacheKeyRequest } from './CacheConfig';
+export type { CacheInterceptor, CacheInterceptorContext, CacheInterceptorResult, } from './CacheInterceptor';
+export type { HttpClientConfig } from './HttpClientConfig';
+export type { RequestConfig, ApiOptions } from './RequestConfig';
+export type { DiskLruCacheConfig, HttpCacheConfig } from './DiskCacheConfig';
+export type { LruMetadataEntry, LruMetadata } from './LruMetadata';
+//# sourceMappingURL=index.d.ts.map

package/dist/http/models/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/http/models/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AAGvC,YAAY,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AAG9C,YAAY,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAGxD,YAAY,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,eAAe,CAAA;AAGjE,YAAY,EACR,gBAAgB,EAChB,uBAAuB,EACvB,sBAAsB,GACzB,MAAM,oBAAoB,CAAA;AAG3B,YAAY,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAA;AAG1D,YAAY,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAGhE,YAAY,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAA;AAG5E,YAAY,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA"}

package/dist/http/models/index.js

@@ -0,0 +1,16 @@
+/**
+ * HTTP 网络框架类型定义
+ *
+ * 按功能模块拆分：
+ * - CacheMode: 缓存模式枚举
+ * - CacheEntry: 缓存条目结构
+ * - ApiTypes: API 响应相关类型
+ * - CacheConfig: 缓存配置
+ * - CacheInterceptor: 缓存拦截器
+ * - HttpClientConfig: HTTP 客户端配置
+ * - RequestConfig: 请求配置
+ * - DiskCacheConfig: 磁盘缓存配置
+ * - LruMetadata: LRU 元数据
+ */
+// 缓存模式
+export { CacheMode } from './CacheMode';

package/dist/http/types.d.ts

@@ -0,0 +1,13 @@
+/**
+ * HTTP 网络框架类型定义
+ *
+ * 统一导出入口，保持向后兼容
+ * 实际类型定义在 models/ 目录下按功能拆分
+ *
+ * @example
+ * ```ts
+ * import { CacheMode, type HttpClientConfig } from 'xxf_react/http'
+ * ```
+ */
+export { CacheMode, type CacheEntry, type ApiResult, type ApiCallback, type CacheConfig, type CacheKeyRequest, type CacheInterceptor, type CacheInterceptorContext, type CacheInterceptorResult, type HttpClientConfig, type RequestConfig, type ApiOptions, type DiskLruCacheConfig, type HttpCacheConfig, type LruMetadataEntry, type LruMetadata, } from './models';
+//# sourceMappingURL=types.d.ts.map

package/dist/http/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/http/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAEH,SAAS,EAET,KAAK,UAAU,EAEf,KAAK,SAAS,EACd,KAAK,WAAW,EAEhB,KAAK,WAAW,EAChB,KAAK,eAAe,EAEpB,KAAK,gBAAgB,EACrB,KAAK,uBAAuB,EAC5B,KAAK,sBAAsB,EAE3B,KAAK,gBAAgB,EAErB,KAAK,aAAa,EAClB,KAAK,UAAU,EAEf,KAAK,kBAAkB,EACvB,KAAK,eAAe,EAEpB,KAAK,gBAAgB,EACrB,KAAK,WAAW,GACnB,MAAM,UAAU,CAAA"}

package/dist/http/types.js

@@ -0,0 +1,14 @@
+/**
+ * HTTP 网络框架类型定义
+ *
+ * 统一导出入口，保持向后兼容
+ * 实际类型定义在 models/ 目录下按功能拆分
+ *
+ * @example
+ * ```ts
+ * import { CacheMode, type HttpClientConfig } from 'xxf_react/http'
+ * ```
+ */
+export { 
+// 缓存模式枚举
+CacheMode, } from './models';

package/dist/index.d.ts

@@ -9,5 +9,6 @@ export * from './responsive';
 export * from './foundation';
 export * from './layout';
 export * from './event-bus';
+export * from './http';
 export declare function initXXF(): void;
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,cAAc,OAAO,CAAC;AACtB,cAAc,SAAS,CAAC;AACxB,cAAc,SAAS,CAAC;AACxB,cAAc,WAAW,CAAC;AAC1B,cAAc,UAAU,CAAC;AACzB,cAAc,SAAS,CAAC;AACxB,cAAc,QAAQ,CAAC;AACvB,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC;AAG5B,wBAAgB,OAAO,SAGtB"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,cAAc,OAAO,CAAC;AACtB,cAAc,SAAS,CAAC;AACxB,cAAc,SAAS,CAAC;AACxB,cAAc,WAAW,CAAC;AAC1B,cAAc,UAAU,CAAC;AACzB,cAAc,SAAS,CAAC;AACxB,cAAc,QAAQ,CAAC;AACvB,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC;AAC5B,cAAc,QAAQ,CAAC;AAGvB,wBAAgB,OAAO,SAGtB"}

package/dist/index.js

@@ -11,6 +11,7 @@ export * from './responsive';
 export * from './foundation';
 export * from './layout';
 export * from './event-bus';
+export * from './http';
 ///框架初始化函数，调用后会初始化一些全局功能
 export function initXXF() {
     initPromiseErrorExtension();

package/dist/layout/hover/XHover.d.ts

@@ -142,6 +142,6 @@ export interface XHoverProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onMou
  * </XHover>
  * ```
  */
-export declare function XHover({ children, hoverDelay, onEnter, onHover, onLeave, hoverLayer, disabled, as: Component, style, ...rest }: XHoverProps): React.JSX.Element;
+export declare const XHover: React.ForwardRefExoticComponent<XHoverProps & React.RefAttributes<HTMLElement>>;
 export default XHover;
 //# sourceMappingURL=XHover.d.ts.map

package/dist/layout/hover/XHover.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"XHover.d.ts","sourceRoot":"","sources":["../../../src/layout/hover/XHover.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAA2C,SAAS,EAAE,cAAc,EAAC,MAAM,OAAO,CAAA;AAEhG;;GAEG;AACH,MAAM,WAAW,WAAY,SAAQ,IAAI,CAAC,cAAc,CAAC,cAAc,CAAC,EAAE,cAAc,GAAG,cAAc,CAAC;IACtG;;OAEG;IACH,QAAQ,EAAE,SAAS,CAAA;IAEnB;;;;;;;;;;;;;;;;;OAiBG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;IAEnB;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,IAAI,CAAA;IAEpB;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,IAAI,CAAA;IAEpB;;;;OAIG;IACH,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,OAAO,KAAK,IAAI,CAAA;IAEtC;;;;;;;;;;;;;;;;;;;OAmBG;IACH,UAAU,CAAC,EAAE,MAAM,SAAS,CAAA;IAE5B;;;;OAIG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAA;IAElB;;;;OAIG;IACH,EAAE,CAAC,EAAE,KAAK,GAAG,MAAM,CAAA;CACtB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+DG;AACH,wBAAgB,MAAM,CAAC,EACnB,QAAQ,EACR,UAAc,EACd,OAAO,EACP,OAAO,EACP,OAAO,EACP,UAAU,EACV,QAAgB,EAChB,EAAE,EAAE,SAAiB,EACrB,KAAK,EACL,GAAG,IAAI,EACV,EAAE,WAAW,qBA0Eb;AAED,eAAe,MAAM,CAAA"}
+{"version":3,"file":"XHover.d.ts","sourceRoot":"","sources":["../../../src/layout/hover/XHover.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAAuD,SAAS,EAAE,cAAc,EAAC,MAAM,OAAO,CAAA;AAE5G;;GAEG;AACH,MAAM,WAAW,WAAY,SAAQ,IAAI,CAAC,cAAc,CAAC,cAAc,CAAC,EAAE,cAAc,GAAG,cAAc,CAAC;IACtG;;OAEG;IACH,QAAQ,EAAE,SAAS,CAAA;IAEnB;;;;;;;;;;;;;;;;;OAiBG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;IAEnB;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,IAAI,CAAA;IAEpB;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,IAAI,CAAA;IAEpB;;;;OAIG;IACH,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,OAAO,KAAK,IAAI,CAAA;IAEtC;;;;;;;;;;;;;;;;;;;OAmBG;IACH,UAAU,CAAC,EAAE,MAAM,SAAS,CAAA;IAE5B;;;;OAIG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAA;IAElB;;;;OAIG;IACH,EAAE,CAAC,EAAE,KAAK,GAAG,MAAM,CAAA;CACtB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+DG;AACH,eAAO,MAAM,MAAM,iFAyFjB,CAAA;AAEF,eAAe,MAAM,CAAA"}

package/dist/layout/hover/XHover.js

@@ -1,4 +1,4 @@
-import React, { useCallback, useRef, useEffect, useState } from 'react';
+import React, { forwardRef, useCallback, useRef, useEffect, useState } from 'react';
 /**
  * 悬浮触发组件
  *
@@ -63,7 +63,7 @@ import React, { useCallback, useRef, useEffect, useState } from 'react';
  * </XHover>
  * ```
  */
-export function XHover({ children, hoverDelay = 0, onEnter, onHover, onLeave, hoverLayer, disabled = false, as: Component = 'div', style, ...rest }) {
+export const XHover = forwardRef(function XHover({ children, hoverDelay = 0, onEnter, onHover, onLeave, hoverLayer, disabled = false, as: Component = 'div', style, ...rest }, ref) {
     const timerRef = useRef(null);
     const hasTriggeredRef = useRef(false);
     // 只有 hoverLayer 存在时才需要状态
@@ -121,8 +121,8 @@ export function XHover({ children, hoverDelay = 0, onEnter, onHover, onLeave, ho
     const containerStyle = hoverLayer
         ? { position: 'relative', ...style }
         : style;
-    return (React.createElement(Component, { ...rest, style: containerStyle, onMouseEnter: handleMouseEnter, onMouseLeave: handleMouseLeave },
+    return (React.createElement(Component, { ref: ref, ...rest, style: containerStyle, onMouseEnter: handleMouseEnter, onMouseLeave: handleMouseLeave },
         children,
         hoverLayer && showLayer && hoverLayer()));
-}
+});
 export default XHover;