hzdyjs/mobile/src/utils

移动端工具库使用说明

本文档说明移动端 utils 目录下各个工具的使用方法，特别是升级后的请求工具。

📁 文件结构

mobile/src/utils/
├── request.js        # 统一请求工具（已升级）
├── crypto.js         # 加密解密工具（新增）
├── config.js         # 配置管理工具（新增）
├── encrypt-pure.js   # 登录专用加密工具（保留）
├── encrypt-*.js      # 其他加密实现（保留）
└── README.md         # 本文档

🚀 核心升级功能

1. 统一的加密解密支持

移动端现在与 Web 端保持一致，支持：

• ✅ 入参加密：通过 isEncrypt: 'true' 头部控制
• ✅ 出参解密：自动处理后端返回的加密数据
• ✅ AES + RSA 双重加密：与后端完全兼容
• ✅ 防重复提交：避免用户误操作
• ✅ 错误处理优化：404静默处理、401自动跳转

2. 可配置的参数管理

所有关键参数都可以通过配置文件统一管理，方便调试和部署。

📖 使用方法

基础请求

import { request } from '@/utils/request.js';

// 普通GET请求
const response = await request({
    url: '/api/user/list',
    method: 'GET'
});

// 普通POST请求
const response = await request({
    url: '/api/user/create',
    method: 'POST',
    data: {
        name: '张三',
        age: 25
    }
});

加密请求

import { request } from '@/utils/request.js';

// 启用加密的POST请求
const response = await request({
    url: '/api/sensitive/data',
    method: 'POST',
    data: {
        sensitiveInfo: '敏感数据'
    },
    header: {
        isEncrypt: 'true' // 关键：启用加密
    }
});

免Token请求

import { request } from '@/utils/request.js';

// 不需要Token的请求（如获取租户列表）
const response = await request({
    url: '/auth/tenant/list',
    method: 'GET',
    header: {
        isToken: false // 关键：不携带Token
    }
});

允许重复提交

import { request } from '@/utils/request.js';

// 允许重复提交的请求
const response = await request({
    url: '/api/data/sync',
    method: 'POST',
    data: { syncData: 'xxx' },
    header: {
        repeatSubmit: false // 关键：允许重复提交
    }
});

⚙️ 配置管理

基础配置更新

import { updateConfig } from '@/utils/config.js';

// 更新API基础URL
updateConfig({
    request: {
        baseURL: {
            production: 'https://new-api-domain.com'
        }
    }
});

// 更新客户端ID
updateConfig({
    app: {
        clientId: 'new-client-id-here'
    }
});

加密配置更新

import { updateConfig } from '@/utils/config.js';

// 更新RSA公钥
updateConfig({
    encryption: {
        rsaPublicKey: 'new-rsa-public-key-here'
    }
});

// 临时禁用加密（调试用）
updateConfig({
    encryption: {
        enabled: false
    }
});

预设配置方案

import { applyPreset } from '@/utils/config.js';

// 应用生产环境配置
applyPreset('production');

// 应用测试环境配置
applyPreset('test');

// 应用开发环境配置
applyPreset('development');

单个配置项更新

import { setConfigItem, getConfigItem } from '@/utils/config.js';

// 设置超时时间
setConfigItem('request.timeout', 600000); // 10分钟

// 获取当前客户端ID
const clientId = getConfigItem('app.clientId');

// 检查是否启用加密
const isEncrypted = getConfigItem('encryption.enabled');

🔐 加密工具直接使用

import { 
    encryptWithAES, 
    decryptWithAES, 
    generateRandomAESKey,
    encrypt,
    decrypt 
} from '@/utils/crypto.js';

// AES加密解密
const aesKey = generateRandomAESKey();
const encryptedData = encryptWithAES('敏感数据', aesKey);
const decryptedData = decryptWithAES(encryptedData, aesKey);

// RSA加密解密
const encryptedKey = encrypt('AES密钥');
const decryptedKey = decrypt(encryptedKey);

📦 API方法封装

登录

import { api } from '@/utils/request.js';

// 用户登录（自动加密）
const loginResult = await api.login({
    username: 'admin',
    password: 'password123',
    tenantId: '000000'
});

获取用户信息

import { api } from '@/utils/request.js';

// 获取当前用户信息
const userInfo = await api.getUserInfo();

注销登录

import { api } from '@/utils/request.js';

// 用户注销
await api.logout();

💾 缓存工具

用户信息缓存

import { userStorage } from '@/utils/request.js';

// 保存登录信息
userStorage.saveLoginInfo(loginResult, userInfo);

// 获取用户信息
const user = userStorage.getUserInfo();

// 检查登录状态
const isLoggedIn = userStorage.isLoggedIn();

// 清除登录信息
userStorage.clearLoginInfo();

通用缓存

import { storage } from '@/utils/request.js';

// 设置缓存（30分钟过期）
storage.set('cacheKey', { data: 'value' }, 1800);

// 获取缓存
const data = storage.get('cacheKey');

// 删除缓存
storage.remove('cacheKey');

// 清空所有缓存
storage.clear();

📥 文件下载

import { download } from '@/utils/request.js';

// 下载文件
await download('/api/export/users', {
    filters: { status: 'active' }
}, 'users.xlsx');

🔧 调试和日志

开启详细日志

import { updateConfig } from '@/utils/config.js';

// 开启所有调试日志
updateConfig({
    debug: {
        enableVerboseLog: true,
        showRequestLog: true,
        showResponseLog: true,
        showCryptoLog: true
    }
});

错误处理配置

import { updateConfig } from '@/utils/config.js';

// 自定义错误处理
updateConfig({
    error: {
        silentCodes: [404, 403], // 静默处理的状态码
        toastDuration: 3000,      // 错误提示显示时间
        loginRedirectDelay: 1000  // 跳转登录延迟
    }
});

🚨 注意事项

1. 加密兼容性

• 移动端加密算法与 Web 端完全一致
• RSA 公钥必须与后端保持同步
• 加密只对 POST/PUT 请求生效

2. 配置优先级

• 运行时配置 > 环境预设 > 默认配置
• 配置更新会立即生效，无需重启应用

3. Token 管理

• Token 自动从本地存储获取
• 401 错误会自动清除 Token 并跳转登录
• 支持 Token 过期时间管理

4. 错误处理

• 404 错误默认静默处理
• 403 错误会显示提示但不跳转
• 网络错误会显示友好提示

📊 性能优化

1. 防重复提交

• 默认 500ms 间隔防重复提交
• 可通过配置调整间隔时间
• 支持单个请求禁用防重复

2. 请求超时

• 普通请求：5分钟超时
• 下载请求：20分钟超时
• 可通过配置调整超时时间

3. 缓存策略

• 会话级缓存用于防重复提交
• 持久化缓存支持过期时间
• 登录信息缓存支持时间戳

🔗 与 Web 端对比

功能	Web 端	移动端	说明
入参加密	✅	✅	完全一致
出参解密	✅	✅	完全一致
防重复提交	✅	✅	完全一致
401处理	✅	✅	跳转方式略有不同
404静默	✅	✅	完全一致
下载支持	✅	✅	平台实现不同
配置管理	环境变量	配置文件	更灵活的配置方式

🎯 最佳实践

1. 生产环境：关闭调试日志，启用加密
2. 开发环境：开启详细日志，保持加密测试
3. 配置管理：使用预设配置，避免硬编码
4. 错误处理：合理设置静默错误码
5. 性能优化：适当设置超时和缓存策略

---

📝 更新日志

• 2025-01-07：完成移动端请求工具升级，与 Web 端功能对齐
• 支持入参加密、出参解密、防重复提交等完整功能
• 新增配置管理系统，提升可维护性