@aithe/aithe-ui 26.2.2 → 26.3.1

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

@@ -0,0 +1,131 @@
+/**
+ * @file 内置 APIStyle 实现 / Built-in APIStyle Implementations
+ * @description 提供开箱即用的 APIStyle：
+ *              - default: Aithe UI 标准风格（请求 { data }，响应 { code/message/data }）
+ *              - k8s: Kubernetes API 风格（请求直接传对象，响应包含 kind/apiVersion/metadata）
+ *              - raw: 原始风格，不对请求体和响应做任何转换，直接透传原始 HTTP 数据
+ *
+ *              Provides ready-to-use APIStyle implementations:
+ *              - default: Aithe UI standard style (request { data }, response { code/message/data })
+ *              - k8s: Kubernetes API style (request sends object directly, response includes kind/apiVersion/metadata)
+ *              - raw: Passthrough style, no request/response transformation, returns raw HTTP data directly
+ */
+// ─── Default Style / 默认风格 ──────────────────────────────────
+const defaultStyle = {
+    name: 'default',
+    onRequest(req) {
+        req.data = { data: req.data };
+    },
+    onResponse(res) {
+        const rawData = res.data;
+        if (!rawData || typeof rawData !== 'object') {
+            return { code: 'UnknownError', message: 'Invalid response format', data: undefined };
+        }
+        const obj = rawData;
+        return {
+            code: obj.code ?? 'UnknownError',
+            message: obj.message ?? '',
+            data: obj.data,
+        };
+    },
+    isSuccess(result) {
+        return result.code === 'Ok';
+    },
+};
+// ─── K8s Style / Kubernetes 风格 ───────────────────────────────
+const k8sStyle = {
+    name: 'k8s',
+    onRequest(_req) {
+        // K8s 风格直接发送业务对象，不额外包装
+    },
+    onResponse(res) {
+        const rawData = res.data;
+        if (!rawData || typeof rawData !== 'object') {
+            return { code: 'UnknownError', message: 'Invalid response format', data: undefined };
+        }
+        const obj = rawData;
+        // K8s 非 2xx 错误响应：Status 对象 { kind: "Status", status: "Failure", message, reason, code }
+        // K8s error response: Status object with top-level status string and message/reason fields
+        if (!res.ok && typeof obj.status === 'string') {
+            return {
+                code: obj.reason ?? obj.status ?? 'UnknownError',
+                message: obj.message ?? '',
+                data: rawData,
+            };
+        }
+        const status = obj.status;
+        const phase = status?.phase;
+        const conditions = status?.conditions;
+        const reason = status?.reason;
+        const k8sMessage = status?.message;
+        let code = 'Ok';
+        let message = '';
+        if (phase && phase !== 'Active' && phase !== 'Available' && phase !== 'Ready') {
+            code = phase;
+        }
+        if (reason) {
+            code = reason;
+        }
+        if (conditions && conditions.length > 0) {
+            const lastCondition = conditions.at(-1);
+            if (lastCondition && lastCondition.status !== 'True') {
+                code = lastCondition.reason ?? code;
+                message = lastCondition.message ?? '';
+            }
+        }
+        if (k8sMessage) {
+            message = k8sMessage;
+        }
+        return {
+            code,
+            message,
+            data: rawData,
+        };
+    },
+    isSuccess(result) {
+        return result.code === 'Ok';
+    },
+};
+// ─── 注册表 / Registry ─────────────────────────────────────────
+/**
+ * Raw 风格：不对请求体和响应做任何转换，直接透传原始 HTTP 数据。
+ * 适用于对接不遵循统一业务协议的三方接口。
+ * Raw style: no request/response transformation, passes raw HTTP data through.
+ * Useful for third-party APIs that don't follow a standard business protocol.
+ */
+const rawStyle = {
+    name: 'raw',
+    onRequest(_req) {
+        // 不包装请求体，直接透传
+    },
+    onResponse(res) {
+        return {
+            code: 'Ok',
+            message: '',
+            data: res.data,
+        };
+    },
+    isSuccess(_result) {
+        return true;
+    },
+};
+const builtinStyles = {
+    default: defaultStyle,
+    k8s: k8sStyle,
+    raw: rawStyle,
+};
+/**
+ * 获取内置 APIStyle / Get a built-in APIStyle by name
+ * @param name - 风格名称，可选 "default" 或 "k8s" / Style name, either "default" or "k8s"
+ * @returns APIStyle 实例，未找到返回 undefined / APIStyle instance, or undefined if not found
+ */
+export function getBuiltinStyle(name) {
+    return builtinStyles[name];
+}
+/**
+ * 获取所有内置 APIStyle 名称列表 / Get all built-in APIStyle names
+ * @returns 风格名称数组 / Array of style names
+ */
+export function getBuiltinStyleNames() {
+    return Object.keys(builtinStyles);
+}

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

@@ -0,0 +1,166 @@
+/**
+ * @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 type { DataHubConfig, DataHubAdapter, DataHubRequestOptions, DataHubAdapterRequest, DataHubAdapterResponse, DataHubAPIStyle } from '../../datahub/types';
+import { DataHubError as DataHubErrorClass } from '../../datahub/types';
+import { onLoadingChange, isLoading } from '../../datahub/utils/loading';
+/**
+ * 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 declare class DataHubCore {
+    /** 已注册的适配器映射，键为适配器名称 / Registered adapter map, keyed by adapter name */
+    private readonly adapters;
+    /** 全局配置（改为可修改） / Global configuration (now mutable) */
+    private config;
+    /** 当前 APIStyle 实例（为空时不处理业务协议） / Current APIStyle instance (null = skip business protocol) */
+    private apiStyle;
+    /**
+     * @param config - 全局配置 / Global configuration
+     */
+    constructor(config?: DataHubConfig);
+    /**
+     * 注册适配器 / Register an adapter
+     * @param adapter - 适配器实例，需实现 DataHubAdapter 接口 / Adapter instance implementing DataHubAdapter
+     * @throws 如果同名适配器已存在，静默覆盖 / Silently overwrites if an adapter with the same name already exists
+     */
+    registerAdapter(adapter: DataHubAdapter): void;
+    /**
+     * 获取已注册的适配器 / Get a registered adapter by name
+     * @param name - 适配器名称 / Adapter name
+     * @returns 适配器实例，未找到返回 undefined / Adapter instance, or undefined if not found
+     */
+    getAdapter(name: string): DataHubAdapter | undefined;
+    /**
+     * 设置 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: DataHubAPIStyle | string): void;
+    /**
+     * 获取当前 APIStyle / Get current APIStyle
+     * @returns 当前 APIStyle 实例 / Current APIStyle instance
+     */
+    getAPIStyle(): DataHubAPIStyle | undefined;
+    /**
+     * 解析单次请求使用的 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.
+     */
+    private resolveRequestStyle;
+    /**
+     * 统一请求入口 / 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 *\/ }
+     */
+    request<T = unknown>(url: string, data?: unknown, options?: DataHubRequestOptions): Promise<DataHubAdapterResponse<T>>;
+    /** 清空所有缓存 / Clear all cache */
+    clearCache(): void;
+    /** 清空所有去重记录 / Clear all dedup records */
+    clearDedup(): void;
+    /** 清空所有幂等锁 / Clear all idempotent locks */
+    clearIdempotent(): void;
+    /**
+     * 设置请求拦截器 / Set request interceptor
+     */
+    setRequestInterceptor(handler: (req: DataHubAdapterRequest) => DataHubAdapterRequest | void): void;
+    /**
+     * 设置响应拦截器 / Set response interceptor
+     */
+    setResponseInterceptor(handler: (res: DataHubAdapterResponse, req: DataHubAdapterRequest) => DataHubAdapterResponse | void): void;
+    /**
+     * 设置全局错误回调 / Set global error handler
+     */
+    setErrorHandler(handler: (error: DataHubErrorClass, req: DataHubAdapterRequest) => void): void;
+    /**
+     * 更新全局配置（合并方式） / Update global config (merge mode)
+     */
+    updateConfig(config: Partial<DataHubConfig>): void;
+    /**
+     * 获取当前配置（只读副本） / Get current config (read-only copy)
+     */
+    getConfig(): Readonly<DataHubConfig>;
+    /** 订阅 loading 状态变更 / Subscribe to loading state changes */
+    onLoadingChange: typeof onLoadingChange;
+    /** 查询指定 URL 是否正在加载 / Check if the specified URL is currently loading */
+    isLoading: typeof isLoading;
+    /**
+     * 解析适配器 / Resolve adapter
+     */
+    private resolveAdapter;
+    /**
+     * 拼接完整 URL / Resolve full URL
+     */
+    private resolveUrl;
+    /**
+     * 合并请求配置 / Merge request options
+     */
+    private mergeOptions;
+    /**
+     * 生成 traceId / Generate traceId
+     */
+    private generateTraceId;
+    /**
+     * 根据 HTTP 传输层错误创建 DataHubError / Create DataHubError from HTTP transport error
+     */
+    private createTransportError;
+    /**
+     * 标准化错误：将各类异常统一转换为 DataHubError
+     * Normalize errors: convert all exception types to DataHubError uniformly
+     */
+    private normalizeError;
+}
+//# sourceMappingURL=datahub-core.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"datahub-core.d.ts","sourceRoot":"","sources":["../../../../src/core/datahub/core/datahub-core.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAAK,EACV,aAAa,EACb,cAAc,EACd,qBAAqB,EACrB,qBAAqB,EACrB,sBAAsB,EACtB,eAAe,EAChB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,YAAY,IAAI,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAOxE,OAAO,EAA4B,eAAe,EAAE,SAAS,EAAE,MAAM,6BAA6B,CAAC;AAenG;;;;;;;;GAQG;AACH,qBAAa,WAAW;IACtB,wEAAwE;IACxE,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAqC;IAC9D,uDAAuD;IACvD,OAAO,CAAC,MAAM,CAAiB;IAC/B,6FAA6F;IAC7F,OAAO,CAAC,QAAQ,CAA8B;IAE9C;;OAEG;gBACS,MAAM,GAAE,aAAkB;IAatC;;;;OAIG;IACI,eAAe,CAAC,OAAO,EAAE,cAAc,GAAG,IAAI;IAIrD;;;;OAIG;IACI,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS;IAM3D;;;;;;;;;;;;;;;OAeG;IACI,WAAW,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,GAAG,IAAI;IAezD;;;OAGG;IACI,WAAW,IAAI,eAAe,GAAG,SAAS;IAIjD;;;;;OAKG;IACH,OAAO,CAAC,mBAAmB;IAY3B;;;;;;;;;;;;;;;;;;OAkBG;IACU,OAAO,CAAC,CAAC,GAAG,OAAO,EAC9B,GAAG,EAAE,MAAM,EACX,IAAI,CAAC,EAAE,OAAO,EACd,OAAO,CAAC,EAAE,qBAAqB,GAC9B,OAAO,CAAC,sBAAsB,CAAC,CAAC,CAAC,CAAC;IAgJrC,+BAA+B;IACxB,UAAU,IAAI,IAAI;IAIzB,yCAAyC;IAClC,UAAU,IAAI,IAAI;IAIzB,2CAA2C;IACpC,eAAe,IAAI,IAAI;IAM9B;;OAEG;IACI,qBAAqB,CAC1B,OAAO,EAAE,CAAC,GAAG,EAAE,qBAAqB,KAAK,qBAAqB,GAAG,IAAI,GACpE,IAAI;IAIP;;OAEG;IACI,sBAAsB,CAC3B,OAAO,EAAE,CACP,GAAG,EAAE,sBAAsB,EAC3B,GAAG,EAAE,qBAAqB,KACvB,sBAAsB,GAAG,IAAI,GACjC,IAAI;IAIP;;OAEG;IACI,eAAe,CACpB,OAAO,EAAE,CAAC,KAAK,EAAE,iBAAiB,EAAE,GAAG,EAAE,qBAAqB,KAAK,IAAI,GACtE,IAAI;IAIP;;OAEG;IACI,YAAY,CAAC,MAAM,EAAE,OAAO,CAAC,aAAa,CAAC,GAAG,IAAI;IAIzD;;OAEG;IACI,SAAS,IAAI,QAAQ,CAAC,aAAa,CAAC;IAM3C,2DAA2D;IACpD,eAAe,yBAAmB;IAEzC,wEAAwE;IACjE,SAAS,mBAAa;IAI7B;;OAEG;IACH,OAAO,CAAC,cAAc;IAetB;;OAEG;IACH,OAAO,CAAC,UAAU;IAWlB;;OAEG;IACH,OAAO,CAAC,YAAY;IAQpB;;OAEG;IACH,OAAO,CAAC,eAAe;IAgBvB;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAe5B;;;OAGG;IACH,OAAO,CAAC,cAAc;CA0BvB"}