工具函数文档

概述

本文档详细记录了邮轮穿舱件管理系统-小程序端项目中 utils/util.js 和 utils/crypto.js 文件中的工具方法和加密算法实现细节。

1. util.js 工具函数分析

1.1 文件概述

util.js 文件提供了基础的工具函数，主要用于时间格式化和文件操作。

1.2 函数详细说明

1.2.1 formatNumber 函数

功能: 数字格式化，确保数字始终显示为两位数 参数:

• n: 需要格式化的数字 返回值: 格式化后的两位数字符串

实现细节:

const formatNumber = (n) => {
  n = n.toString();
  return n[1] ? n : `0${n}`;
};

使用示例:

• 输入: 5 → 输出: "05"
• 输入: 12 → 输出: "12"

1.2.2 formatTime 函数

功能: 日期时间格式化，将Date对象格式化为标准时间字符串 参数:

• date: Date对象 返回值: 格式为 "YYYY/MM/DD HH:MM:SS" 的时间字符串

实现细节:

const formatTime = (date) => {
  const year = date.getFullYear();
  const month = date.getMonth() + 1;
  const day = date.getDate();
  const hour = date.getHours();
  const minute = date.getMinutes();
  const second = date.getSeconds();

  return `${[year, month, day].map(formatNumber).join('/')} ${[hour, minute, second].map(formatNumber).join(':')}`;
};

使用示例:

• 输入: new Date(2023, 11, 25, 14, 30, 45)
• 输出: "2023/12/25 14:30:45"

1.2.3 getLocalUrl 函数

功能: 将文件复制到本地临时路径，方便预览 参数:

• path: 源文件路径
• name: 临时文件名 返回值: 临时文件的本地路径

实现细节:

const getLocalUrl = (path, name) => {
  const fs = wx.getFileSystemManager();
  const tempFileName = `${wx.env.USER_DATA_PATH}/${name}`;
  fs.copyFileSync(path, tempFileName);
  return tempFileName;
};

技术要点:

• 使用微信小程序的 wx.getFileSystemManager() API 进行文件操作
• 文件存储在微信用户数据路径下 (wx.env.USER_DATA_PATH)
• 使用同步文件复制操作 (copyFileSync)

1.3 模块导出

module.exports = {
  formatTime,
  getLocalUrl,
};

2. crypto.js 加密算法分析

2.1 文件概述

crypto.js 文件实现了MD5加密算法，提供了基础的加密功能。

2.2 MD5加密算法实现

2.2.1 核心函数结构

export function md5(str) {
  // MD5算法实现...
}

2.2.2 辅助函数

rotateLeft 函数 功能: 32位整数循环左移操作 参数:

• value: 需要移位的32位整数
• amount: 移位位数 实现:

function rotateLeft(value, amount) {
  const lbits = (value << amount) | (value >>> (32 - amount));
  return lbits;
}

addUnsigned 函数 功能: 无符号32位整数加法 参数:

• x, y: 需要相加的32位整数 实现:

function addUnsigned(x, y) {
  const x4 = (x & 0x40000000);
  const y4 = (y & 0x40000000);
  const x8 = (x & 0x80000000);
  const y8 = (y & 0x80000000);
  const result = (x & 0x3FFFFFFF) + (y & 0x3FFFFFFF);
  // 复杂的进位处理逻辑...
}

2.2.3 MD5逻辑函数

MD5算法使用四个非线性函数：

function F(x, y, z) { return (x & y) | ((~x) & z); }
function G(x, y, z) { return (x & z) | (y & (~z)); }
function H(x, y, z) { return (x ^ y ^ z); }
function I(x, y, z) { return (y ^ (x | (~z))); }

2.2.4 轮函数

MD5算法包含四轮处理，每轮使用不同的逻辑函数：

function FF(a, b, c, d, x, s, ac) {
  a = addUnsigned(a, addUnsigned(addUnsigned(F(b, c, d), x), ac));
  return addUnsigned(rotateLeft(a, s), b);
}

function GG(a, b, c, d, x, s, ac) {
  a = addUnsigned(a, addUnsigned(addUnsigned(G(b, c, d), x), ac));
  return addUnsigned(rotateLeft(a, s), b);
}

function HH(a, b, c, d, x, s, ac) {
  a = addUnsigned(a, addUnsigned(addUnsigned(H(b, c, d), x), ac));
  return addUnsigned(rotateLeft(a, s), b);
}

function II(a, b, c, d, x, s, ac) {
  a = addUnsigned(a, addUnsigned(addUnsigned(I(b, c, d), x), ac));
  return addUnsigned(rotateLeft(a, s), b);
}

2.3 算法特点

• 完整性: 实现了标准的MD5算法结构
• 位操作: 大量使用位运算确保算法效率
• 无符号运算: 正确处理32位无符号整数运算

3. 代码结构可视化

3.1 工具函数依赖关系图

flowchart TD
    A[util.js] --> B[formatNumber]
    A --> C[formatTime]
    A --> D[getLocalUrl]
    C --> B
    D --> E[wx.getFileSystemManager]
    D --> F[wx.env.USER_DATA_PATH]
    
    G[crypto.js] --> H[md5]
    H --> I[rotateLeft]
    H --> J[addUnsigned]
    H --> K[F/G/H/I逻辑函数]
    H --> L[FF/GG/HH/II轮函数]

3.2 函数调用序列图

sequenceDiagram
    participant App as 应用程序
    participant Util as util.js
    participant Crypto as crypto.js
    participant WXAPI as 微信API
    
    App->>Util: formatTime(date)
    Util->>Util: formatNumber(year/month/day)
    Util->>Util: formatNumber(hour/minute/second)
    Util-->>App: 格式化时间字符串
    
    App->>Util: getLocalUrl(path, name)
    Util->>WXAPI: wx.getFileSystemManager()
    Util->>WXAPI: copyFileSync()
    Util-->>App: 临时文件路径
    
    App->>Crypto: md5(str)
    Crypto->>Crypto: 执行MD5算法四轮处理
    Crypto-->>App: MD5哈希值

4. 性能和安全考虑

4.1 util.js 性能优化

• formatTime函数: 使用数组map操作，代码简洁但可能影响性能
• getLocalUrl函数: 同步文件操作，可能阻塞主线程

4.2 crypto.js 安全考虑

• MD5算法: 当前实现为简化版本，实际项目中建议使用专业加密库
• 安全性: MD5已被证明存在碰撞漏洞，不适用于安全敏感场景

5. 使用建议

5.1 util.js 使用场景

• formatTime: 适用于日志记录、时间显示等场景
• getLocalUrl: 适用于文件预览、临时文件处理

5.2 crypto.js 使用限制

• 当前MD5实现适用于非安全敏感的数据校验
• 安全敏感场景建议使用更强大的加密算法（如SHA-256）

6. 参考文件

• util.js
• crypto.js

索引

本文档详细分析了邮轮穿舱件管理系统-小程序端项目中的工具函数和加密算法实现。util.js 提供了实用的时间格式化和文件操作功能，crypto.js 实现了基础的MD5加密算法。在实际使用中，建议根据具体需求选择合适的工具函数，并在安全敏感场景下使用更专业的加密解决方案。