✨ feat: 增加部分公共函数

Author: OFreshman

README.md

@@ -22,6 +22,8 @@ ui-utils-kit 是一个高效的偏业务前端工具函数库。
 - **海报制作**
   将 DOM 元素转换为图片（canvas），支持自动下载或返回 Blob 格式数据。
   > 针对跨域图片问题，内置 `html2canvas` proxy 解决方案。
+- **业务工具类函数**
+  提供一些常用的业务工具函数，如 JSON 安全解析、敏感信息脱敏等。
 
 ---
 
@@ -45,12 +47,14 @@ ui-utils-kit 的工具函数分为三大类：`tree`、`business`、`common`，
 **方式一：**
 ```javascript
 import { tree } from "ui-utils-kit";
+
 const result = tree.buildTree(nodes);
 ```
 
 **方式二：**
 ```javascript
 import { buildTree } from "ui-utils-kit";
+
 const result = buildTree(nodes);
 ```
 
@@ -83,6 +87,9 @@ const result = buildTree(nodes);
 
 **`tree.treeToArr`** 将树形数据转换为扁平化数组，便于遍历与处理。
 
+- **参数：**
+  - `tree` (`TreeNode`)：包含 `id` 与 `name`、`children`的树形结构数据。
+  - `node` (`TreeNode`)：包含 `id` 与 `pid` 的节点数据。
 - **示例：**
   ```typescript
   import { treeToArr } from 'ui-utils-kit';
@@ -96,6 +103,8 @@ const result = buildTree(nodes);
 
 **`tree.updateTreeCheckStatus`** 更新树中节点的选中状态（含子节点与父节点联动）。
 
+- **参数：**
+  - `tree` (`TreeNode`)：包含 `id` 与 `name`、`children`的树形结构数据。
 - **示例：**
   ```typescript
   import { updateTreeCheckStatus } from 'ui-utils-kit';
@@ -172,7 +181,97 @@ const result = buildTree(nodes);
 
 ## 🎨 公共通用函数 (common)
 
-> 当前暂无公共通用函数，后续版本将持续更新。
+### 1. safeJsonParse<T>(jsonString: string, defaultValue: T): [Error \| null, T]
+
+**功能描述：** 安全地解析 JSON 字符串，如果解析出错则返回默认值和错误对象。
+
+**参数**
+- `jsonString: string` — 要解析的 JSON 格式字符串。
+
+- `defaultValue: T` — 当解析失败时返回的默认值，类型与期待的解析结果相同。
+
+**返回值**
+  `[Error | null, T]` — 一个元组：
+
+- 示例
+```typescript
+import { safeJsonParse } from 'ui-utils-kit';
+
+const [err, data] = safeJsonParse('{"foo": 42}', { foo: 0 });
+if (err) {
+  // 处理解析错误
+} else {
+  console.log(data.foo); // 42
+}
+```
+### 2. desensitize(value: string, type: "mobile" | "idcard"): string
+**功能描述**：对敏感信息（手机号或身份证号）进行脱敏处理，隐藏中间部分。
+
+**参数**
+- `value: string` — 原始字符串，如手机号或身份证号。
+- `type: "mobile" \| "idcard"` — 数据类型，"mobile" 脱敏手机号，"idcard" 脱敏身份证号。
+
+**返回值**
+string — 脱敏后字符串，如果输入非字符串则返回空字符串。
+
+- 示例
+```typescript
+import { desensitize } from 'ui-utils-kit';
+
+console.log(desensitize('13812345678', 'mobile'));  // 输出：138****5678
+console.log(desensitize('110105199001011234', 'idcard')); // 输出：110105********1234
+```
+
+### 3. Mutex 类
+功能描述：模拟互斥锁机制，用于控制异步操作对共享资源的访问，确保同一时刻只有一个操作进入临界区。
+> ##### 以下是一些应用场景
+> - 防止按钮重复点击：避免用户多次点击同一按钮导致重复网络请求或状态混乱
+> - 强制 API 调用顺序：确保一组异步接口按预期顺序依次执行，防止乱序带来的逻辑错误
+> - 多标签页 localStorage 访问：在多个浏览器标签或窗口同时操作同一 localStorage 时，避免数据竞争和丢失
+> - 分片上传（Chunked Upload）：在大文件上传时，按顺序上传每个分片，确保断点续传或失败重试时不会错乱
+> - Web Worker 任务同步：在主线程与 Worker 线程之间同步访问共享内存（如 SharedArrayBuffer ）时，保证原子性
+
+
+- 示例
+
+```typescript
+<template>
+  <view>
+    <button @click="onSubmit" :disabled="isSubmitting">
+      {{ isSubmitting ? '提交中...' : '提交' }}
+    </button>
+  </view>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue'
+import Mutex from '@/utils/Mutex'   // 假设 Mutex 存放在 utils 目录
+
+// 状态变量，无需在 setup 中 return，自动暴露给模板使用
+const isSubmitting = ref(false)
+// 创建一个互斥锁实例
+const submitMutex = new Mutex()
+
+// 点击处理函数
+const onSubmit = async () => {
+  // 获取锁：若已有操作在进行，则挂起后续调用
+  await submitMutex.lock()
+  try {
+    isSubmitting.value = true
+    // 模拟网络请求
+    await new Promise<void>(resolve => setTimeout(resolve, 1500))
+    uni.showToast({ title: '提交成功' })
+  } catch (err: any) {
+    uni.showModal({ title: '错误', content: err.message })
+  } finally {
+    isSubmitting.value = false
+    // 释放锁，允许下一次点击
+    submitMutex.unlock()
+  }
+}
+</script>
+
+```
 
 ---
 

packages/core/README.md

@@ -172,7 +172,89 @@ const result = buildTree(nodes);
 
 ## 🎨 公共通用函数 (common)
 
-> 当前暂无公共通用函数，后续版本将持续更新。
+### 1. safeJsonParse<T>(jsonString: string, defaultValue: T): [Error \| null, T]
+
+**功能描述：**
+安全地解析 JSON 字符串，如果解析出错则返回默认值和错误对象。
+
+```typescript
+export function safeJsonParse<T>(jsonString: string, defaultValue: T): [Error | null, T] {
+  try {
+    const parsed = JSON.parse(jsonString) as T;
+    return [null, parsed];
+  } catch (error) {
+    console.error("JSON 解析错误:", error);
+    return [error instanceof Error ? error : new Error(String(error)), defaultValue];
+  }
+}
+```
+**参数**
+- `jsonString: string` — 要解析的 JSON 格式字符串。
+
+- `defaultValue: T` — 当解析失败时返回的默认值，类型与期待的解析结果相同。
+
+**返回值**
+`[Error | null, T]` — 一个元组：
+
+- 示例
+```typescript
+const [err, data] = safeJsonParse('{"foo": 42}', { foo: 0 });
+if (err) {
+  // 处理解析错误
+} else {
+  console.log(data.foo); // 42
+}
+```
+### 2. desensitize(value: string, type: "mobile" | "idcard"): string
+功能描述：对敏感信息（手机号或身份证号）进行脱敏处理，隐藏中间部分。
+
+**参数**
+- `value: string` — 原始字符串，如手机号或身份证号。
+
+- `type: "mobile" \| "idcard"` — 数据类型，"mobile" 脱敏手机号，"idcard" 脱敏身份证号。
+
+**返回值**
+string — 脱敏后字符串，如果输入非字符串则返回空字符串。
+- 示例
+```typescript
+console.log(desensitize('13812345678', 'mobile'));  // 输出：138****5678
+console.log(desensitize('110105199001011234', 'idcard')); // 输出：110105********1234
+```
+
+### 3. Mutex 类
+功能描述：模拟互斥锁机制，用于控制异步操作对共享资源的访问，确保同一时刻只有一个操作进入临界区。
+- 示例
+
+```typescript
+import Mutex from './Mutex';
+
+const mutex = new Mutex();
+
+// 初始状态
+console.log('初始状态', mutex.isLocked(), mutex.queueLength()); // 初始状态 false 0
+
+// 获取锁
+await mutex.lock();
+console.log('获取锁后', mutex.isLocked(), mutex.queueLength()); // 获取锁后 true 0
+
+// 第二次请求锁，不会立即获取，加入队列
+const pending = mutex.lock().then(() => {
+  console.log('第二次获取锁', mutex.isLocked(), mutex.queueLength());
+});
+console.log('请求队列长度', mutex.queueLength()); // 请求队列长度 1
+
+// 执行临界区代码
+// ...
+
+// 释放锁，自动唤醒队列中的下一个请求
+mutex.unlock();
+console.log('释放锁后', mutex.isLocked(), mutex.queueLength()); // 释放锁后 true 0
+
+await pending; // 等待第二个请求获取锁
+// 最后释放锁
+mutex.unlock();
+console.log('全部完成', mutex.isLocked(), mutex.queueLength()); // 全部完成 false 0
+```
 
 ---
 

packages/core/src/common.ts

@@ -2,4 +2,118 @@
  * =====================
  * =======公共函数=======
  * =====================
- */
+ */
+
+
+/**
+ * 安全地解析 JSON 字符串。
+ *
+ * @param jsonString - 要解析的 JSON 字符串。
+ * @param defaultValue - 解析失败时返回的默认值。
+ * @returns 一个元组，第一个元素为错误对象（若无错误则为 null），第二个元素为解析结果或默认值。
+ */
+export function safeJsonParse<T>(jsonString: string, defaultValue: T): [Error | null, T] {
+  try {
+    const parsed = JSON.parse(jsonString) as T;
+    return [null, parsed];
+  } catch (error) {
+    console.error("JSON 解析错误:", error);
+    return [error instanceof Error ? error : new Error(String(error)), defaultValue];
+  }
+}
+
+/**
+ * 对敏感信息进行脱敏处理
+ *
+ * @param value - 原始字符串（如手机号、身份证号）
+ * @param type - 数据类型，可选值为 "mobile"（手机号）或 "idcard"（身份证号）
+ * @returns 脱敏后的字符串
+ */
+export function desensitize(value: string, type: "mobile" | "idcard"): string {
+  if (typeof value !== "string") {
+    return "";
+  }
+
+  switch (type) {
+    case "mobile":
+      // 手机号脱敏：保留前3位和后4位，中间4位替换为星号
+      // 示例：13812345678 => 138****5678
+      return value.replace(/^(\d{3})\d{4}(\d{4})$/, "$1****$2");
+
+    case "idcard":
+      // 身份证号脱敏：保留前6位和后4位，中间位数替换为星号
+      // 示例：110105199001011234 => 110105********1234
+      return value.replace(/^(\d{6})\d+(\d{4})$/, (_, p1, p2) => {
+        const middleLength = value.length - p1.length - p2.length;
+        const masked = "*".repeat(middleLength);
+        return `${p1}${masked}${p2}`;
+      });
+
+    default:
+      return value;
+  }
+}
+
+/**
+ * 模拟互斥锁（Mutex）机制，用于控制异步操作对共享资源的访问
+ */
+export default class Mutex {
+
+  /**
+   * 锁的状态：true 表示已锁定，false 表示未锁定
+   */
+  #locked = false;
+
+  /**
+   * 等待获取锁的 Promise resolve 函数队列
+   */
+  #queue: Array<() => void> = [];
+
+  /**
+   * 获取锁。如果当前已锁定，则将请求加入队列，等待解锁后依次获取。
+   * @returns Promise<void> - 当获取到锁时，Promise 被 resolve。
+   */
+  public lock(): Promise<void> {
+    if (this.#locked) {
+      // 已锁定，将请求加入队列
+      return new Promise((resolve) => {
+        this.#queue.push(resolve);
+      });
+    }
+
+    // 未锁定，立即获取锁
+    this.#locked = true;
+    return Promise.resolve();
+  }
+
+  /**
+   * 释放锁。如果有等待队列，则唤醒队列中的下一个请求；否则将锁状态设为未锁定。
+   */
+  public unlock(): void {
+    if (this.#queue.length > 0) {
+      // 唤醒队列中的下一个请求
+      const nextResolve = this.#queue.shift();
+      nextResolve?.();
+    } else {
+      // 没有等待请求，释放锁
+      this.#locked = false;
+    }
+  }
+
+  /**
+   * 查询当前锁的状态
+   * @returns boolean - true 表示已锁定，false 表示未锁定
+   */
+  public isLocked(): boolean {
+    return this.#locked;
+  }
+
+  /**
+   * 获取当前等待队列的长度
+   * @returns number - 等待队列中的请求数量
+   */
+  public queueLength(): number {
+    return this.#queue.length;
+  }
+
+}