@ruan-cat/utils 4.3.1 → 4.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ruan-cat/utils",
-  "version": "4.3.1",
+  "version": "4.4.0",
   "description": "阮喵喵工具集合。默认提供js文件，也直接提供ts文件。",
   "type": "module",
   "main": "./src/index.ts",
@@ -32,6 +32,7 @@
     "./unplugin-vue-router": "./src/unplugin-vue-router/index.ts",
     "./vite-plugin-autogeneration-import-file": "./src/vite-plugin-autogeneration-import-file/index.ts",
     "./vueuse": "./src/vueuse/index.ts",
+    "./vueuse/*": "./src/vueuse/*",
     "./src/*": "./src/*",
     "./dist/*": "./dist/*"
   },
@@ -78,13 +79,13 @@
     "typedoc-plugin-frontmatter": "^1.3.0",
     "typedoc-plugin-markdown": "^4.5.0",
     "typescript": "^5.8.2",
-    "unplugin-vue-router": "^0.11.2",
+    "unplugin-vue-router": "^0.12.0",
     "vite-plugin-autogeneration-import-file": "^3.0.0",
     "vitepress": "^1.6.3"
   },
   "peerDependencies": {
     "typescript": "5.7.3",
-    "unplugin-vue-router": "^0.10.0",
+    "unplugin-vue-router": "^0.12.0",
     "vite-plugin-autogeneration-import-file": ">=3"
   },
   "peerDependenciesMeta": {

package/src/vueuse/index.ts

@@ -1 +1,2 @@
 export * from "./useAxios/index";
+export * from "./useAxios-for-01s/index";

package/src/vueuse/useAxios-for-01s/index.ts

@@ -0,0 +1,4 @@
+export * from "./types/JsonVO";
+export * from "./types/PageDTO";
+export * from "./tools";
+export * from "./main";

package/src/vueuse/useAxios-for-01s/main.ts

@@ -0,0 +1,94 @@
+import type { KeyAxiosRequestConfig, UseAxiosWrapperParams } from "../useAxios/index";
+import { useAxiosWrapper } from "../useAxios/index";
+
+import type { UseAxiosOptionsBase } from "@vueuse/integrations/useAxios";
+import type { PartialPick } from "type-plus";
+import type { AxiosInstance } from "axios";
+import axios from "axios";
+import type { JsonVO } from "./types/JsonVO";
+
+import type { AxiosRequestConfigBaseKey, HttpParamWay } from "./tools.ts";
+import {
+	createDefaultUseAxiosOptions,
+	setHeaders,
+	UpType,
+	setDefaultUseAxiosOptions,
+	setDataByHttpParamWay,
+} from "./tools";
+
+/**
+ * 内部用的 axios 实例
+ * @description
+ * 主动声明类型 用于约束
+ * @private
+ */
+let innerAxiosInstance: AxiosInstance = axios;
+
+/**
+ * 定义具体的 AxiosInstance 实例
+ * @description
+ * 让外部设置一次内部的默认请求实例
+ */
+export function defineAxiosInstance(axiosInstance: AxiosInstance) {
+	innerAxiosInstance = axiosInstance;
+}
+
+export type ParamsPathKey = AxiosRequestConfigBaseKey | "url";
+export type ParamsQueryKey = AxiosRequestConfigBaseKey | "data";
+export type ParamsBodyKey = AxiosRequestConfigBaseKey | "data";
+
+type UseAxiosWrapperUseKey<T extends HttpParamWay, K extends KeyAxiosRequestConfig> =
+	//
+	T extends HttpParamWay ? Exclude<K, AxiosRequestConfigBaseKey> : never;
+
+interface _Params<K extends KeyAxiosRequestConfig, T = any, D = any>
+	extends UseAxiosWrapperParams<K, T, UseAxiosOptionsBase<JsonVO<T>>, D> {
+	httpParamWay: HttpParamWay;
+	upType?: UpType;
+}
+
+/** 建议封装接口请求函数不传递 useAxios 的 instance 和 options 参数 */
+type Params<K extends KeyAxiosRequestConfig, T = any, D = any> = PartialPick<_Params<K, T, D>, "instance" | "options">;
+
+/**
+ * 项目内用的接口请求
+ * @description
+ * 01s项目内常用的接口请求
+ * @version 2
+ */
+export function useRequestIn01s<
+	K extends KeyAxiosRequestConfig,
+	T = any,
+	D = any,
+	HttpParamWayTemp extends HttpParamWay = Params<K>["httpParamWay"],
+>(
+	params: Params<
+		//
+		UseAxiosWrapperUseKey<HttpParamWayTemp, K>,
+		T,
+		D
+	>,
+) {
+	const {
+		config,
+		options = createDefaultUseAxiosOptions(),
+		instance = innerAxiosInstance,
+		httpParamWay,
+		upType,
+		url,
+	} = params;
+	setHeaders(config, upType);
+	setDefaultUseAxiosOptions(options);
+	setDataByHttpParamWay({
+		httpParamWay,
+		config,
+	});
+	// console.log(" instance  ?", instance.defaults.baseURL);
+	return useAxiosWrapper<
+		//
+		UseAxiosWrapperUseKey<HttpParamWayTemp, K>,
+		JsonVO<T>,
+		UseAxiosOptionsBase<JsonVO<T>>,
+		D
+	>({ config, instance, options, url });
+}

package/src/vueuse/useAxios-for-01s/tools.ts

@@ -0,0 +1,185 @@
+import type { UseAxiosOptionsBase } from "@vueuse/integrations/useAxios";
+import type { AxiosRequestConfig } from "axios";
+
+import { isNil, merge } from "lodash-es";
+import qs from "qs";
+
+import type { JsonVO } from "./types/JsonVO";
+import { isConditionsSome } from "../../index";
+
+/**
+ * http的接口传参方式
+ * @description
+ * 用于控制接口请求时的参数传递方式
+ * @see https://www.cnblogs.com/jinyuanya/p/13934722.html
+ */
+export type HttpParamWay =
+	// 路径传参
+	| "path"
+	// query传参
+	| "query"
+	// body传参
+	| "body";
+
+/**
+ * 基础的 axios.config 必填项字段
+ * @description
+ * 用于说明axios配置必须传递method字段
+ * @version 2
+ */
+export type AxiosRequestConfigBaseKey = "method";
+
+/**
+ * 数据上传数据类型
+ * @description
+ * 一个标记工具，用来控制上传数据的格式
+ *
+ * 目前没有发现axios有类似的上传类型声明
+ */
+export enum UpType {
+	/** 表单类型 */
+	form = 0,
+
+	/** json类型 */
+	json = 1,
+
+	/** 文件类型 */
+	file = 3,
+
+	/** 文件流类型 */
+	stream = 4,
+}
+
+/**
+ * HTTP状态码
+ * @description
+ * 待优化 未来可以直接复用axios内提供的值 不需要额外地封装工具
+ */
+export enum HttpCode {
+	/** 暂未登录或TOKEN已经过期 */
+	UNAUTHORIZED = 401,
+	/** 没有相关权限 */
+	FORBIDDEN = 403,
+	/** 访问页面未找到 */
+	NOT_FOUND = 404,
+	/** 服务器错误 */
+	SERVER_ERROR = 9994,
+	/** 上传参数异常 */
+	PARAMS_INVALID = 9995,
+	/** ContentType错误 */
+	CONTENT_TYPE_ERR = 9996,
+	/** 功能尚未实现 */
+	API_UN_IMPL = 9997,
+	/** 服务器繁忙 */
+	SERVER_BUSY = 9998,
+	/** 操作失败 */
+	FAIL = 9999,
+	/** 操作成功 */
+	SUCCESS = 10000,
+}
+
+/**
+ * 上传类型-请求体类型 枚举
+ * @description
+ * 待优化 未来可以直接复用axios内提供的值 不需要额外地封装工具
+ */
+export enum MapContentTypeUpType {
+	"application/json;charset=UTF-8" = UpType.json,
+	"multipart/form-data" = UpType.file,
+	"application/octet-stream" = UpType.stream,
+	"application/x-www-form-urlencoded;charset=UTF-8" = UpType.form,
+}
+
+/** @private */
+type ContentType = keyof typeof MapContentTypeUpType;
+
+/**
+ * 根据数据上传类型 重设请求头类型
+ * @description
+ * 不同的数据上传数据类型 要使用不同的接口请求方式
+ *
+ * 不再有返回值
+ * @version 2
+ */
+export function setHeaders(config: AxiosRequestConfig, upType: UpType = UpType.json) {
+	const contentType = MapContentTypeUpType[upType] as ContentType;
+	if (contentType) {
+		config = merge<AxiosRequestConfig, AxiosRequestConfig>(config, {
+			headers: {
+				"Content-Type": contentType,
+			},
+		});
+	}
+	if (!isNil(config.data) && upType === UpType.form) {
+		config.data = qs.stringify(config.data, { arrayFormat: "repeat" });
+	}
+	if (!isNil(config.data) && upType === UpType.file) {
+		const formData = new FormData();
+		for (const key in config.data) {
+			formData.append(key, config.data[key]);
+		}
+		config.data = formData;
+	}
+}
+
+/**
+ * 提供默认返回值的包装类型
+ * @description
+ * 预期会在每一个接口的包装函数内使用 用来定义 useAxios 的options参数
+ *
+ * 该类型应该成为高频使用的工具类型
+ *
+ * 被设计成一个简单的类型 而不是interface接口
+ * @version 2
+ */
+export type UseAxiosOptionsJsonVO<T = any> = UseAxiosOptionsBase<JsonVO<T>>;
+
+/** useAxios的选项配置 且默认带有immediate属性 不立刻执行 */
+export interface UseAxiosOptionsImmediate<T = any> extends UseAxiosOptionsJsonVO<T> {
+	/**
+	 * @default false
+	 * @description
+	 * 默认为 false 不立刻执行
+	 */
+	immediate: boolean;
+}
+
+/** 生成默认的选项配置 */
+export function createDefaultUseAxiosOptions<T = any>(): UseAxiosOptionsImmediate<T> {
+	return {
+		immediate: false,
+	};
+}
+
+/**
+ * 设置默认的 useAxiosOptions 参数值
+ * @description
+ * 设置 immediate 的值
+ *
+ * 如果外部没有传递 immediate 属性，那么就使用默认的值
+ *
+ * 每个业务接口都会传递 options 值，本函数用来完成默认的参数补全。
+ */
+export function setDefaultUseAxiosOptions<T>(options: UseAxiosOptionsBase<T>) {
+	const _options = createDefaultUseAxiosOptions();
+	options.immediate = options?.immediate ?? _options.immediate;
+}
+
+/** @private */
+interface SetDataByHttpParamWayParams {
+	httpParamWay: HttpParamWay;
+	config: AxiosRequestConfig;
+}
+export function setDataByHttpParamWay(params: SetDataByHttpParamWayParams) {
+	const { httpParamWay, config } = params;
+	if (
+		isConditionsSome([
+			//
+			() => config.method === "GET",
+			() => config.method === "get",
+			() => httpParamWay === "query",
+		])
+	) {
+		config.params = config.data;
+	}
+}

package/src/vueuse/useAxios-for-01s/types/JsonVO.ts

@@ -0,0 +1,18 @@
+/**
+ * 前后端数据对接数据对象
+ * @description
+ * 后端 JsonVO 泛型类的前端翻译
+ *
+ * `01s` 项目统一的数据返回格式
+ */
+export interface JsonVO<T> {
+	/** 状态码 */
+	code: number;
+
+	/** 提示消息 */
+
+	message: string;
+
+	/** 数据对象 */
+	data: T;
+}

package/src/vueuse/useAxios-for-01s/types/PageDTO.ts

@@ -0,0 +1,33 @@
+/**
+ * 数据分页的返回对象
+ * @description
+ *
+ * `01s` 项目统一的数据返回格式
+ */
+export interface PageDTO<T> {
+	/**
+	 * 当前页码
+	 */
+	pageIndex: number;
+
+	/**
+	 * 每页显示最大数据条数
+	 */
+
+	pageSize: number;
+
+	/**
+	 * 总条数
+	 */
+	total: number;
+
+	/**
+	 * 总页数
+	 */
+	pages: number;
+
+	/**
+	 * 当前页数据列表
+	 */
+	rows: T[];
+}