@aithe/aithe-ui 26.2.3 → 26.3.2

package/dist/core/datahub/core/datahub-core.js

@@ -0,0 +1,520 @@
+/**
+ * @file DataHubCore - 核心调度器 / Core Dispatcher
+ * @description DataHub 的核心引擎，负责请求的完整生命周期管理：
+ *              1. 合并配置 → 2. 解析策略 → 3. 生成 traceId → 4. 请求拦截
+ *              → 5. 缓存检查 → 6. 去重/幂等 → 7. 适配器调用 → 8. 响应拦截
+ *              → 9. 缓存写入 → 10. 错误处理 → 11. loading 状态管理
+ *
+ *              设计原则：
+ *              - DataHub 只处理 HTTP 传输层，不关心业务协议
+ *              - 业务协议（code/message/data 等）由使用者在外部自行解析
+ *              - DataHubAdapterResponse.data 为原始 JSON，不做任何业务语义假设
+ *              - 适配器完全可插拔，核心不依赖任何具体适配器实现
+ *              - 策略自动识别，业务层无需关心缓存/去重/防重细节
+ *              - 统一错误处理，仅处理传输层异常
+ *
+ *              The core engine of DataHub, managing the complete request lifecycle.
+ *
+ *              Design principles:
+ *              - DataHub handles only the HTTP transport layer, not business protocols
+ *              - Business protocols (code/message/data, etc.) are interpreted by the consumer externally
+ *              - DataHubAdapterResponse.data is raw JSON with no assumed business semantics
+ *              - Adapters are fully pluggable; the core depends on no specific adapter implementation
+ *              - Strategy is auto-detected; the business layer need not worry about cache/dedup/idempotent details
+ *              - Unified error handling, only for transport-layer exceptions
+ */
+import { DataHubError as DataHubErrorClass } from '../../datahub/types';
+import { getBuiltinStyle, getBuiltinStyleNames } from './api-styles';
+import { FetchAdapter } from './adapter/fetch-adapter';
+import { MockAdapter } from './adapter/mock-adapter';
+import { resolveStrategy } from '../../datahub/config/strategy';
+import { cacheGet, cacheSet, cacheClear } from '../../datahub/utils/cache';
+import { dedupTrack, dedupClear } from '../../datahub/utils/dedup';
+import { loadingStart, loadingEnd, onLoadingChange, isLoading } from '../../datahub/utils/loading';
+import { idempotentGuard, idempotentClear } from '../../datahub/utils/idempotent';
+/** 默认配置项 / Default configuration values */
+const DEFAULT_CONFIG = {
+    /** 默认超时 30 秒 / Default timeout 30s */
+    defaultTimeout: 30000,
+    /** 默认缓存有效期 60 秒 / Default cache TTL 60s */
+    defaultCacheTTL: 60_000,
+    /** 默认使用 fetch 适配器 / Default to fetch adapter */
+    defaultAdapter: 'fetch',
+};
+/**
+ * DataHubCore - 核心调度器 / Core Dispatcher
+ * @description 管理适配器注册、API 注册、请求调度及中间件编排。
+ *              返回 DataHubAdapterResponse<T>，其中 data 为原始 JSON 解析结果，
+ *              不包含任何业务协议假设。使用者自行解析业务结构。
+ *              Manages adapter registration, API registration, request dispatch, and middleware orchestration.
+ *              Returns DataHubAdapterResponse<T>, where data is raw JSON-parsed result
+ *              without any business protocol assumptions. Consumers parse business structures themselves.
+ */
+export class DataHubCore {
+    /**
+     * @param config - 全局配置 / Global configuration
+     */
+    constructor(config = {}) {
+        /** 已注册的适配器映射，键为适配器名称 / Registered adapter map, keyed by adapter name */
+        this.adapters = new Map();
+        // ─── Loading 状态代理 / Loading State Proxy ───────────────────
+        /** 订阅 loading 状态变更 / Subscribe to loading state changes */
+        this.onLoadingChange = onLoadingChange;
+        /** 查询指定 URL 是否正在加载 / Check if the specified URL is currently loading */
+        this.isLoading = isLoading;
+        this.config = config;
+        // APIStyle 默认为空，不处理业务协议
+        // APIStyle defaults to undefined — no business protocol handling
+        // 内置注册两个零依赖适配器 / Register two zero-dependency built-in adapters
+        this.registerAdapter(new FetchAdapter());
+        this.registerAdapter(new MockAdapter());
+    }
+    // ─── 适配器管理 / Adapter Management ──────────────────────────
+    /**
+     * 注册适配器 / Register an adapter
+     * @param adapter - 适配器实例，需实现 DataHubAdapter 接口 / Adapter instance implementing DataHubAdapter
+     * @throws 如果同名适配器已存在，静默覆盖 / Silently overwrites if an adapter with the same name already exists
+     */
+    registerAdapter(adapter) {
+        this.adapters.set(adapter.name, adapter);
+    }
+    /**
+     * 获取已注册的适配器 / Get a registered adapter by name
+     * @param name - 适配器名称 / Adapter name
+     * @returns 适配器实例，未找到返回 undefined / Adapter instance, or undefined if not found
+     */
+    getAdapter(name) {
+        return this.adapters.get(name);
+    }
+    // ─── APIStyle 管理 / APIStyle Management ──────────────────────
+    /**
+     * 设置 APIStyle / Set APIStyle
+     * @param style - APIStyle 实例或内置风格名称（"default" | "k8s"）/ APIStyle instance or built-in style name
+     *
+     * @example
+     * // 使用内置风格 / Use built-in style
+     * dataHub.setAPIStyle('k8s');
+     *
+     * @example
+     * // 使用自定义风格 / Use custom style
+     * dataHub.setAPIStyle({
+     *   name: 'custom',
+     *   onRequest(req) { ... },
+     *   onResponse(res) { ... },
+     * });
+     */
+    setAPIStyle(style) {
+        if (typeof style === 'string') {
+            const builtin = getBuiltinStyle(style);
+            if (!builtin) {
+                throw new DataHubErrorClass({
+                    code: 'APIStyleNotFound',
+                    message: `Built-in APIStyle "${style}" is not found. Available: ${getBuiltinStyleNames().join(', ')}`,
+                });
+            }
+            this.apiStyle = builtin;
+        }
+        else {
+            this.apiStyle = style;
+        }
+    }
+    /**
+     * 获取当前 APIStyle / Get current APIStyle
+     * @returns 当前 APIStyle 实例 / Current APIStyle instance
+     */
+    getAPIStyle() {
+        return this.apiStyle;
+    }
+    /**
+     * 解析单次请求使用的 APIStyle：优先使用 options.apiStyle，否则回退到全局 this.apiStyle。
+     * 当 options.apiStyleRaw 为 true 时，返回 undefined 跳过 APIStyle 处理。
+     * Resolve the APIStyle for a single request: prefers options.apiStyle, falls back to this.apiStyle.
+     * Returns undefined when options.apiStyleRaw is true, skipping APIStyle processing.
+     */
+    resolveRequestStyle(options) {
+        if (options.apiStyle) {
+            if (typeof options.apiStyle === 'string') {
+                return getBuiltinStyle(options.apiStyle);
+            }
+            return options.apiStyle;
+        }
+        return this.apiStyle;
+    }
+    // ─── 核心请求方法 / Core Request Method ───────────────────────
+    /**
+     * 统一请求入口 / Unified request entry point
+     * @param url - 请求地址（相对路径会自动拼接 baseURL）/ Request URL (relative paths are auto-prepended with baseURL)
+     * @param data - 请求体数据 / Request body data
+     * @param options - 请求配置项 / Request options
+     * @returns DataHubAdapterResponse<T>，包含原始 JSON 响应体，业务协议由使用者自行解析
+     *          DataHubAdapterResponse<T> with raw JSON body — business protocol is interpreted by the consumer
+     *
+     * @example
+     * // 使用者自行定义业务协议 / Consumer defines their own business protocol
+     * interface BizResponse { code: string; message: string; data: unknown }
+     *
+     * const res = await dataHub.request('/order/query', { id: '1' });
+     * // res.ok — HTTP 是否成功 / whether HTTP succeeded
+     * // res.status — HTTP 状态码 / HTTP status code
+     * // res.data — 原始 JSON，由使用者按 BizResponse 自行解析 / raw JSON, interpreted by consumer as BizResponse
+     * const biz = res.data as BizResponse;
+     * if (biz.code === 'Ok') { /* handle success *\/ }
+     */
+    async request(url, data, options) {
+        // 1. 合并默认配置与用户配置 / Merge default config with user config
+        const merged = this.mergeOptions(options);
+        // 2. 拼接完整 URL / Resolve full URL
+        const fullUrl = this.resolveUrl(url);
+        // 3. 根据 URL 自动识别策略 / Auto-detect strategy based on URL
+        const strategy = resolveStrategy(fullUrl);
+        // 4. 生成或使用 traceId / Generate or use existing traceId
+        const traceId = merged.traceId ?? this.generateTraceId();
+        // 将 traceId 写入配置，供适配器使用 / Write traceId into options for adapter usage
+        merged.traceId = traceId;
+        // 合并全局 headers 并透传 traceId 和 locale
+        // Merge global headers and propagate traceId and locale
+        const traceHeaderKey = this.config.traceHeaderKey ?? 'X-B3-TraceId';
+        const localeHeaderKey = this.config.localeHeaderKey ?? 'X-Locale';
+        merged.headers = {
+            ...this.config.headers,
+            ...merged.headers,
+            [traceHeaderKey]: traceId,
+        };
+        if (this.config.getLocale) {
+            merged.headers[localeHeaderKey] = this.config.getLocale();
+        }
+        // 使用 APIStyle 封装请求体数据 / Wrap request data using APIStyle
+        const req = { url: fullUrl, data, options: merged };
+        const requestStyle = this.resolveRequestStyle(merged);
+        requestStyle?.onRequest(req);
+        // 5. 请求拦截器 / Request interceptor
+        if (this.config.onRequest) {
+            const intercepted = this.config.onRequest(req);
+            if (intercepted)
+                Object.assign(req, intercepted);
+        }
+        // 6. 缓存检查：查询类请求且未跳过缓存时，尝试命中缓存
+        // Cache check: for query requests without skipCache, try to hit cache
+        // forceCache 选项可无视 URL 命名约定强制启用缓存
+        // forceCache option bypasses URL naming convention to force-enable caching
+        const cacheable = this.isCacheable(strategy, merged);
+        if (cacheable && !merged.skipCache) {
+            const cached = cacheGet(fullUrl, data);
+            if (cached) {
+                // 缓存命中：先走全局响应拦截器，再走统一响应处理（与实际请求路径保持一致）
+                // Cache hit: apply global response interceptor first, then unified response handling
+                // (consistent with the real-request path)
+                this.applyResponseInterceptor(cached, req);
+                return this.handleResponse(cached, requestStyle, traceId, fullUrl);
+            }
+        }
+        // 实际执行请求的内部函数 / Internal function that actually executes the request
+        const execute = () => this.executeRequest(req, merged, requestStyle, traceId, fullUrl, data, cacheable);
+        // 12. 去重处理：查询类请求自动合并相同并发请求
+        // Dedup: automatically merge identical concurrent query requests
+        // forceDedup 选项可无视 URL 命名约定强制启用去重
+        // forceDedup option bypasses URL naming convention to force-enable dedup
+        const dedupable = this.isDedupable(strategy, merged);
+        if (dedupable && !merged.skipDedup) {
+            return dedupTrack(fullUrl, data, execute);
+        }
+        // 13. 幂等防护：提交类请求阻止重复提交
+        // Idempotent guard: block duplicate submissions for submit requests
+        // 当 forceDedup 或 forceCache 为 true 时跳过幂等防护，避免并发查询请求被误判为重复提交
+        // Skip idempotent guard when forceDedup or forceCache is true, preventing concurrent
+        // query requests from being misjudged as duplicate submissions
+        if (this.shouldGuardIdempotent(strategy, merged)) {
+            return idempotentGuard(fullUrl, data, execute);
+        }
+        // 14. 无需中间件，直接执行 / No middleware needed, execute directly
+        return execute();
+    }
+    /**
+     * 应用全局响应拦截器（命中缓存与实际请求路径共用）。
+     * Apply global response interceptor (shared by cache-hit and real-request paths).
+     */
+    applyResponseInterceptor(res, req) {
+        if (!this.config.onResponse)
+            return;
+        const intercepted = this.config.onResponse(res, req);
+        if (intercepted)
+            Object.assign(res, intercepted);
+    }
+    /**
+     * 实际执行请求：适配器调用 + 响应拦截 + HTTP 错误处理 + 统一响应处理 + 缓存写入。
+     * Execute the request: adapter call + response interceptor + HTTP error handling +
+     * unified response handling + cache write.
+     */
+    async executeRequest(req, merged, requestStyle, traceId, fullUrl, data, cacheable) {
+        // 标记 loading 开始 / Mark loading start
+        loadingStart(fullUrl);
+        try {
+            // 7. 解析并调用适配器 / Resolve and call adapter
+            const adapter = this.resolveAdapter(merged);
+            const res = await adapter.request(req);
+            // 8. 响应拦截器 / Response interceptor
+            this.applyResponseInterceptor(res, req);
+            // 9. HTTP 传输层错误处理：HTTP 非 2xx 时，优先用 APIStyle 解析响应体
+            // HTTP transport error: when !res.ok, try APIStyle first, fall back to transport error
+            if (!res.ok) {
+                throw this.buildHttpError(res, requestStyle, traceId, fullUrl);
+            }
+            // 10. 统一响应处理：APIStyle 转换 + isSuccess 业务校验 + 返回业务数据
+            // Unified response handling: APIStyle transform + isSuccess check + return business data
+            // 注意：handleResponse 内部会抛出 DataHubError，与原逻辑保持一致
+            // Note: handleResponse throws DataHubError on business failure, consistent with original logic
+            const handled = this.handleResponse(res, requestStyle, traceId, fullUrl);
+            // 11. 缓存写入：查询类请求成功后写入缓存（写入原始 res，保持现有行为）
+            // Cache write: write to cache after successful query request (write raw res, keep existing behavior)
+            if (cacheable && !merged.skipCache) {
+                const ttl = merged.cacheTTL ?? DEFAULT_CONFIG.defaultCacheTTL;
+                cacheSet(fullUrl, data, res, ttl);
+            }
+            // 返回经 handleResponse 处理后的响应（data 已替换为业务数据）
+            // Return the response processed by handleResponse (data replaced with business data)
+            return handled;
+        }
+        catch (err) {
+            // 统一错误处理：将各类异常转换为 DataHubError
+            // Unified error handling: convert all exceptions to DataHubError
+            const error = this.normalizeError(err, fullUrl, traceId);
+            if (this.config.onError) {
+                this.config.onError(error, req);
+            }
+            throw error;
+        }
+        finally {
+            // 无论成功失败，标记 loading 结束 / Mark loading end regardless of success or failure
+            loadingEnd(fullUrl);
+        }
+    }
+    /**
+     * 构造 HTTP 传输层错误：优先用 APIStyle 解析响应体，回退到 transport error。
+     * Build HTTP transport error: try APIStyle first, fall back to transport error.
+     */
+    buildHttpError(res, requestStyle, traceId, fullUrl) {
+        if (requestStyle) {
+            const result = requestStyle.onResponse(res);
+            return new DataHubErrorClass({
+                code: result.code ?? `HTTP_${res.status}`,
+                message: result.message || `HTTP request failed with status ${res.status}`,
+                trace: traceId,
+                status: res.status,
+                url: fullUrl,
+                data: res.data,
+            });
+        }
+        return this.createTransportError(res, traceId, fullUrl);
+    }
+    /**
+     * 是否可缓存：strategy 默认判定，或 forceCache 强制启用。
+     * Whether cacheable: by strategy, or force-enabled by forceCache.
+     */
+    isCacheable(strategy, options) {
+        return strategy.cacheable || options.forceCache === true;
+    }
+    /**
+     * 是否可去重：strategy 默认判定，或 forceDedup 强制启用。
+     * Whether dedupable: by strategy, or force-enabled by forceDedup.
+     */
+    isDedupable(strategy, options) {
+        return strategy.dedupable || options.forceDedup === true;
+    }
+    /**
+     * 是否需要幂等防护：strategy 判定为提交类、未跳过、且未被 force 选项豁免。
+     * Whether idempotent guard applies: strategy says submit, not skipped, and not
+     * exempted by forceDedup/forceCache (which mark the request as a query).
+     */
+    shouldGuardIdempotent(strategy, options) {
+        if (!strategy.idempotent || options.skipIdempotent)
+            return false;
+        const forceQuery = options.forceDedup === true || options.forceCache === true;
+        return !forceQuery;
+    }
+    /**
+     * 统一响应处理：APIStyle 转换 + isSuccess 业务校验 + 返回业务数据
+     * Unified response handling: APIStyle transform + isSuccess check + return business data
+     *
+     * 抽取该方法的目的：让「实际请求路径」与「缓存命中路径」走完全一致的响应处理逻辑，
+     * 避免缓存命中时跳过 isSuccess 校验或丢失 code/message 等字段。
+     *
+     * This method is extracted so that both the real-request path and the cache-hit path
+     * share identical response handling, avoiding skipped isSuccess checks or lost
+     * code/message fields when cache hits.
+     *
+     * @param res - 适配器返回的原始响应 / Raw response from adapter
+     * @param requestStyle - 解析后的 APIStyle / Resolved APIStyle
+     * @param traceId - 链路追踪 ID / Trace ID
+     * @param fullUrl - 完整请求 URL / Full request URL
+     * @returns 业务数据已替换的响应 / Response with business data replaced
+     */
+    handleResponse(res, requestStyle, traceId, fullUrl) {
+        // 无 APIStyle：直接返回原始响应，不做业务转换 / No APIStyle: return raw response
+        if (!requestStyle)
+            return res;
+        // 使用 APIStyle 解析业务结果（code/message/data）
+        // Use APIStyle to parse business result (code/message/data)
+        const result = requestStyle.onResponse(res);
+        // 业务错误处理：根据风格自定义的成功判断
+        // Business error handling: success check defined by the style
+        if (!requestStyle.isSuccess(result)) {
+            throw new DataHubErrorClass({
+                code: result.code,
+                message: result.message || `error: ${result.code}`,
+                trace: traceId,
+                status: res.status,
+                url: fullUrl,
+            });
+        }
+        // 返回时 data 替换为业务数据 / Replace data with business data in response
+        return { ...res, data: result.data };
+    }
+    // ─── 状态清理方法 / State Cleanup Methods ─────────────────────
+    /** 清空所有缓存 / Clear all cache */
+    clearCache() {
+        cacheClear();
+    }
+    /** 清空所有去重记录 / Clear all dedup records */
+    clearDedup() {
+        dedupClear();
+    }
+    /** 清空所有幂等锁 / Clear all idempotent locks */
+    clearIdempotent() {
+        idempotentClear();
+    }
+    // ─── 配置修改方法 / Configuration Modification Methods ─────────
+    /**
+     * 设置请求拦截器 / Set request interceptor
+     */
+    setRequestInterceptor(handler) {
+        this.config.onRequest = handler;
+    }
+    /**
+     * 设置响应拦截器 / Set response interceptor
+     */
+    setResponseInterceptor(handler) {
+        this.config.onResponse = handler;
+    }
+    /**
+     * 设置全局错误回调 / Set global error handler
+     */
+    setErrorHandler(handler) {
+        this.config.onError = handler;
+    }
+    /**
+     * 更新全局配置（合并方式） / Update global config (merge mode)
+     */
+    updateConfig(config) {
+        this.config = { ...this.config, ...config };
+    }
+    /**
+     * 获取当前配置（只读副本） / Get current config (read-only copy)
+     */
+    getConfig() {
+        return { ...this.config };
+    }
+    // ─── 私有方法 / Private Methods ───────────────────────────────
+    /**
+     * 解析适配器 / Resolve adapter
+     */
+    resolveAdapter(options) {
+        if (this.config.forceMock || options.mock) {
+            return this.adapters.get('mock') ?? this.adapters.get(DEFAULT_CONFIG.defaultAdapter);
+        }
+        const name = options.adapter ?? this.config.defaultAdapter ?? DEFAULT_CONFIG.defaultAdapter;
+        const adapter = this.adapters.get(name);
+        if (!adapter) {
+            throw new DataHubErrorClass({
+                code: 'AdapterNotFound',
+                message: `Adapter "${name}" is not registered`,
+            });
+        }
+        return adapter;
+    }
+    /**
+     * 拼接完整 URL / Resolve full URL
+     */
+    resolveUrl(url) {
+        if (this.config.baseURL && !url.startsWith('http')) {
+            let base = this.config.baseURL;
+            while (base.endsWith('/'))
+                base = base.slice(0, -1);
+            let path = url;
+            while (path.startsWith('/'))
+                path = path.slice(1);
+            return `${base}/${path}`;
+        }
+        return url;
+    }
+    /**
+     * 合并请求配置 / Merge request options
+     */
+    mergeOptions(options) {
+        return {
+            timeout: DEFAULT_CONFIG.defaultTimeout,
+            cacheTTL: DEFAULT_CONFIG.defaultCacheTTL,
+            ...options,
+        };
+    }
+    /**
+     * 生成 traceId / Generate traceId
+     */
+    generateTraceId() {
+        if (this.config.generateTraceId)
+            return this.config.generateTraceId();
+        if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {
+            return crypto.randomUUID();
+        }
+        const timestamp = (typeof performance === 'undefined' ? Date.now() : performance.now()).toString(36);
+        const bytes = new Uint8Array(8);
+        if (typeof crypto !== 'undefined' && crypto.getRandomValues) {
+            crypto.getRandomValues(bytes);
+        }
+        const random = Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('');
+        return timestamp + random;
+    }
+    /**
+     * 根据 HTTP 传输层错误创建 DataHubError / Create DataHubError from HTTP transport error
+     */
+    createTransportError(res, traceId, url) {
+        return new DataHubErrorClass({
+            code: `HTTP_${res.status}`,
+            message: `HTTP request failed with status ${res.status}`,
+            trace: traceId,
+            status: res.status,
+            url,
+            data: res.data,
+        });
+    }
+    /**
+     * 标准化错误：将各类异常统一转换为 DataHubError
+     * Normalize errors: convert all exception types to DataHubError uniformly
+     */
+    normalizeError(err, url, traceId) {
+        if (err instanceof DataHubErrorClass)
+            return err;
+        if (err instanceof DOMException && err.name === 'AbortError') {
+            return new DataHubErrorClass({
+                code: 'RequestAborted',
+                message: 'Request was aborted',
+                trace: traceId,
+                url,
+            });
+        }
+        if (err instanceof TypeError) {
+            return new DataHubErrorClass({
+                code: 'NetworkError',
+                message: err.message ?? 'Network error',
+                trace: traceId,
+                url,
+            });
+        }
+        const message = err instanceof Error ? err.message : String(err);
+        return new DataHubErrorClass({
+            code: 'UnknownError',
+            message,
+            trace: traceId,
+            url,
+        });
+    }
+}

package/dist/core/datahub/core/index.js

@@ -0,0 +1,7 @@
+/**
+ * @file Core 模块导出 / Core Module Exports
+ * @description 统一导出核心调度器和内置适配器。
+ *              Unified export of the core dispatcher and built-in adapters.
+ */
+export { DataHubCore } from './datahub-core';
+export { FetchAdapter, MockAdapter } from './adapter';

package/dist/core/datahub/index.js

@@ -0,0 +1,50 @@
+/**
+ * @file DataHub 数据中间层 — 对外出口 / DataHub Data Middleware — Public Exports
+ * @description 提供统一的导入入口，导出所有公开 API：
+ *              - 核心类：DataHubCore
+ *              - 内置适配器：FetchAdapter、MockAdapter
+ *              - 类型定义：所有 interface / type / class
+ *              - 工具函数：策略解析、缓存、去重、loading、幂等防护
+ *              - 默认实例：default export（推荐使用默认实例或 new DataHubCore()）
+ *
+ *              Note: DataHub handles only the HTTP transport layer, not business protocols.
+ *              DataHubAdapterResponse.data is raw JSON; business protocol is interpreted by the consumer.
+ *
+ * @example
+ * // 使用默认实例 / Use default instance
+ * import {dataHub} from './datahub';
+ * const res = await dataHub.request('/order/query', { id: '1' });
+ * // res.ok — HTTP 是否成功 / whether HTTP succeeded
+ * // res.data — 原始 JSON，由使用者自行解析业务协议 / raw JSON, consumer parses business protocol
+ *
+ * @example
+ * // 创建独立实例 / Create isolated instance
+ * import { DataHubCore } from './datahub';
+ * const hub = new DataHubCore({ baseURL: '/api' });
+ *
+ * @example
+ * // 扩展适配器 / Extend with custom adapter
+ * import { DataHubCore } from './datahub';
+ * const hub = new DataHubCore();
+ * hub.registerAdapter({ name: 'axios', async request(req) { ... } });
+ */
+// ─── 核心类 / Core Class ────────────────────────────────────────
+export { DataHubCore } from './core';
+// ─── 内置适配器 / Built-in Adapters ─────────────────────────────
+export { FetchAdapter, MockAdapter } from './core/adapter';
+export { getBuiltinStyle, getBuiltinStyleNames } from './core/api-styles';
+// ─── 错误类导出 / Error Class Export ────────────────────────────
+export { DataHubError } from './types';
+// ─── 策略解析 / Strategy Resolution ─────────────────────────────
+export { resolveStrategy } from './config/strategy';
+// ─── 工具函数导出 / Utility Function Exports ────────────────────
+export { isQueryAction, setQueryKeywords, getQueryKeywords } from './utils/is-query';
+export { buildKey } from './utils/common';
+export { cacheGet, cacheSet, cacheDelete, cacheClear } from './utils/cache';
+export { dedupTrack, dedupClear } from './utils/dedup';
+export { loadingStart, loadingEnd, isLoading, onLoadingChange } from './utils/loading';
+export { idempotentGuard, idempotentClear } from './utils/idempotent';
+// ─── 默认实例 / Default Instance ────────────────────────────────
+import { DataHubCore } from './core';
+/** 默认 DataHub 实例，开箱即用 / Default DataHub instance, ready to use out of the box */
+export const dataHub = new DataHubCore();

package/dist/core/datahub/types.d.ts

@@ -74,10 +74,30 @@ export interface DataHubRequestOptions {
     skipDedup?: boolean;
     /** 是否跳过幂等防护，允许同一提交重复执行 / Whether to skip idempotent guard, allowing duplicate submissions */
     skipIdempotent?: boolean;
+    /**
+     * 是否强制启用去重：为 true 时无视 URL 命名约定，对本请求启用并发去重。
+     * 适用于 URL 不以 query/list/get 结尾、但语义为查询且可能被并发调用的 GET 请求。
+     * Force enable dedup: when true, bypasses URL naming convention and enables
+     * concurrent dedup for this request. Applicable to GET requests whose URL does
+     * not end with query/list/get but are semantically queries and may be called concurrently.
+     */
+    forceDedup?: boolean;
+    /**
+     * 是否强制启用缓存：为 true 时无视 URL 命名约定，对本请求启用结果缓存。
+     * 配合 cacheTTL 控制有效期。适用于 URL 不以 query/list/get 结尾、
+     * 但语义为查询且结果可短期复用的 GET 请求。
+     * Force enable cache: when true, bypasses URL naming convention and enables
+     * result caching for this request. Use with cacheTTL to control TTL.
+     * Applicable to GET requests whose URL does not end with query/list/get
+     * but are semantically queries with short-term reusable results.
+     */
+    forceCache?: boolean;
     /** 是否使用 Mock 适配器 / Whether to use the Mock adapter */
     mock?: boolean;
     /** Mock 返回的业务数据 / Mock business data to return */
     mockData?: unknown;
+    /** Mock JSON 文件路径，用于加载本地 mock 数据文件 / Mock JSON file path for loading local mock data files */
+    mockPath?: string;
     /** Mock 延迟时间（毫秒），模拟网络耗时，默认 300 / Mock delay in ms simulating network latency, default 300 */
     mockDelay?: number;
     /** 手动指定 traceId，不传则自动生成 / Manually specified traceId, auto-generated if omitted */
@@ -166,6 +186,8 @@ export interface DataHubErrorDetail {
     status?: number;
     /** 请求 URL / Request URL */
     url?: string;
+    /** 原始响应体 / Raw response body */
+    data?: unknown;
 }
 /**
  * DataHub 统一错误类 / DataHub Unified Error Class
@@ -184,6 +206,8 @@ export declare class DataHubError extends Error {
     readonly status?: number;
     /** 请求 URL / Request URL */
     readonly url?: string;
+    /** 原始响应体 / Raw response body */
+    readonly data?: unknown;
     constructor(detail: DataHubErrorDetail);
 }
 /**

package/dist/core/datahub/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/core/datahub/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/core/datahub/types.ts"],"names":[],"mappings":"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"}