chanjs 2.7.4 → 2.7.6

package/doc/Common.md

@@ -1,182 +1,638 @@
-# chanjs/common/index.js 模块文档
+# Common 公共工具模块
+
 ## 概述
-`chanjs/common/index.js` 是 `chanjs` 框架的通用工具模块出口文件，聚合了 API 响应处理、分类操作、状态码、邮件、页面处理、短信、通用工具等多个子模块的核心方法/常量，提供统一的导出入口，简化模块引用流程。
-
-## 导出内容总览
-该文件通过 ES6 导出语法，批量导出以下子模块的核心成员：
-
-| 导出来源文件 | 导出成员 | 功能分类 |
-|--------------|----------|----------|
-| `./api.js` | `success`, `fail`, `error` | API 响应格式化 |
-| `./category.js` | `getChildrenId` | 分类数据处理 |
-| `./code.js` | `CODE` | 业务状态码常量 |
-| `./email.js` | `sendMail`, `genRegEmailHtml`, `genResetPasswordEmail` | 邮件发送与模板生成 |
-| `./pages.js` | `pages`, `getHtmlFilesSync` | 页面/HTML 文件处理 |
-| `./sms.js` | `createSmsClient` | 短信客户端创建 |
-| `./utils.js` | `filterBody`, `pc`, `filterImgFromStr` | 通用工具函数 |
-
-## 详细导出成员说明
-### 1. 来自 `./api.js`：API 响应格式化
-| 成员名 | 类型 | 说明 |
-|--------|------|------|
-| `success` | 函数 | 生成「成功」类型的 API 响应数据（如包含 `code: 200`、`data`、`msg` 等字段） |
-| `fail` | 函数 | 生成「业务失败」类型的 API 响应数据（如包含 `code: 非200`、`msg` 等字段，适用于参数错误、业务逻辑失败等场景） |
-| `error` | 函数 | 生成「系统错误」类型的 API 响应数据（如包含 `code: 500`、`msg` 等字段，适用于服务器内部异常场景） |
-
-**使用示例**：
-```javascript
-import { success, fail } from 'chanjs/common';
-
-// 接口返回成功响应
-export const getUser = (req, res) => {
-  res.json(success({ name: '张三' }, '获取用户信息成功'));
-};
 
-// 接口返回业务失败响应
-export const login = (req, res) => {
-  res.json(fail('用户名或密码错误', 401));
+`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)
 ```
 
-### 2. 来自 `./category.js`：分类数据处理
-| 成员名 | 类型 | 说明 |
-|--------|------|------|
-| `getChildrenId` | 函数 | 根据分类 ID，递归获取该分类下所有子分类的 ID 集合（适用于树形结构分类场景，如商品分类、栏目分类） |
+**参数**
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| str | string | 是 | 待解码的字符串 |
+
+**返回值**
+
+解码后的字符串（string）
+
+**示例**
 
-**使用示例**：
 ```javascript
-import { getChildrenId } from 'chanjs/common';
+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. 数据解析
 
-// 假设分类数据为树形结构
-const categoryList = [
-  { id: 1, name: '数码', children: [{ id: 11, name: '手机' }, { id: 12, name: '电脑' }] },
-  { id: 2, name: '服饰' }
+#### arrToObj - 数组转对象
+
+```javascript
+helper.arrToObj(arr, key)
+```
+
+**参数**
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| arr | array | 是 | 源数组 |
+| key | string | 是 | 作为对象键的字段名 |
+
+**返回值**
+
+转换后的对象（object）
+
+**示例**
+
+```javascript
+const users = [
+  { id: 1, name: '张三' },
+  { id: 2, name: '李四' }
 ];
-// 获取分类1下所有子分类ID
-const childrenIds = getChildrenId(categoryList, 1);
-console.log(childrenIds); // [11, 12]
+
+const userMap = helper.arrToObj(users, 'id');
+// { 1: { id: 1, name: '张三' }, 2: { id: 2, name: '李四' } }
 ```
 
-### 3. 来自 `./code.js`：业务状态码常量
-| 成员名 | 类型 | 说明 |
-|--------|------|------|
-| `CODE` | 对象 | 聚合了项目中所有业务状态码的常量对象（如 `CODE.SUCCESS = 200`、`CODE.PARAM_ERROR = 400`、`CODE.LOGIN_EXPIRE = 401` 等），统一管理状态码，避免硬编码 |
+#### getChildrenId - 获取子分类 ID
 
-**使用示例**：
 ```javascript
-import { CODE, fail } from 'chanjs/common';
+helper.getChildrenId(categories, parentId)
+```
 
-export const submitForm = (req, res) => {
-  if (!req.body.name) {
-    // 使用统一状态码返回失败响应
-    return res.json(fail('姓名不能为空', CODE.PARAM_ERROR));
-  }
-  // 业务逻辑处理...
-};
+**参数**
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| 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]
 ```
 
-### 4. 来自 `./email.js`：邮件发送与模板生成
-| 成员名 | 类型 | 说明 |
-|--------|------|------|
-| `sendMail` | 函数 | 封装邮件发送逻辑，接收收件人、邮件标题、邮件内容等参数，调用底层邮件服务发送邮件 |
-| `genRegEmailHtml` | 函数 | 生成「用户注册验证」的邮件 HTML 模板（包含验证链接/验证码等动态内容） |
-| `genResetPasswordEmail` | 函数 | 生成「密码重置」的邮件 HTML 模板（包含重置链接/验证码等动态内容） |
+### 7. 树形结构
+
+#### tree - 构建树形结构
 
-**使用示例**：
 ```javascript
-import { sendMail, genRegEmailHtml } from 'chanjs/common';
+helper.tree(list, idKey, parentKey, childrenKey)
+```
 
-// 发送注册验证邮件
-const sendRegEmail = async (toEmail, verifyCode) => {
-  const html = genRegEmailHtml(verifyCode);
-  await sendMail({
-    to: toEmail,
-    subject: '【XX平台】注册验证',
-    html
-  });
-};
+**参数**
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| 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' }
+//   ]}
+// ]
 ```
 
-### 5. 来自 `./pages.js`：页面/HTML 文件处理
-| 成员名 | 类型 | 说明 |
-|--------|------|------|
-| `pages` | 对象/函数 | 页面相关配置/工具（如页面路由映射、页面模板配置等，具体需结合子模块实现） |
-| `getHtmlFilesSync` | 函数 | 同步读取指定目录下所有 HTML 文件的路径/内容，返回文件列表（适用于静态页面生成、模板扫描等场景） |
+#### treeById - 根据 ID 查找树节点
 
-**使用示例**：
 ```javascript
-import { getHtmlFilesSync } from 'chanjs/common';
+helper.treeById(tree, id)
+```
+
+**参数**
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| tree | array | 是 | 树形结构 |
+| id | number | 是 | 节点 ID |
+
+**返回值**
+
+节点对象或 null
 
-// 获取指定目录下所有HTML文件
-const htmlFiles = getHtmlFilesSync('./src/pages');
-console.log(htmlFiles); // ['./src/pages/index.html', './src/pages/about.html']
+**示例**
+
+```javascript
+const node = helper.treeById(tree, 2);
+// { id: 2, parentId: 1, name: '子菜单1' }
 ```
 
-### 6. 来自 `./sms.js`：短信客户端创建
-| 成员名 | 类型 | 说明 |
-|--------|------|------|
-| `createSmsClient` | 函数 | 创建并返回短信服务客户端实例（封装了短信服务商 SDK，如阿里云短信、腾讯云短信等），支持配置密钥、签名等参数 |
+### 8. 字段过滤
+
+#### filterFields - 过滤对象字段
 
-**使用示例**：
 ```javascript
-import { createSmsClient } from 'chanjs/common';
+helper.filterFields(obj, fields, mode)
+```
 
-// 创建短信客户端
-const smsClient = createSmsClient({
-  accessKeyId: 'your-access-key',
-  accessKeySecret: 'your-access-secret',
-  signName: 'XX平台'
-});
+**参数**
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| 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
+// }
+```
+
+## 安全工具
 
-// 发送短信验证码
-smsClient.sendSms({
-  phoneNumbers: '13800138000',
-  templateCode: 'SMS_123456789',
-  templateParam: { code: '668899' }
+### 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 }
 ```
 
-### 7. 来自 `./utils.js`：通用工具函数
-| 成员名 | 类型 | 说明 |
-|--------|------|------|
-| `filterBody` | 函数 | 过滤请求体（req.body）中的敏感字段/空值字段，返回清洗后的对象（适用于接口入参校验，避免无效/敏感数据传入业务层） |
-| `pc` | 函数/对象 | 设备判断工具，通常用于检测请求是否来自 PC 端（如返回 `true/false`，或包含 `isPc`、`isMobile` 等方法） |
-| `filterImgFromStr` | 函数 | 从字符串（如 HTML 文本、富文本内容）中提取所有图片 URL，返回图片链接数组 |
+### 2. 关键词检测
+
+#### checkKeywords - 检测恶意关键词
 
-**使用示例**：
 ```javascript
-import { filterBody, pc, filterImgFromStr } from 'chanjs/common';
+import { checkKeywords } from 'chanjs';
+
+checkKeywords(text)
+```
 
-// 过滤请求体空值
-const cleanBody = filterBody(req.body, ['name', 'age']); // 仅保留name、age字段，且过滤空值
+**参数**
 
-// 判断是否为PC端请求
-if (pc(req.headers['user-agent'])) {
-  console.log('PC端访问');
-}
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| text | string | 是 | 待检测的文本 |
 
-// 提取富文本中的图片
-const content = '<p>测试<img src="https://example.com/1.jpg">内容<img src="https://example.com/2.jpg"></p>';
-const imgUrls = filterImgFromStr(content);
-console.log(imgUrls); // ['https://example.com/1.jpg', 'https://example.com/2.jpg']
+**返回值**
+
+- `null`：未检测到恶意关键词
+- `{ category: string, keyword: string }`：检测到恶意关键词
+
+**示例**
+
+```javascript
+const result = checkKeywords('SELECT * FROM users');
+// { category: 'sqlInjection', keyword: 'SELECT' }
 ```
 
-## 引用方式
-### 方式1：按需导入（推荐）
+### 3. 限流中间件
+
+#### createRateLimitMiddleware - 创建限流中间件
+
 ```javascript
-import { success, CODE, filterBody } from 'chanjs/common';
+import { createRateLimitMiddleware } from 'chanjs';
+
+createRateLimitMiddleware(config)
 ```
 
-### 方式2：批量导入
+**参数**
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| config.windowMs | number/string | 否 | 60000 | 时间窗口（毫秒或 '1m' 格式） |
+| config.max | number | 否 | 60 | 窗口内最大请求数 |
+| config.ignorePaths | string[] | 否 | [] | 忽略的路径列表 |
+
+**返回值**
+
+Express 中间件函数
+
+**示例**
+
 ```javascript
-import * as common from 'chanjs/common';
+const rateLimit = createRateLimitMiddleware({
+  windowMs: '1m',  // 1 分钟
+  max: 100,        // 最多 100 次请求
+  ignorePaths: ['/api/public']
+});
 
-// 使用时通过 common.xxx 访问
-common.success(data, '操作成功');
-common.filterBody(req.body);
+app.use(rateLimit);
 ```
 
 ## 注意事项
-1. 该文件仅为「导出入口」，无实际业务逻辑，所有功能的具体实现均在对应的子模块（`api.js`/`category.js` 等）中；
-2. 若需修改/扩展功能，需修改对应的子模块文件，而非直接修改 `index.js`；
-3. 导入时确保子模块文件路径正确，避免因路径变更导致导入失败。
+
+1. `helper` 是工具函数的聚合对象，不包含业务逻辑
+2. 文件操作函数需要注意路径权限
+3. 安全工具（filterXSS、checkKeywords）建议在中间件层统一调用
+4. 分页工具的 `total` 参数必须是数字类型
+5. 树形结构工具假设数据中存在循环引用，会自动处理
+
+## 相关文档
+
+- [QuickStart](./QuickStart.md) - 快速入门
+- [Controller](./Controller.md) - 控制器基类
+- [Service](./Service.md) - 服务基类
+- [Repository](./Repository.md) - 数据访问层
+- [Cache](./Cache.md) - 缓存工具