# Windychen Utils 项目开发记录

**日期**: 2026-05-25  
**项目**: windychen-untils (v1.0.0)  
**类型**: 轻量级 JavaScript 工具库

---

## 一、已完成功能模块

### 1. Object 扩展 (`object.js`)

| 方法 | 功能 | 特性 |
|------|------|------|
| `getPro(path, defaultValue?)` | 安全获取嵌套属性 | 支持点分隔路径、特殊键名（含`.`）、混合路径、默认值回退 |
| `setPro(path, value)` | 设置嵌套路径值 | 自动创建中间对象，支持特殊键名 |

**路径格式示例：**
```javascript
obj.getPro('a.b.c');           // 普通点分隔
obj.getPro("['x.y'].z");       // 特殊键名
obj.getPro("['a.b'].c['d']"); // 混合嵌套
```

**优化点：**
- 提取 `_parsePath()` 公共函数消除重复代码
- 使用正则 `\[['"]([^'"]+)['"]\]|[^.\[\]]+` 统一解析所有 key 格式
- 最终代码量：26 行（原 47 行，精简 45%）

---

### 2. Array 扩展 (`array.js`)

6 个增强方法，均支持三种调用方式：

| 方法 | 对应原生 | 说明 |
|------|---------|------|
| `findPro(a, b?)` | find() | 查找首个匹配项 |
| `filterPro(a, b?)` | filter() | 过滤所有匹配项 |
| `findIndexPro(a, b?)` | findIndex() | 返回索引 |
| `findLastPro(a, b?)` | findLast() | 从末尾查找 |
| **somePro(a, b?)** | some() | 任一满足 |
| **everyPro(a, b?)** | every() | 全部满足 |

**三种调用模式：**
```javascript
// 模式1: 回调函数
arr.findPro(item => item.id > 1);

// 模式2: 单值精确匹配
['aa','bb'].findPro('bb');

// 模式3: key-value 匹配（支持 getPro 嵌套路径）
arr.findPro('user.info.name', 'Alice');
```

**优化点：**
- 提取 `_resolveMatcher()` 统一参数判断逻辑
- 循环生成 6 个 Pro 方法，零重复代码
- key-value 模式接入 `getPro` 支持深层路径访问
- 处理 null/undefined 边界（`item != null && ...`）
- 最终代码量：12 行（原 64 行，精简 81%）

---

### 3. Storage 存储 (`storage.js`)

浏览器环境专用：

| 类 | 存储后端 | 特点 |
|----|---------|------|
| `IDBStorage` | IndexedDB | 大容量存储 |
| `ILocalStorage` | localStorage + Map 缓存 | 兼容性好，启动时全量加载 |

**自动选择策略：**
```javascript
window.indexedDB ? IDBStorage : (localStorage ? ILocalStorage : null)
```

**API：**
- `storage.set(key, value)` → Promise
- `storage.get(key, initValue)` → Promise

---

## 二、工程化配置

### 构建系统 (Webpack)

**配置文件**: `webpack.config.js`（单文件，多模式）

```bash
npm run build       # 全部 (CJS + ESM + UMD)
npm run build:cjs   # CommonJS 格式
npm run build:esm   # ES Module 格式  
npm run build:umd   # UMD 浏览器格式
npm run dev         # 开发模式
```

**输出产物：**

| 格式 | 文件 | 入口字段 |
|------|------|---------|
| CJS | dist/windychen-utils.cjs.js | main |
| ESM | dist/windychen-utils.esm.js | module |
| UMD | dist/windychen-utils.js | browser |

**演进过程：**
1. 初始创建 3 个独立 webpack 配置文件
2. 发现 `.esm.js` 后缀被 webpack-cli 误识别为 esm 加载器
3. 重命名解决加载异常
4. 发现 `experiments` 应在顶层而非 output 内
5. **最终收敛为单文件 + --env 参数方案**

---

### 项目结构

```
e:\project\utils\
├── index.js              # 统一入口，聚合各模块
├── object.js             # Object 原型扩展 (getPro/setPro)
├── array.js              # Array 原型扩展 (6个Pro方法)
├── storage.js            # 浏览器存储封装 (IndexedDB/LS)
├── webpack.config.js     # 打包配置 (单文件多模式)
├── package.json          # 项目元信息 & 脚本
├── .gitignore            # Git 忽略规则
├── test.js               # Node/Bun 端测试
├── index.html            # 浏览器端测试页面
├── README.md             # 项目文档
└── dist/                 # 构建产物输出目录
```

---

## 三、测试体系

### Node.js / Bun 测试 (`test.js`)
- 直接 require 源码运行
- 彩色终端输出 (✓/✗)
- 覆盖全部 API 的核心场景
- 失败时 process.exit(1)
- 命令: `npm test`

### 浏览器测试 (`index.html`)
- 引入 dist/windychen-utils.js (UMD)
- 深色主题 UI 展示结果
- 绿色通过 / 红色失败
- 命令: `npm run build:umd && open index.html`

**已修复 Bug：**
- array.js 中 `_resolveMatcher` 未处理 item 为 null/undefined 导致的 TypeError
- 修复: `item != null && item.getPro(...)`

---

## 四、关键决策记录

1. **Prototype 扩展方式**: 直接扩展 Object/Array 原型，使用时无需导入，全局可用
2. **路径解析设计**: 正则统一处理普通键和特殊键（含点号），避免分支逻辑
3. **Array Pro 方法设计**: 参数重载（function/string+value/value）覆盖常见使用场景
4. **Storage 自动降级**: IndexedDB → localStorage → null，最大化兼容性
5. **Webpack 单配置**: 通过 --env format 参数控制输出，避免维护多个配置文件

---

## 五、待改进方向

- [ ] 添加单元测试框架（如 Jest/Vitest）
- [ ] 支持 TypeScript 类型声明 (.d.ts)
- [ ] Storage 模块添加 delete/clear 方法
- [ ] 考虑添加更多工具方法（日期、字符串、数字等）
- [ ] CI/CD 自动化构建与发布