174 lines
5.2 KiB
Markdown
174 lines
5.2 KiB
Markdown
# 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 自动化构建与发布
|