chanjs 2.7.7 → 2.7.10

package/doc/Common.md

@@ -1,638 +0,0 @@
-# Common 公共工具模块
-
-## 概述
-
-`common` 模块是 chanjs 框架的公共工具集合，提供响应格式化、数据解析、HTML 处理、文件操作等常用功能。
-
-## 引入方式
-
-```javascript
-import { helper } from 'chanjs';
-
-// 或从子模块精确引用
-import { getIp } from 'chanjs/utils/ip.js';
-```
-
-## 核心工具
-
-### 1. 响应格式化
-
-#### success - 成功响应
-
-```javascript
-helper.success({ data, msg })
-```
-
-**参数**
-
-| 参数 | 类型 | 必填 | 默认值 | 说明 |
-|------|------|------|--------|------|
-| data | any | 否 | {} | 响应数据 |
-| msg | string | 否 | "操作成功" | 提示信息 |
-
-**示例**
-
-```javascript
-import { helper } from 'chanjs';
-
-const response = helper.success({ 
-  data: { id: 1, name: '张三' },
-  msg: '查询成功'
-});
-// { success: true, code: 0, msg: '查询成功', data: {...} }
-```
-
-#### fail - 失败响应
-
-```javascript
-helper.fail({ msg, code, data })
-```
-
-**参数**
-
-| 参数 | 类型 | 必填 | 默认值 | 说明 |
-|------|------|------|--------|------|
-| msg | string | 否 | "操作失败" | 错误提示 |
-| code | number | 否 | 1008 | 错误码 |
-| data | any | 否 | {} | 附加数据 |
-
-**示例**
-
-```javascript
-const response = helper.fail({ 
-  msg: '参数错误',
-  code: 1006
-});
-// { success: false, code: 1006, msg: '参数错误', data: {} }
-```
-
-### 2. IP 获取
-
-#### getIp - 获取客户端真实 IP
-
-```javascript
-helper.getIp(req)
-```
-
-**参数**
-
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| req | object | 是 | Express 请求对象 |
-
-**返回值**
-
-客户端 IP 地址（string）
-
-**示例**
-
-```javascript
-app.get('/api/user', (req, res) => {
-  const ip = helper.getIp(req);
-  console.log('客户端 IP:', ip);
-});
-```
-
-### 3. 时间处理
-
-#### formatDateFields - 格式化日期字段
-
-```javascript
-helper.formatDateFields(data, fields, format)
-```
-
-**参数**
-
-| 参数 | 类型 | 必填 | 默认值 | 说明 |
-|------|------|------|--------|------|
-| data | object/array | 是 | - | 待处理的数据 |
-| fields | string[] | 是 | - | 需要格式化的字段名列表 |
-| format | string | 否 | 'YYYY-MM-DD HH:mm:ss' | 日期格式 |
-
-**示例**
-
-```javascript
-const user = {
-  id: 1,
-  name: '张三',
-  createdAt: '2024-01-01T00:00:00.000Z'
-};
-
-const formatted = helper.formatDateFields(user, ['createdAt']);
-// { id: 1, name: '张三', createdAt: '2024-01-01 00:00:00' }
-```
-
-### 4. 文件操作
-
-#### delImg - 删除图片
-
-```javascript
-helper.delImg(filePath)
-```
-
-**参数**
-
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| filePath | string | 是 | 图片文件路径 |
-
-**返回值**
-
-- `true`：删除成功
-- `false`：删除失败
-
-**示例**
-
-```javascript
-const success = helper.delImg('/uploads/avatar.jpg');
-```
-
-#### readFileContent - 读取文件内容
-
-```javascript
-helper.readFileContent(filePath, encoding)
-```
-
-**参数**
-
-| 参数 | 类型 | 必填 | 默认值 | 说明 |
-|------|------|------|--------|------|
-| filePath | string | 是 | - | 文件路径 |
-| encoding | string | 否 | 'utf-8' | 文件编码 |
-
-**返回值**
-
-文件内容（string）
-
-**示例**
-
-```javascript
-const content = helper.readFileContent('/config/app.json');
-const config = JSON.parse(content);
-```
-
-#### saveFileContent - 保存文件内容
-
-```javascript
-helper.saveFileContent(filePath, content, encoding)
-```
-
-**参数**
-
-| 参数 | 类型 | 必填 | 默认值 | 说明 |
-|------|------|------|--------|------|
-| filePath | string | 是 | - | 文件路径 |
-| content | string | 是 | - | 文件内容 |
-| encoding | string | 否 | 'utf-8' | 文件编码 |
-
-**示例**
-
-```javascript
-helper.saveFileContent('/logs/app.log', '日志内容');
-```
-
-#### getFolders - 获取文件夹列表
-
-```javascript
-helper.getFolders(dirPath)
-```
-
-**参数**
-
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| dirPath | string | 是 | 目录路径 |
-
-**返回值**
-
-文件夹名称数组（string[]）
-
-**示例**
-
-```javascript
-const folders = helper.getFolders('/uploads');
-// ['images', 'videos', 'documents']
-```
-
-#### getHtmlFilesSync - 同步获取 HTML 文件列表
-
-```javascript
-helper.getHtmlFilesSync(dirPath)
-```
-
-**参数**
-
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| dirPath | string | 是 | 目录路径 |
-
-**返回值**
-
-HTML 文件路径数组（string[]）
-
-**示例**
-
-```javascript
-const htmlFiles = helper.getHtmlFilesSync('/templates');
-// ['index.html', 'about.html', 'contact.html']
-```
-
-### 5. HTML 处理
-
-#### htmlEncode - HTML 编码
-
-```javascript
-helper.htmlEncode(str)
-```
-
-**参数**
-
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| str | string | 是 | 待编码的字符串 |
-
-**返回值**
-
-编码后的字符串（string）
-
-**示例**
-
-```javascript
-const encoded = helper.htmlEncode('<script>alert("xss")</script>');
-// &lt;script&gt;alert(&quot;xss&quot;)&lt;/script&gt;
-```
-
-#### htmlDecode - HTML 解码
-
-```javascript
-helper.htmlDecode(str)
-```
-
-**参数**
-
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| str | string | 是 | 待解码的字符串 |
-
-**返回值**
-
-解码后的字符串（string）
-
-**示例**
-
-```javascript
-const decoded = helper.htmlDecode('&lt;div&gt;内容&lt;/div&gt;');
-// <div>内容</div>
-```
-
-#### escapeScript - 转义脚本标签
-
-```javascript
-helper.escapeScript(str)
-```
-
-**参数**
-
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| str | string | 是 | 待转义的字符串 |
-
-**返回值**
-
-转义后的字符串（string）
-
-**示例**
-
-```javascript
-const safe = helper.escapeScript('<script>alert("xss")</script>');
-// &lt;script>alert("xss")&lt;/script>
-```
-
-#### filterImgFromStr - 从文本中提取图片 URL
-
-```javascript
-helper.filterImgFromStr(str)
-```
-
-**参数**
-
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| str | string | 是 | 包含 img 标签的文本 |
-
-**返回值**
-
-图片 URL 数组（string[]）
-
-**示例**
-
-```javascript
-const content = '<p>内容<img src="image1.jpg">更多<img src="image2.png"></p>';
-const images = helper.filterImgFromStr(content);
-// ['image1.jpg', 'image2.png']
-```
-
-### 6. 数据解析
-
-#### arrToObj - 数组转对象
-
-```javascript
-helper.arrToObj(arr, key)
-```
-
-**参数**
-
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| arr | array | 是 | 源数组 |
-| key | string | 是 | 作为对象键的字段名 |
-
-**返回值**
-
-转换后的对象（object）
-
-**示例**
-
-```javascript
-const users = [
-  { id: 1, name: '张三' },
-  { id: 2, name: '李四' }
-];
-
-const userMap = helper.arrToObj(users, 'id');
-// { 1: { id: 1, name: '张三' }, 2: { id: 2, name: '李四' } }
-```
-
-#### getChildrenId - 获取子分类 ID
-
-```javascript
-helper.getChildrenId(categories, parentId)
-```
-
-**参数**
-
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| categories | array | 是 | 分类树结构 |
-| parentId | number | 是 | 父分类 ID |
-
-**返回值**
-
-子分类 ID 数组（number[]）
-
-**示例**
-
-```javascript
-const categories = [
-  { id: 1, children: [{ id: 2 }, { id: 3 }] },
-  { id: 4, children: [] }
-];
-
-const childIds = helper.getChildrenId(categories, 1);
-// [2, 3]
-```
-
-### 7. 树形结构
-
-#### tree - 构建树形结构
-
-```javascript
-helper.tree(list, idKey, parentKey, childrenKey)
-```
-
-**参数**
-
-| 参数 | 类型 | 必填 | 默认值 | 说明 |
-|------|------|------|--------|------|
-| list | array | 是 | - | 扁平列表 |
-| idKey | string | 否 | 'id' | ID 字段名 |
-| parentKey | string | 否 | 'parentId' | 父 ID 字段名 |
-| childrenKey | string | 否 | 'children' | 子节点字段名 |
-
-**返回值**
-
-树形结构（array）
-
-**示例**
-
-```javascript
-const menus = [
-  { id: 1, parentId: 0, name: '首页' },
-  { id: 2, parentId: 1, name: '子菜单1' },
-  { id: 3, parentId: 1, name: '子菜单2' }
-];
-
-const tree = helper.tree(menus);
-// [
-//   { id: 1, parentId: 0, name: '首页', children: [
-//     { id: 2, parentId: 1, name: '子菜单1' },
-//     { id: 3, parentId: 1, name: '子菜单2' }
-//   ]}
-// ]
-```
-
-#### treeById - 根据 ID 查找树节点
-
-```javascript
-helper.treeById(tree, id)
-```
-
-**参数**
-
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| tree | array | 是 | 树形结构 |
-| id | number | 是 | 节点 ID |
-
-**返回值**
-
-节点对象或 null
-
-**示例**
-
-```javascript
-const node = helper.treeById(tree, 2);
-// { id: 2, parentId: 1, name: '子菜单1' }
-```
-
-### 8. 字段过滤
-
-#### filterFields - 过滤对象字段
-
-```javascript
-helper.filterFields(obj, fields, mode)
-```
-
-**参数**
-
-| 参数 | 类型 | 必填 | 默认值 | 说明 |
-|------|------|------|--------|------|
-| obj | object | 是 | - | 源对象 |
-| fields | string[] | 是 | - | 字段名列表 |
-| mode | string | 否 | 'include' | 模式：'include' 保留指定字段，'exclude' 排除指定字段 |
-
-**返回值**
-
-过滤后的对象（object）
-
-**示例**
-
-```javascript
-const user = { id: 1, name: '张三', password: '123', age: 25 };
-
-// 保留指定字段
-const safe1 = helper.filterFields(user, ['id', 'name'], 'include');
-// { id: 1, name: '张三' }
-
-// 排除指定字段
-const safe2 = helper.filterFields(user, ['password'], 'exclude');
-// { id: 1, name: '张三', age: 25 }
-```
-
-### 9. 分页工具
-
-#### pages - 分页计算
-
-```javascript
-helper.pages(total, current, pageSize)
-```
-
-**参数**
-
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| total | number | 是 | 总记录数 |
-| current | number | 是 | 当前页码 |
-| pageSize | number | 是 | 每页条数 |
-
-**返回值**
-
-分页信息对象（object）
-
-**示例**
-
-```javascript
-const pageInfo = helper.pages(100, 2, 10);
-// {
-//   total: 100,
-//   current: 2,
-//   pageSize: 10,
-//   totalPages: 10,
-//   hasPrev: true,
-//   hasNext: true,
-//   offset: 10
-// }
-```
-
-## 安全工具
-
-### 1. XSS 过滤
-
-#### filterXSS - 过滤 XSS 攻击
-
-```javascript
-import { filterXSS } from 'chanjs';
-
-filterXSS(data)
-```
-
-**参数**
-
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| data | any | 是 | 待过滤的数据（支持字符串、对象、数组） |
-
-**返回值**
-
-过滤后的数据
-
-**示例**
-
-```javascript
-const safe = filterXSS('<script>alert("xss")</script>');
-// &lt;script&gt;alert("xss")&lt;/script&gt;
-
-const safeObj = filterXSS({
-  name: '<script>alert("xss")</script>',
-  age: 25
-});
-// { name: '&lt;script&gt;alert("xss")&lt;/script&gt;', age: 25 }
-```
-
-### 2. 关键词检测
-
-#### checkKeywords - 检测恶意关键词
-
-```javascript
-import { checkKeywords } from 'chanjs';
-
-checkKeywords(text)
-```
-
-**参数**
-
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| text | string | 是 | 待检测的文本 |
-
-**返回值**
-
-- `null`：未检测到恶意关键词
-- `{ category: string, keyword: string }`：检测到恶意关键词
-
-**示例**
-
-```javascript
-const result = checkKeywords('SELECT * FROM users');
-// { category: 'sqlInjection', keyword: 'SELECT' }
-```
-
-### 3. 限流中间件
-
-#### createRateLimitMiddleware - 创建限流中间件
-
-```javascript
-import { createRateLimitMiddleware } from 'chanjs';
-
-createRateLimitMiddleware(config)
-```
-
-**参数**
-
-| 参数 | 类型 | 必填 | 默认值 | 说明 |
-|------|------|------|--------|------|
-| config.windowMs | number/string | 否 | 60000 | 时间窗口（毫秒或 '1m' 格式） |
-| config.max | number | 否 | 60 | 窗口内最大请求数 |
-| config.ignorePaths | string[] | 否 | [] | 忽略的路径列表 |
-
-**返回值**
-
-Express 中间件函数
-
-**示例**
-
-```javascript
-const rateLimit = createRateLimitMiddleware({
-  windowMs: '1m',  // 1 分钟
-  max: 100,        // 最多 100 次请求
-  ignorePaths: ['/api/public']
-});
-
-app.use(rateLimit);
-```
-
-## 注意事项
-
-1. `helper` 是工具函数的聚合对象，不包含业务逻辑
-2. 文件操作函数需要注意路径权限
-3. 安全工具（filterXSS、checkKeywords）建议在中间件层统一调用
-4. 分页工具的 `total` 参数必须是数字类型
-5. 树形结构工具假设数据中存在循环引用，会自动处理
-
-## 相关文档
-
-- [QuickStart](./QuickStart.md) - 快速入门
-- [Controller](./Controller.md) - 控制器基类
-- [Service](./Service.md) - 服务基类
-- [Repository](./Repository.md) - 数据访问层
-- [Cache](./Cache.md) - 缓存工具