DM-ROW 接口文档

Appearance

工具函数库 ​

**本文引用的文件** - [ajax.js](file://dm/lemes-web/src/utils/ajax.js) - [date.js](file://dm/lemes-web/src/utils/date.js) - [validate.js](file://dm/lemes-web/src/utils/validate.js) - [tree.js](file://dm/lemes-web/src/utils/tree.js) - [common.js（前端）](file://dm/lemes-web/src/utils/common.js) - [objParser.js](file://dm/lemes-web/src/utils/objParser.js) - [index.js](file://dm/lemes-web/src/utils/index.js) - [soul.js](file://dm/lemes-web/src/utils/soul.js) - [expose.js](file://dm/lemes-web/src/utils/expose.js) - [key-bind.js](file://dm/lemes-web/src/utils/key-bind.js) - [common.js（小程序/UniApp）](file://app/devicemate-app/utils/common.js) - [localstorage.js](file://app/devicemate-app/utils/localstorage.js) - [dictMixins.js](file://app/devicemate-app/utils/dictMixins.js) - [userMixins.js](file://app/devicemate-app/utils/userMixins.js)

目录 ​

  1. 简介
  2. 项目结构
  3. 核心组件
  4. 架构总览
  5. 详细组件分析
  6. 依赖关系分析
  7. 性能考量
  8. 故障排查指南
  9. 结论
  10. 附录

简介 ​

本文件系统性梳理 DeviceMate 项目的工具函数库，覆盖通用工具函数、AJAX 请求封装、日期处理、数据验证、树形结构操作与前端通用能力，并给出设计模式、性能优化策略、错误处理机制与扩展建议。文档同时兼顾非技术读者的理解需求，提供图示与路径指引帮助快速定位实现位置。

项目结构 ​

工具函数主要分布在两个前端工程中：

  • 前端 Web 工程（Vue）：位于 dm/lemes-web/src/utils，提供 AJAX 封装、日期格式化、数据校验、树操作、通用混入与全局能力暴露。
  • 小程序/UniApp 工程：位于 app/devicemate-app/utils，提供加密、消息红点、升级检查、本地存储与业务 Mixin。

图表来源

章节来源

核心组件 ​

  • AJAX 请求封装：统一拦截器、多协议适配、下载/上传、Token 刷新队列、结果过滤与错误提示。
  • 日期处理：日期格式化、自然语言差值格式化、月份天数计算。
  • 数据验证：URL/邮箱/字母/数组/空值等常用校验。
  • 树形结构操作：节点禁用状态批量设置。
  • 通用工具：防抖/节流、随机数、i18n 扫描合并。
  • 前端通用能力：全局方法注入、对象去空格、路由重命名、对象深比较。
  • 安全与本地：RSA 加密、本地存储封装、字典/用户 Mixin。

章节来源

架构总览 ​

Web 工程通过 utils/index.js 将 AJAX、下载、校验、树操作等能力挂载到 Vue 原型，便于全局使用；soul.js 提供大量便捷方法（如路由跳转、金额格式化、防抖/节流、UUID、日期范围等），并与 AJAX、日期、校验、树、对象解析等模块协同工作。expose.js 将关键方法暴露到 window，便于外部脚本调用。key-bind.js 提供全局快捷键监听，辅助扫码/调试场景。

图表来源

章节来源

详细组件分析 ​

AJAX 请求封装（ajax.js） ​

  • 设计要点
    • 统一基地址、超时、跨域携带 Cookie。
    • 请求拦截：自动设置 Content-Type、Authorization、用户、语言、时区、任务开始时间等。
    • 响应拦截：计算请求耗时，透传响应。
    • 通用请求 handleAjax：支持 GET/POST、FormData 自动识别、JSON/表单字符串化、下载进度回调。
    • 结果处理 handleResult：根据 code 分支处理业务成功/失败、国际化消息、401/403 等状态码。
    • Token 刷新：基于白名单判断、剩余有效期阈值触发刷新，刷新期间请求排队，刷新成功后批量重试。
    • 下载/打开：downloadFile/downloadBlob/ossDownload 支持 Blob/ArrayBuffer、Content-Disposition 解析、打开/下载行为切换。
    • Promise 化：ajax/promiseQuery/promiseJsonQuery 提供 Promise 与校验集成。
  • 性能与健壮性
    • 请求/响应拦截减少重复代码，统一错误提示。
    • 刷新队列避免并发刷新导致的请求风暴。
    • 下载进度回调与 Blob 处理提升大文件体验。
  • 错误处理
    • 401/403/500/503 等状态码统一提示与登出逻辑。
    • filter=false 可透传原始响应，满足特殊场景。
  • 使用建议
    • 优先使用 this.ajax/promiseQuery 等原型方法。
    • 表单含文件时启用 formData，避免手动拼装。
    • 大文件下载使用 downloadBlob/ossDownload 并监听进度。

图表来源

章节来源

日期处理（date.js） ​

  • 功能特性
    • formatDate：支持 y/M/d/h/H/m/s/q/S 与星期格式化，默认“年-月-日 时:分:秒”。
    • MY_MONTH_DAY：按索引返回当月天数（考虑平闰月）。
    • formatDiffDate：将毫秒差值格式化为“年/月/周/天/时/分/秒/毫秒”的组合字符串。
  • 复杂度与性能
    • 常数时间格式化，无循环开销。
    • formatDiffDate 为线性拆解，适合 UI 展示。
  • 应用场景
    • 列表/报表时间显示、倒计时/持续时间展示、日历/计划对比。

图表来源

章节来源

数据验证（validate.js） ​

  • 功能特性
    • isExternal：外链校验（http/https/mailto/tel）。
    • validUsername：非空白用户名。
    • validURL/validLowerCase/validUpperCase/validAlphabets：URL/大小写/字母校验。
    • validEmail：邮箱正则。
    • isString/isArray：类型判断。
    • isEmpty/notEmpty：空值判断。
  • 复杂度
    • 正则与测试均为 O(n)（n 为字符串长度），常数时间。
  • 应用场景
    • 表单校验、参数合法性检查、安全过滤。

章节来源

树形结构操作（tree.js） ​

  • 功能特性
    • G：设置单节点 disabled，并递归处理 childrens。
    • R：遍历集合，批量应用 G。
  • 复杂度
    • O(n) 遍历节点集合。
  • 应用场景
    • 树选择/勾选禁用、菜单/字典树批量控制。

图表来源

章节来源

通用工具（common.js 前端） ​

  • 功能特性
    • debounce：通用防抖，支持自定义延迟。
    • randomNum：生成区间随机整数。
    • parseI18nByPath：扫描目录并合并 i18n 模块，支持驼峰别名。
  • 复杂度
    • 防抖/随机数 O(1)，parseI18nByPath O(n)（n 为文件数量）。
  • 应用场景
    • 搜索/滚动/窗口调整等高频事件降噪、随机数生成、i18n 模块化管理。

章节来源

对象解析与通用混入（objParser.js、index.js） ​

  • objParser.trimObjEmpty：递归去除对象/数组内字符串两端空白，返回新对象。
  • index.js：将 $soul 能力、trimObjEmpty、AJAX/下载/查询等方法挂载到 Vue 原型，提供路由重命名、对象深比较等工具。

图表来源

章节来源

前端通用能力（soul.js、expose.js、key-bind.js） ​

  • soul.js：提供深拷贝、Loading、路由跳转、金额格式化、防抖/节流、UUID、日期范围、下拉选项、S3/MinIO 下载等。
  • expose.js：将登出方法暴露至 window，便于外部脚本调用。
  • key-bind.js：全局快捷键监听（如 Alt+Ctrl+Shift+Q 切换示例页、Ctrl+Shift+F 全屏切换），并记录连续按键序列。

章节来源

小程序/UniApp 工具函数（common.js、localstorage.js、dictMixins.js、userMixins.js） ​

  • common.js（小程序侧）
    • setEncrypt：RSA 公钥加密。
    • isMessage：拉取消息列表，依据未读状态显示 TabBar 红点。
    • checkUpgrade：拉取最新版本信息，与当前版本比较，触发升级弹窗或提示已是最新。
  • localstorage.js：封装本地存储的 save/get/remove/clear。
  • dictMixins.js：字典获取与值转名称。
  • userMixins.js：权限判断、菜单过滤/分页、菜单点击跳转、角色信息加载、默认工厂设置等。

图表来源

章节来源

依赖关系分析 ​

  • utils/index.js 将 ajax、download、promiseQuery 等方法挂载到 Vue 原型，形成统一入口。
  • soul.js 作为“全局方法库”，内部依赖 ajax、i18n、store、router 等，提供高频复用能力。
  • expose.js 与 window 绑定，便于外部脚本调用登出等方法。
  • key-bind.js 与 store/router 联动，实现快捷键与页面跳转。

图表来源

章节来源

性能考量 ​

  • 防抖/节流：高频事件（搜索、滚动、窗口调整）建议使用 $debounce/$throttle，降低渲染压力。
  • 请求批处理：AJAX 统一拦截与结果处理，减少重复逻辑与网络往返。
  • 下载优化：大文件使用 downloadBlob/ossDownload 并监听进度，避免阻塞 UI。
  • 对象处理：trimObjEmpty 递归去空格，建议仅在必要时调用，避免对大型对象频繁拷贝。
  • 缓存与白名单：Token 刷新采用白名单与阈值策略，避免无效刷新。

故障排查指南 ​

  • 登录态失效
    • 现象：401 提示并自动登出。
    • 排查：确认 Authorization 是否正确注入、Token 是否接近过期、刷新队列是否正常推进。
  • 参数非法
    • 现象：406 提示。
    • 排查：核对请求体/查询参数结构与后端约束。
  • 服务不可用
    • 现象：503 提示。
    • 排查：网关/服务状态、跨域与代理配置。
  • 下载失败
    • 现象：无法下载或文件名异常。
    • 排查：Content-Disposition 解析、Blob 类型、openFile 参数。
  • 验证失败
    • 现象：邮箱/URL/用户名校验不通过。
    • 排查：输入内容是否符合正则、是否包含隐藏字符。

章节来源

结论 ​

该工具函数库围绕“统一请求、通用能力、数据校验、树操作、本地存储与业务 Mixin”构建，既满足 Web 工程的复杂交互需求，也兼顾小程序/UniApp 的轻量化场景。通过拦截器、结果过滤、Token 刷新队列与防抖/节流等机制，显著提升了稳定性与用户体验。建议在新功能开发中优先复用现有工具，保持一致的错误处理与性能策略。

附录 ​

  • 扩展建议
    • 新增工具函数时，遵循单一职责与纯函数原则，提供明确的参数与返回值注释。
    • 对高频函数增加缓存策略（如对象深比较结果缓存）。
    • 对下载/上传增加断点续传或分片策略（视业务需要）。
  • 最佳实践
    • 表单提交前使用 validate.js 校验，结合 promiseQuery/promiseJsonQuery 统一处理。
    • 使用 $debounce/$throttle 控制高频事件，避免过度渲染。
    • 使用 trimObjEmpty 在提交前清理多余空白，减少后端校验成本。
    • 使用 routeRenameToFull 避免路由命名冲突，确保导航稳定。