create-bubbles 0.1.18 → 0.1.20

package/template-vp-react-shadcn/src/utils/request/alova-core/index.ts

@@ -0,0 +1,425 @@
+import {
+  deepMergeObject,
+  isPlainObject,
+  isReadableStream,
+  tryParseJsonString,
+} from './utils'
+import type {
+  AlovaGlobalCacheAdapter,
+  AlovaOptions,
+  AlovaRequestAdapter,
+  GlobalCacheConfig,
+  StatesExport,
+  StatesHook,
+} from 'alova'
+import { createAlova } from 'alova'
+import type { FetchRequestInit } from 'alova/fetch'
+import adapterFetch from 'alova/fetch'
+
+type MaybePromise<T> = T | Promise<T>
+type HeaderValue =
+  | string
+  | number
+  | boolean
+  | null
+  | undefined
+  | (() => MaybePromise<string | number | boolean | null | undefined>)
+type StatusMatcher<RE> = number | number[] | ((status: number, response: RE) => boolean)
+type CodeMatcher = Array<number | string>
+
+export interface StatusMap<RE = unknown> {
+  success?: StatusMatcher<RE>
+  unAuthorized?: StatusMatcher<RE>
+}
+
+export interface CodeMap {
+  success?: CodeMatcher
+  unAuthorized?: CodeMatcher
+}
+
+export interface RequestMeta {
+  isWrapped?: boolean
+  isTransformResponse?: boolean
+  isShowSuccessMessage?: boolean
+  isShowErrorMessage?: boolean
+}
+
+export interface BaseRequestOption<
+  RC extends object = FetchRequestInit,
+  RE = Response,
+  RH = Headers,
+  SE extends StatesExport<any> = StatesExport<any>,
+> extends RequestMeta {
+  baseUrl?: string
+  timeout?: number
+  commonHeaders?: () => Record<string, HeaderValue>
+  statusMap?: StatusMap<RE>
+  codeMap?: CodeMap
+  responseCodeKey?: string
+  responseDataKey?: string
+  responseMessageKey?: string
+  cacheFor?: GlobalCacheConfig<any> | null
+  cacheLogger?: boolean
+  statesHook?: StatesHook<SE>
+  successDefaultMessage?: string
+  errorDefaultMessage?: string
+  successMessageFunc?: (message: string) => void
+  errorMessageFunc?: (message: string) => void
+  unAuthorizedResponseFunc?: () => void
+  requestAdapter?: AlovaRequestAdapter<RC, RE, RH>
+  l1Cache?: AlovaGlobalCacheAdapter
+  l2Cache?: AlovaGlobalCacheAdapter
+  storageAdapter?: AlovaGlobalCacheAdapter
+}
+
+export type baseRequestOption<
+  RC extends object = FetchRequestInit,
+  RE = Response,
+  RH = Headers,
+  SE extends StatesExport<any> = StatesExport<any>,
+> = BaseRequestOption<RC, RE, RH, SE>
+
+export type RequestOption<
+  RC extends object = FetchRequestInit,
+  RE = Response,
+  RH = Headers,
+  SE extends StatesExport<any> = StatesExport<any>,
+> = BaseRequestOption<RC, RE, RH, SE>
+
+type RequestAlovaGenerics<RC extends object, RE, RH, SE extends StatesExport<any>> = {
+  Responded: unknown
+  Transformed: unknown
+  RequestConfig: RC
+  Response: RE
+  ResponseHeader: RH
+  L1Cache: AlovaGlobalCacheAdapter
+  L2Cache: AlovaGlobalCacheAdapter
+  StatesExport: SE
+}
+
+type ResolvedRequestOption<RC extends object, RE, RH, SE extends StatesExport<any>> = Required<
+  Pick<
+    BaseRequestOption<RC, RE, RH, SE>,
+    | 'baseUrl'
+    | 'statusMap'
+    | 'codeMap'
+    | 'responseCodeKey'
+    | 'responseDataKey'
+    | 'responseMessageKey'
+    | 'isWrapped'
+    | 'isTransformResponse'
+    | 'isShowSuccessMessage'
+    | 'successDefaultMessage'
+    | 'isShowErrorMessage'
+    | 'errorDefaultMessage'
+    | 'cacheLogger'
+  >
+> &
+  BaseRequestOption<RC, RE, RH, SE>
+
+const DEFAULT_SUCCESS_MESSAGE = '操作成功'
+const DEFAULT_ERROR_MESSAGE = '服务异常'
+
+const defaultRequestOption: BaseRequestOption<any, any, any, any> = {
+  baseUrl: '/',
+  timeout: undefined,
+  statusMap: {
+    success: 200,
+    unAuthorized: 401,
+  },
+  codeMap: {
+    success: [200],
+    unAuthorized: [401],
+  },
+  responseCodeKey: 'code',
+  responseDataKey: 'data',
+  responseMessageKey: 'message',
+  isWrapped: true,
+  isTransformResponse: true,
+  isShowSuccessMessage: false,
+  successDefaultMessage: DEFAULT_SUCCESS_MESSAGE,
+  isShowErrorMessage: true,
+  errorDefaultMessage: DEFAULT_ERROR_MESSAGE,
+  cacheFor: null,
+  cacheLogger: true,
+  requestAdapter: adapterFetch() as AlovaRequestAdapter<any, any, any>,
+}
+
+function getMethodMeta(method: unknown): RequestMeta {
+  const methodRecord = method as { meta?: RequestMeta; config?: { meta?: RequestMeta } } | undefined
+  return methodRecord?.config?.meta ?? methodRecord?.meta ?? {}
+}
+
+function getMetaFlag(meta: RequestMeta, key: keyof RequestMeta, fallback: boolean): boolean {
+  const value = meta[key]
+  return typeof value === 'boolean' ? value : fallback
+}
+
+function isMatchedStatus<RE>(
+  status: number,
+  matcher: StatusMatcher<RE> | undefined,
+  response: RE,
+): boolean {
+  if (matcher === undefined) return status >= 200 && status < 300
+
+  if (typeof matcher === 'function') return matcher(status, response)
+
+  return Array.isArray(matcher) ? matcher.includes(status) : matcher === status
+}
+
+function isMatchedCode(code: unknown, matcher: CodeMatcher | undefined): boolean {
+  if (!matcher?.length) return true
+
+  return matcher.some((item) => String(item) === String(code))
+}
+
+function getResponseStatus(response: unknown): number {
+  const responseRecord = response as { status?: unknown; statusCode?: unknown }
+  const status = responseRecord.statusCode ?? responseRecord.status
+  return typeof status === 'number' ? status : Number(status)
+}
+
+function getResponseMessage(data: unknown, messageKey: string, defaultMessage: string): string {
+  if (!isPlainObject(data)) return defaultMessage
+
+  const message = data[messageKey] ?? data.message ?? data.msg
+  if (typeof message === 'string') return message || defaultMessage
+  if (typeof message === 'number') return String(message)
+
+  return defaultMessage
+}
+
+function getResponseField(data: unknown, key: string): unknown {
+  return isPlainObject(data) ? data[key] : undefined
+}
+
+async function parseFetchResponse(response: {
+  status?: number
+  body?: unknown
+  headers?: Headers | Record<string, unknown>
+  clone?: () => Response
+  json?: () => Promise<unknown>
+  text?: () => Promise<string>
+}): Promise<unknown> {
+  if (response.status === 204) return undefined
+
+  const reader = typeof response.clone === 'function' ? response.clone() : response
+  const contentType = getHeaderValue(response.headers, 'content-type')
+
+  if (contentType.includes('application/json') && typeof reader.json === 'function')
+    return reader.json()
+
+  if (contentType.startsWith('text/') && typeof reader.text === 'function')
+    return tryParseJsonString(await reader.text())
+
+  if (typeof reader.json === 'function') {
+    try {
+      return await reader.json()
+    } catch {
+      // Fall through to text parsing.
+    }
+  }
+
+  if (typeof reader.text === 'function') return tryParseJsonString(await reader.text())
+
+  return undefined
+}
+
+function getHeaderValue(
+  headers: Headers | Record<string, unknown> | undefined,
+  key: string,
+): string {
+  if (!headers) return ''
+
+  if (typeof Headers !== 'undefined' && headers instanceof Headers) return headers.get(key) ?? ''
+
+  const headerRecord = headers as Record<string, unknown>
+  const value =
+    headerRecord[key] ?? headerRecord[key.toLowerCase()] ?? headerRecord[key.toUpperCase()]
+  return typeof value === 'string' ? value : ''
+}
+
+async function getResponseData(response: unknown): Promise<unknown> {
+  const responseRecord = response as {
+    body?: unknown
+    data?: unknown
+    json?: () => Promise<unknown>
+    text?: () => Promise<string>
+  }
+
+  if ('data' in responseRecord && !isReadableStream(responseRecord.body))
+    return tryParseJsonString(responseRecord.data)
+
+  if (
+    isReadableStream(responseRecord.body) ||
+    typeof responseRecord.json === 'function' ||
+    typeof responseRecord.text === 'function'
+  ) {
+    return parseFetchResponse(responseRecord)
+  }
+
+  return response
+}
+
+async function resolveHeaderValue(value: HeaderValue): Promise<string | undefined> {
+  const resolved = typeof value === 'function' ? await value() : value
+  if (resolved === null || resolved === undefined) return undefined
+  return String(resolved)
+}
+
+function setHeader(target: unknown, key: string, value: string): void {
+  if (typeof Headers !== 'undefined' && target instanceof Headers) {
+    target.set(key, value)
+    return
+  }
+
+  if (Array.isArray(target)) {
+    target.push([key, value])
+    return
+  }
+
+  ;(target as Record<string, string>)[key] = value
+}
+
+function resolveConfig<RC extends object, RE, RH, SE extends StatesExport<any>>(
+  option: BaseRequestOption<RC, RE, RH, SE>,
+): ResolvedRequestOption<RC, RE, RH, SE> {
+  return deepMergeObject(defaultRequestOption, option) as ResolvedRequestOption<RC, RE, RH, SE>
+}
+
+export function createInstance<
+  RC extends object = FetchRequestInit,
+  RE = Response,
+  RH = Headers,
+  SE extends StatesExport<any> = StatesExport<any>,
+>(option: RequestOption<RC, RE, RH, SE> = {}) {
+  const config = resolveConfig(option)
+
+  const alovaOptions: AlovaOptions<RequestAlovaGenerics<RC, RE, RH, SE>> = {
+    baseURL: config.baseUrl,
+    timeout: config.timeout,
+    cacheFor: config.cacheFor as GlobalCacheConfig<any>,
+    cacheLogger: config.cacheLogger,
+    statesHook: config.statesHook,
+    requestAdapter: config.requestAdapter!,
+    l1Cache: config.l1Cache,
+    l2Cache: config.l2Cache ?? config.storageAdapter,
+    beforeRequest: async (method) => {
+      const methodConfig = method.config as { headers?: unknown }
+      const headers = methodConfig.headers ?? {}
+      methodConfig.headers = headers
+
+      for (const [key, value] of Object.entries(config.commonHeaders?.() ?? {})) {
+        const resolvedValue = await resolveHeaderValue(value)
+        if (resolvedValue !== undefined) setHeader(headers, key, resolvedValue)
+      }
+    },
+    responded: {
+      onSuccess: async (response, method) => {
+        const meta = getMethodMeta(method)
+        const shouldTransform = getMetaFlag(meta, 'isTransformResponse', config.isTransformResponse)
+        const showSuccess = getMetaFlag(meta, 'isShowSuccessMessage', config.isShowSuccessMessage)
+        const showError = getMetaFlag(meta, 'isShowErrorMessage', config.isShowErrorMessage)
+        const isWrapped = getMetaFlag(meta, 'isWrapped', config.isWrapped)
+
+        if (!shouldTransform) return response
+
+        const status = getResponseStatus(response)
+        const data = await getResponseData(response)
+
+        if (!isMatchedStatus(status, config.statusMap.success, response)) {
+          if (isMatchedStatus(status, config.statusMap.unAuthorized, response))
+            config.unAuthorizedResponseFunc?.()
+
+          if (showError) {
+            config.errorMessageFunc?.(
+              getResponseMessage(data, config.responseMessageKey, config.errorDefaultMessage),
+            )
+          }
+          return Promise.reject(response)
+        }
+
+        if (!isWrapped) {
+          if (showSuccess) config.successMessageFunc?.(config.successDefaultMessage)
+          return data
+        }
+
+        const code = getResponseField(data, config.responseCodeKey)
+        const responseData = getResponseField(data, config.responseDataKey)
+        const responseMessage = getResponseMessage(
+          data,
+          config.responseMessageKey,
+          config.successDefaultMessage,
+        )
+
+        if (!isMatchedCode(code, config.codeMap.success)) {
+          if (isMatchedCode(code, config.codeMap.unAuthorized)) config.unAuthorizedResponseFunc?.()
+
+          if (showError) {
+            config.errorMessageFunc?.(
+              getResponseMessage(data, config.responseMessageKey, config.errorDefaultMessage),
+            )
+          }
+          return Promise.reject(response)
+        }
+
+        if (showSuccess) config.successMessageFunc?.(responseMessage)
+
+        return responseData
+      },
+      onError: (error, method) => {
+        const meta = getMethodMeta(method)
+        const showError = getMetaFlag(meta, 'isShowErrorMessage', config.isShowErrorMessage)
+
+        if (showError) {
+          config.errorMessageFunc?.(
+            error instanceof Error ? error.message : config.errorDefaultMessage,
+          )
+        }
+        return Promise.reject(error)
+      },
+    },
+  }
+
+  return createAlova(alovaOptions)
+}
+
+export type RequestInstance<
+  RC extends object = FetchRequestInit,
+  RE = Response,
+  RH = Headers,
+  SE extends StatesExport<any> = StatesExport<any>,
+> = ReturnType<typeof createInstance<RC, RE, RH, SE>>
+
+export type DualCallInstance<
+  RC extends object = FetchRequestInit,
+  RE = Response,
+  RH = Headers,
+  SE extends StatesExport<any> = StatesExport<any>,
+> = RequestInstance<RC, RE, RH, SE> &
+  ((option?: RequestOption<RC, RE, RH, SE>) => RequestInstance<RC, RE, RH, SE>)
+
+export function createDualCallInstance<
+  RC extends object = FetchRequestInit,
+  RE = Response,
+  RH = Headers,
+  SE extends StatesExport<any> = StatesExport<any>,
+>(baseConfig: BaseRequestOption<RC, RE, RH, SE>): DualCallInstance<RC, RE, RH, SE> {
+  const defaultInstance = createInstance(baseConfig)
+  const dualInstance = ((option?: RequestOption<RC, RE, RH, SE>) => {
+    if (!option) return defaultInstance
+    return createInstance(deepMergeObject(baseConfig, option))
+  }) as DualCallInstance<RC, RE, RH, SE>
+
+  Object.assign(dualInstance, defaultInstance)
+  dualInstance.Get = defaultInstance.Get.bind(defaultInstance)
+  dualInstance.Post = defaultInstance.Post.bind(defaultInstance)
+  dualInstance.Put = defaultInstance.Put.bind(defaultInstance)
+  dualInstance.Delete = defaultInstance.Delete.bind(defaultInstance)
+  dualInstance.Patch = defaultInstance.Patch.bind(defaultInstance)
+  dualInstance.Head = defaultInstance.Head.bind(defaultInstance)
+  dualInstance.Options = defaultInstance.Options.bind(defaultInstance)
+  dualInstance.Request = defaultInstance.Request.bind(defaultInstance)
+
+  return dualInstance
+}

package/template-vp-react-shadcn/src/utils/request/alova-core/utils.ts

@@ -0,0 +1,39 @@
+export function deepMergeObject<T = any>(source: T, target: Partial<T>): T {
+  const merge = (src: any, tgt: any): any => {
+    if (!isPlainObject(src) || !isPlainObject(tgt)) return tgt === undefined ? src : tgt
+
+    const result = { ...src }
+    for (const key of Object.keys(tgt)) {
+      const targetValue = tgt[key]
+      result[key] = isPlainObject(targetValue) ? merge(result[key], targetValue) : targetValue
+    }
+
+    return result
+  }
+
+  return merge(source, target)
+}
+
+export function isPlainObject(data: unknown): data is Record<string, any> {
+  return Object.prototype.toString.call(data) === '[object Object]'
+}
+
+export function isReadableStream(data: unknown): boolean {
+  if (typeof ReadableStream === 'undefined') return false
+  return data instanceof ReadableStream
+}
+
+export function tryParseJsonString(data: unknown): unknown {
+  if (typeof data !== 'string') return data
+
+  const value = data.trim()
+  if (!value) return data
+
+  if (!value.startsWith('{') && !value.startsWith('[')) return data
+
+  try {
+    return JSON.parse(value)
+  } catch {
+    return data
+  }
+}

package/template-vp-react-shadcn/src/utils/request/index.ts

@@ -0,0 +1,48 @@
+import reactHook from "alova/react";
+import { toast } from "sonner";
+
+import { navigator } from "@/router";
+import { envVariables } from "@/utils/env";
+
+import { createDualCallInstance } from "./alova-core";
+
+function normalizeBaseUrl(apiAffix?: string) {
+  if (!apiAffix) return "/";
+  if (/^https?:\/\//.test(apiAffix) || apiAffix.startsWith("/")) {
+    return apiAffix;
+  }
+
+  return `/${apiAffix}`;
+}
+
+function getBaseConfig(): Parameters<typeof createDualCallInstance>[0] {
+  return {
+    baseUrl: normalizeBaseUrl(envVariables.API_AFFIX),
+    statusMap: {
+      success: [200, 201, 204],
+      unAuthorized: 401,
+    },
+    codeMap: {
+      success: [200],
+      unAuthorized: [401],
+    },
+    responseDataKey: "data",
+    responseMessageKey: "msg",
+    commonHeaders: () => ({}),
+    successMessageFunc: (msg) => {
+      toast.success(msg);
+    },
+    errorMessageFunc: (msg) => {
+      toast.error(msg);
+    },
+    unAuthorizedResponseFunc: () => {
+      navigator("/login");
+      toast.error("登录过期或未登录");
+    },
+    statesHook: reactHook,
+  };
+}
+
+const alovaRequest = createDualCallInstance(getBaseConfig());
+
+export default alovaRequest;

package/template-vp-react-shadcn/src/utils/request/readme.md

@@ -0,0 +1,176 @@
+# request 使用说明
+
+`src/utils/request/index.ts` 导出的是项目统一的 alova 请求实例，业务接口建议统一放在 `src/api` 里封装，页面和组件不要直接散写请求配置。
+
+## 基础用法
+
+请求方法会创建 alova `Method` 实例，不会在创建时立刻发送请求。可以在组件中交给 `useRequest`，也可以在普通函数里直接 `await`。
+
+```ts
+import alovaRequest from "@/utils/request";
+
+interface DramaItem {
+  id: number;
+  title: string;
+}
+
+interface DramaListParams {
+  page: number;
+  pageSize: number;
+}
+
+export const getDramaList = (params: DramaListParams) => {
+  return alovaRequest.Get<DramaItem[]>("/drama/list", { params });
+};
+```
+
+组件中使用：
+
+```tsx
+import { useRequest } from "alova/client";
+
+import { getDramaList } from "@/api";
+
+export function DramaList() {
+  const { data, loading, error } = useRequest(getDramaList({ page: 1, pageSize: 20 }), {
+    initialData: [],
+  });
+
+  // ...
+}
+```
+
+普通异步函数中使用：
+
+```ts
+const list = await getDramaList({ page: 1, pageSize: 20 });
+```
+
+## 请求参数
+
+GET 查询参数放在第二个参数的 `params` 里：
+
+```ts
+alovaRequest.Get<UserInfo>("/user/detail", {
+  params: {
+    id: 1,
+  },
+});
+```
+
+POST、PUT、PATCH、DELETE 的 body 放在第二个参数，配置放在第三个参数：
+
+```ts
+alovaRequest.Post<CreateUserResult>("/user/create", {
+  name: "Tom",
+});
+
+alovaRequest.Post<CreateUserResult>(
+  "/user/create",
+  { name: "Tom" },
+  {
+    meta: {
+      isShowSuccessMessage: true,
+    },
+  },
+);
+```
+
+## 返回结构
+
+默认按下面这种后端格式处理：
+
+```ts
+interface ApiResponse<T> {
+  code: number;
+  data: T;
+  msg: string;
+}
+```
+
+默认规则：
+
+- HTTP 状态码 `200`、`201`、`204` 视为成功。
+- 业务 `code` 在 `codeMap.success` 中视为成功，当前默认是 `[200]`。
+- 成功后返回 `data` 字段，所以 `alovaRequest.Get<User[]>` 的最终数据类型就是 `User[]`。
+- 如果响应不是普通对象，会直接返回解析后的原始数据，比如字符串。
+
+## 提示开关
+
+单次请求可以通过 `meta` 控制是否转换响应、是否显示成功提示、是否显示错误提示。
+
+```ts
+alovaRequest.Post(
+  "/user/update",
+  { id: 1, name: "Tom" },
+  {
+    meta: {
+      isShowSuccessMessage: true,
+      isShowErrorMessage: false,
+    },
+  },
+);
+```
+
+也可以创建一个带临时配置的请求实例：
+
+```ts
+const silentRequest = alovaRequest({
+  isShowErrorMessage: false,
+});
+
+silentRequest.Get<UserInfo>("/user/detail", {
+  params: { id: 1 },
+});
+```
+
+## 原始响应
+
+下载文件、读取响应头、或不想走业务 `code/data/msg` 转换时，关闭 `isTransformResponse`。
+
+```ts
+const downloadFile = () => {
+  return alovaRequest.Get<Response>("/file/download", {
+    meta: {
+      isTransformResponse: false,
+    },
+  });
+};
+
+const response = await downloadFile();
+const blob = await response.blob();
+```
+
+## 错误处理
+
+HTTP 状态码错误、业务 `code` 错误都会抛出 `RequestError`，alova hook 会进入 `error` 分支。
+
+```ts
+import { RequestError } from "@/utils/request/alova-core";
+
+try {
+  await getDramaList({ page: 1, pageSize: 20 });
+} catch (error) {
+  if (error instanceof RequestError) {
+    console.log(error.status, error.code, error.message);
+  }
+}
+```
+
+`401` 会自动执行 `unAuthorizedResponseFunc`，当前行为是跳转到 `/login` 并提示登录过期。
+
+## 环境变量
+
+请求基础路径来自 `VITE_API_AFFIX`：
+
+```env
+VITE_API_AFFIX=/api
+```
+
+没有配置时会使用 `/`，避免出现 `/undefined`。
+
+## 注意事项
+
+- 业务接口优先写成函数并标注返回泛型，例如 `alovaRequest.Get<UserInfo>()`，组件里的 `useRequest` 会自动推断数据类型。
+- 不要把 GET 查询参数直接作为第二个裸对象传入，第二个参数是配置对象，查询参数必须放到 `{ params }`。
+- 需要局部关闭错误提示时优先用 `meta.isShowErrorMessage`，不要在组件里重复 toast。