@kine-design/crud 0.0.1-beta.2 → 0.0.1-beta.21

package/composables/request/requestBuilder.ts

@@ -0,0 +1,418 @@
+/**
+ * @description 链式请求构建器
+ * @author 阿怪
+ * @date 2026/3/15
+ * @version v0.0.1
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+
+import type {
+  CachePolicy,
+  ControlPolicy,
+  Lifecycle,
+  NetworkError,
+  RequestConfig,
+  RequestMethod,
+  RetryPolicy,
+  Transport,
+  TransportResponse,
+  WrappedResponse,
+} from './types';
+import { BusinessError, NetworkRequestError } from './types';
+import { buildCacheKey, ControlGate } from './controlGate';
+
+// ────────────────────────────────────────────────────────────────────────────
+// 内部：缓存存储
+// ────────────────────────────────────────────────────────────────────────────
+
+interface CacheEntry {
+  data: unknown;
+  timestamp: number;
+}
+
+const cacheStore = new Map<string, CacheEntry>();
+
+// ────────────────────────────────────────────────────────────────────────────
+// 内部：自动压包
+// ────────────────────────────────────────────────────────────────────────────
+
+/** 判断是否包含 File/Blob */
+function containsFile(obj: unknown): boolean {
+  if (obj instanceof File || obj instanceof Blob || obj instanceof FormData) return true;
+  if (typeof obj === 'object' && obj !== null) {
+    return Object.values(obj as Record<string, unknown>).some(containsFile);
+  }
+  return false;
+}
+
+/** 将普通对象转为 FormData */
+function toFormData(obj: Record<string, unknown>): FormData {
+  const fd = new FormData();
+  for (const [key, value] of Object.entries(obj)) {
+    if (value instanceof File || value instanceof Blob) {
+      fd.append(key, value);
+    } else if (Array.isArray(value)) {
+      value.forEach(item => {
+        if (item instanceof File || item instanceof Blob) {
+          fd.append(key, item);
+        } else {
+          fd.append(key, String(item));
+        }
+      });
+    } else if (value !== null && value !== undefined) {
+      fd.append(key, String(value));
+    }
+  }
+  return fd;
+}
+
+/** 将参数序列化为 query string */
+function toQueryString(params: Record<string, unknown>): string {
+  const parts: string[] = [];
+  for (const [key, value] of Object.entries(params)) {
+    if (value === null || value === undefined) continue;
+    if (Array.isArray(value)) {
+      value.forEach(v => parts.push(`${encodeURIComponent(key)}=${encodeURIComponent(String(v))}`));
+    } else {
+      parts.push(`${encodeURIComponent(key)}=${encodeURIComponent(String(value))}`);
+    }
+  }
+  return parts.join('&');
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// 内部：自动解包
+// ────────────────────────────────────────────────────────────────────────────
+
+/** 根据 Content-Type 解析响应，并检查 WrappedResponse */
+async function unwrapResponse<T>(
+  response: { status: number; statusText: string; headers: Record<string, string>; text(): Promise<string>; json<R>(): Promise<R> },
+): Promise<T> {
+  // HTTP 错误
+  if (response.status < 200 || response.status >= 300) {
+    // 4xx/5xx：尝试解析 body，提取业务错误信息
+    if (response.status >= 400) {
+      const ct = response.headers['content-type'] ?? '';
+      if (ct.includes('application/json')) {
+        try {
+          const json = await response.json<WrappedResponse<unknown>>();
+          if (isWrappedResponse(json) && !json.success) {
+            throw new BusinessError(json.message || `请求失败（${response.status}）`);
+          }
+        } catch (e) {
+          if (e instanceof BusinessError) throw e;
+        }
+      }
+    }
+    throw new NetworkRequestError({
+      type: 'httpError',
+      status: response.status,
+      statusText: response.statusText,
+    });
+  }
+
+  const contentType = response.headers['content-type'] ?? '';
+
+  // JSON 响应
+  if (contentType.includes('application/json')) {
+    const json = await response.json<WrappedResponse<T> | T>();
+
+    // 检查是否为 WrappedResponse 结构
+    if (isWrappedResponse<T>(json)) {
+      if (!json.success) {
+        throw new BusinessError(json.message || '请求失败');
+      }
+      return json.data;
+    }
+
+    return json as T;
+  }
+
+  // 其他类型直接返回文本
+  const text = await response.text();
+  return text as unknown as T;
+}
+
+function isWrappedResponse<T>(value: unknown): value is WrappedResponse<T> {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'success' in value &&
+    'data' in value &&
+    typeof (value as Record<string, unknown>).success === 'boolean'
+  );
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// 内部：重试执行
+// ────────────────────────────────────────────────────────────────────────────
+
+async function withRetry<T>(fn: () => Promise<T>, policy: RetryPolicy, signal?: AbortSignal): Promise<T> {
+  if (policy.type === 'none') return fn();
+
+  let lastError: unknown;
+  const maxAttempts = policy.maxAttempts;
+
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    try {
+      return await fn();
+    } catch (e) {
+      lastError = e;
+
+      // 被取消则不重试
+      if (signal?.aborted) throw e;
+      // 业务错误不重试
+      if (e instanceof BusinessError) throw e;
+
+      if (attempt < maxAttempts) {
+        const delay = policy.type === 'fixed'
+          ? policy.delay
+          : Math.min(policy.initialDelay * Math.pow(policy.multiplier, attempt - 1), policy.maxDelay);
+
+        await new Promise<void>((resolve, reject) => {
+          const timer = setTimeout(resolve, delay);
+          signal?.addEventListener('abort', () => {
+            clearTimeout(timer);
+            reject(new NetworkRequestError({ type: 'aborted' }));
+          }, { once: true });
+        });
+      }
+    }
+  }
+
+  throw lastError;
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// RequestBuilder
+// ────────────────────────────────────────────────────────────────────────────
+
+export interface RequestBuilderContext {
+  transport: Transport;
+  controlGate: ControlGate;
+  baseURL: string;
+  defaultHeaders: Record<string, string>;
+  getToken?: () => string | null | undefined;
+  onUnauthorized?: () => void;
+  responseInterceptor?: <T>(data: T) => T;
+  /** 用户反馈处理器（写操作成功后自动 showSuccess） */
+  feedback?: import('./types').UserFeedbackHandler;
+  /** 注册 abort controller，供生命周期管理 */
+  registerAbort?: (controller: AbortController) => void;
+}
+
+export class RequestBuilder {
+  private method: RequestMethod;
+  private url: string;
+  private body: unknown;
+  private config: RequestConfig = {};
+  private context: RequestBuilderContext;
+  private customHeaders: Record<string, string> = {};
+
+  constructor(
+    context: RequestBuilderContext,
+    method: RequestMethod,
+    url: string,
+    body?: unknown,
+  ) {
+    this.context = context;
+    this.method = method;
+    this.url = url;
+    this.body = body;
+  }
+
+  // ── 链式 API ────────────────────────────────────────────────────────────
+
+  cache(policy: CachePolicy): this {
+    this.config.cache = policy;
+    return this;
+  }
+
+  retry(policy: RetryPolicy): this {
+    this.config.retry = policy;
+    return this;
+  }
+
+  debounce(delay: number): this {
+    this.config.control = { ...this.config.control, debounce: delay };
+    return this;
+  }
+
+  throttle(interval: number): this {
+    this.config.control = { ...this.config.control, throttle: interval };
+    return this;
+  }
+
+  deduplicate(enabled = true): this {
+    this.config.control = { ...this.config.control, deduplicate: enabled };
+    return this;
+  }
+
+  timeout(ms: number): this {
+    this.config.timeout = ms;
+    return this;
+  }
+
+  totalTimeout(ms: number): this {
+    this.config.totalTimeout = ms;
+    return this;
+  }
+
+  lifecycle(lc: Lifecycle): this {
+    this.config.lifecycle = lc;
+    return this;
+  }
+
+  priority(p: number): this {
+    this.config.control = { ...this.config.control, priority: p };
+    return this;
+  }
+
+  headers(h: Record<string, string>): this {
+    Object.assign(this.customHeaders, h);
+    return this;
+  }
+
+  // ── 执行 ────────────────────────────────────────────────────────────────
+
+  async execute<T>(): Promise<T> {
+    const { transport, controlGate, baseURL, defaultHeaders, getToken, onUnauthorized, responseInterceptor, registerAbort } = this.context;
+
+    // 构建完整 URL
+    let fullURL = this.url.startsWith('http') ? this.url : `${baseURL}${this.url}`;
+
+    // AbortController
+    const abortController = new AbortController();
+    registerAbort?.(abortController);
+
+    // 总超时
+    let totalTimeoutId: ReturnType<typeof setTimeout> | undefined;
+    if (this.config.totalTimeout) {
+      totalTimeoutId = setTimeout(() => abortController.abort('totalTimeout'), this.config.totalTimeout);
+    }
+
+    try {
+      // 构建请求头
+      const reqHeaders: Record<string, string> = { ...defaultHeaders, ...this.customHeaders };
+
+      // 注入 token
+      const token = getToken?.();
+      if (token) {
+        reqHeaders['Authorization'] = `Bearer ${token}`;
+      }
+
+      // 自动压包
+      let reqBody: BodyInit | null = null;
+
+      if (this.method === 'GET' && this.body && typeof this.body === 'object') {
+        // GET 参数拼接到 query string
+        const qs = toQueryString(this.body as Record<string, unknown>);
+        if (qs) {
+          fullURL += (fullURL.includes('?') ? '&' : '?') + qs;
+        }
+      } else if (this.body !== undefined && this.body !== null) {
+        if (this.body instanceof FormData) {
+          reqBody = this.body;
+        } else if (containsFile(this.body)) {
+          reqBody = toFormData(this.body as Record<string, unknown>);
+        } else {
+          reqBody = JSON.stringify(this.body);
+          reqHeaders['Content-Type'] = 'application/json';
+        }
+      }
+
+      // 缓存 key
+      const cacheKey = buildCacheKey(this.method, fullURL, this.body);
+
+      // 缓存策略检查
+      const cachePolicy = this.config.cache ?? { type: 'none' as const };
+      if (cachePolicy.type === 'cacheFirst' || cachePolicy.type === 'staleWhileRevalidate') {
+        const cached = cacheStore.get(cacheKey);
+        if (cached) {
+          const age = (Date.now() - cached.timestamp) / 1000;
+          if (age < cachePolicy.maxAge) {
+            if (cachePolicy.type === 'staleWhileRevalidate') {
+              // 返回旧数据，后台刷新
+              this.executeTransport<T>(transport, fullURL, reqHeaders, reqBody, abortController.signal)
+                .then(data => { cacheStore.set(cacheKey, { data, timestamp: Date.now() }); })
+                .catch(() => { /* 后台刷新失败静默忽略 */ });
+            }
+            return cached.data as T;
+          }
+        }
+      }
+
+      // 执行函数（含重试）
+      const doRequest = () => this.executeTransport<T>(transport, fullURL, reqHeaders, reqBody, abortController.signal);
+
+      // 控制门
+      const controlPolicy: ControlPolicy = this.config.control ?? {};
+      const retryPolicy = this.config.retry ?? { type: 'none' as const };
+
+      const result = await controlGate.execute(cacheKey, async () => {
+        return withRetry(doRequest, retryPolicy, abortController.signal);
+      }, controlPolicy);
+
+      // 写入缓存
+      if (cachePolicy.type !== 'none') {
+        cacheStore.set(cacheKey, { data: result, timestamp: Date.now() });
+      }
+
+      // 响应拦截器
+      const finalResult = responseInterceptor ? responseInterceptor(result) : result;
+
+      // 写操作成功后自动反馈
+      if (this.context.feedback && ['POST', 'PUT', 'PATCH', 'DELETE'].includes(this.method)) {
+        this.context.feedback.showSuccess('操作成功');
+      }
+
+      return finalResult as T;
+    } catch (error) {
+      // 401 检测
+      if (error instanceof NetworkRequestError && error.detail.type === 'httpError' && error.detail.status === 401) {
+        onUnauthorized?.();
+      }
+      // 写操作失败自动反馈错误信息
+      if (this.context.feedback) {
+        const msg = error instanceof BusinessError ? error.message
+          : error instanceof NetworkRequestError ? `请求失败: ${error.message}`
+          : '操作失败';
+        this.context.feedback.showError(msg);
+      }
+      throw error;
+    } finally {
+      if (totalTimeoutId !== undefined) clearTimeout(totalTimeoutId);
+    }
+  }
+
+  // ── 内部传输 ──────────────────────────────────────────────────────────────
+
+  private async executeTransport<T>(
+    transport: Transport,
+    url: string,
+    headers: Record<string, string>,
+    body: BodyInit | null,
+    signal: AbortSignal,
+  ): Promise<T> {
+    let response: TransportResponse;
+    try {
+      response = await transport.send({
+        url,
+        method: this.method,
+        headers,
+        body,
+        signal,
+        timeout: this.config.timeout,
+      });
+    } catch (error) {
+      // transport 层抛出的是 NetworkError 裸对象，统一包装为 NetworkRequestError
+      if (error && typeof error === 'object' && 'type' in error) {
+        throw new NetworkRequestError(error as NetworkError);
+      }
+      throw new NetworkRequestError({ type: 'unknown', error });
+    }
+
+    return unwrapResponse<T>(response);
+  }
+}

package/composables/request/transport/fetchTransport.ts

@@ -0,0 +1,79 @@
+/**
+ * @description 基于 fetch API 的传输层实现
+ * @author 阿怪
+ * @date 2026/3/15
+ * @version v0.0.1
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+
+import type { Transport, TransportRequest, TransportResponse } from '../types';
+
+/** 将 fetch Response 的 Headers 转为普通对象 */
+function headersToRecord(headers: Headers): Record<string, string> {
+  const record: Record<string, string> = {};
+  headers.forEach((value, key) => {
+    record[key.toLowerCase()] = value;
+  });
+  return record;
+}
+
+/** 将 fetch Response 适配为 TransportResponse */
+function wrapFetchResponse(response: Response): TransportResponse {
+  return {
+    status: response.status,
+    statusText: response.statusText,
+    headers: headersToRecord(response.headers),
+    body: response.body,
+    text: () => response.text(),
+    json: <T>() => response.json() as Promise<T>,
+    blob: () => response.blob(),
+  };
+}
+
+export class FetchTransport implements Transport {
+  async send(request: TransportRequest): Promise<TransportResponse> {
+    const controller = new AbortController();
+
+    // 将外部 signal 的 abort 传播到内部 controller
+    if (request.signal) {
+      if (request.signal.aborted) {
+        controller.abort(request.signal.reason);
+      } else {
+        request.signal.addEventListener('abort', () => {
+          controller.abort(request.signal!.reason);
+        }, { once: true });
+      }
+    }
+
+    // 超时控制
+    let timeoutId: ReturnType<typeof setTimeout> | undefined;
+    if (request.timeout !== undefined && request.timeout > 0) {
+      timeoutId = setTimeout(() => controller.abort('timeout'), request.timeout);
+    }
+
+    try {
+      const response = await fetch(request.url, {
+        method: request.method,
+        headers: request.headers,
+        body: request.body,
+        signal: controller.signal,
+      });
+
+      return wrapFetchResponse(response);
+    } catch (error) {
+      // 区分超时和手动取消
+      if (error instanceof DOMException && error.name === 'AbortError') {
+        if (controller.signal.reason === 'timeout') {
+          throw { type: 'timeout' as const };
+        }
+        throw { type: 'aborted' as const };
+      }
+      throw error;
+    } finally {
+      if (timeoutId !== undefined) {
+        clearTimeout(timeoutId);
+      }
+    }
+  }
+}

package/composables/request/transport/xhrTransport.ts

@@ -0,0 +1,100 @@
+/**
+ * @description 基于 XMLHttpRequest 的传输层实现，支持上传进度
+ * @author 阿怪
+ * @date 2026/3/15
+ * @version v0.0.1
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+
+import type { Transport, TransportRequest, TransportResponse } from '../types';
+
+/** 解析 XHR 响应头字符串为 Record */
+function parseResponseHeaders(rawHeaders: string): Record<string, string> {
+  const headers: Record<string, string> = {};
+  if (!rawHeaders) return headers;
+
+  rawHeaders.split('\r\n').forEach(line => {
+    const idx = line.indexOf(':');
+    if (idx > 0) {
+      const key = line.slice(0, idx).trim().toLowerCase();
+      const value = line.slice(idx + 1).trim();
+      headers[key] = value;
+    }
+  });
+  return headers;
+}
+
+export class XhrTransport implements Transport {
+  send(request: TransportRequest): Promise<TransportResponse> {
+    return new Promise((resolve, reject) => {
+      const xhr = new XMLHttpRequest();
+
+      xhr.open(request.method, request.url, true);
+
+      // 设置请求头
+      for (const [key, value] of Object.entries(request.headers)) {
+        xhr.setRequestHeader(key, value);
+      }
+
+      // 超时
+      if (request.timeout !== undefined && request.timeout > 0) {
+        xhr.timeout = request.timeout;
+      }
+
+      // 上传进度
+      if (request.onUploadProgress) {
+        const onProgress = request.onUploadProgress;
+        xhr.upload.addEventListener('progress', (event) => {
+          if (event.lengthComputable) {
+            onProgress({ loaded: event.loaded, total: event.total });
+          }
+        });
+      }
+
+      // 外部取消信号
+      if (request.signal) {
+        if (request.signal.aborted) {
+          xhr.abort();
+          reject({ type: 'aborted' as const });
+          return;
+        }
+        request.signal.addEventListener('abort', () => xhr.abort(), { once: true });
+      }
+
+      xhr.onload = () => {
+        const headers = parseResponseHeaders(xhr.getAllResponseHeaders());
+        const responseText = xhr.responseText;
+
+        const response: TransportResponse = {
+          status: xhr.status,
+          statusText: xhr.statusText,
+          headers,
+          body: null,
+          text: () => Promise.resolve(responseText),
+          json: <T>() => {
+            try { return Promise.resolve(JSON.parse(responseText) as T); }
+            catch (e) { return Promise.reject(e); }
+          },
+          blob: () => Promise.resolve(new Blob([responseText])),
+        };
+
+        resolve(response);
+      };
+
+      xhr.onerror = () => {
+        reject({ type: 'unknown' as const, error: new Error('网络错误') });
+      };
+
+      xhr.ontimeout = () => {
+        reject({ type: 'timeout' as const });
+      };
+
+      xhr.onabort = () => {
+        reject({ type: 'aborted' as const });
+      };
+
+      xhr.send(request.body as XMLHttpRequestBodyInit | null);
+    });
+  }
+}