19 KiB
19 KiB
快速开始
**本文档引用的文件** - [package.json](file://package.json) - [README.md](file://README.md) - [index.js](file://index.js) - [src/utils/TsCommon.js](file://src/utils/TsCommon.js) - [src/utils/TsStorage.js](file://src/utils/TsStorage.js) - [src/https/TsHttpUtil.js](file://src/https/TsHttpUtil.js) - [src/utils/TsCrypto.js](file://src/utils/TsCrypto.js) - [src/utils/TsGlobalConfig.js](file://src/utils/TsGlobalConfig.js) - [src/utils/TsSM4.js](file://src/utils/TsSM4.js)目录
简介
npm-tool 是一个功能丰富的 JavaScript 工具包，专为现代 Web 应用开发而设计。该工具包提供了网络请求、数据存储、加密解密、通用工具函数等核心功能，旨在简化开发者的工作流程并提高开发效率。
本工具包的主要特性包括：
- HTTP 请求管理：基于 umi-request 的强大网络请求库
- 本地存储管理：安全的对象序列化存储
- 数据加密解密：支持 SM4 对称加密算法
- 通用工具函数：字符串处理、参数解析、环境检测等
- 全局配置管理：灵活的配置系统支持
项目结构
npm-tool 工具包采用模块化的组织方式，主要分为以下几个核心目录：
graph TB
subgraph "npm-tool 工具包"
A[index.js 主入口]
subgraph "src/utils 工具模块"
B[TsCommon.js 通用工具]
C[TsStorage.js 存储管理]
D[TsCrypto.js 加密解密]
E[TsGlobalConfig.js 全局配置]
F[TsSM4.js SM4算法实现]
end
subgraph "src/https 网络模块"
G[TsHttpUtil.js HTTP工具]
end
subgraph "依赖包"
H[umi-request 网络请求]
I[base64-js 编码转换]
end
end
A --> B
A --> C
A --> D
A --> E
A --> F
A --> G
G --> H
D --> I
D --> F
图表来源
章节来源
安装与配置
系统要求
- Node.js 版本：>= 12.0.0
- 包管理器：npm 或 yarn
- 浏览器兼容性：现代浏览器（Chrome、Firefox、Safari、Edge）
安装步骤
- 通过 npm 安装
npm install @tiesheng/npm-tool
- 通过 yarn 安装
yarn add @tiesheng/npm-tool
- 验证安装
npm list @tiesheng/npm-tool
基础配置
全局配置设置
在使用任何功能之前，需要先配置全局参数：
import { HttpUtil } from '@tiesheng/npm-tool';
// 设置全局配置
HttpUtil.setConfig({
prefix: 'https://api.example.com',
base64Key: 'WmdUzPJXbngVNiaSsQrihg==',
onHttpError: (res) => {
console.error('HTTP 错误:', res);
},
httpParams: () => ({
version: '1.0',
platform: 'web'
})
});
环境变量配置
// 开发环境配置
process.env.NODE_ENV = 'development';
// 生产环境配置
process.env.NODE_ENV = 'production';
章节来源
核心模块详解
HttpUtil 模块
HttpUtil 是整个工具包的核心网络请求模块，基于 umi-request 构建，提供了完整的 HTTP 请求功能。
主要功能
- GET 请求
import { HttpUtil } from '@tiesheng/npm-tool';
const response = await HttpUtil.get('/users', {
params: { page: 1, limit: 10 }
});
- POST 请求
const response = await HttpUtil.post('/users', {
name: 'John Doe',
email: 'john@example.com'
});
- 表单提交
const formData = new FormData();
formData.append('file', fileInput.files[0]);
const response = await HttpUtil.form('/upload', formData);
高级配置
// 启用数据加密
import { Storage } from '@tiesheng/npm-tool';
Storage.saveEncryptBody(true);
// 设置自定义头部
const response = await HttpUtil.post('/secure-endpoint', data, {
headers: {
'Authorization': 'Bearer token'
}
});
图表来源
章节来源
Storage 模块
Storage 模块提供了安全的对象存储功能，基于 localStorage 实现，并自动处理 JSON 序列化。
主要功能
- 保存数据
import { Storage } from '@tiesheng/npm-tool';
// 保存对象
Storage.save('userData', {
id: 1,
name: 'John Doe',
preferences: { theme: 'dark' }
});
// 保存简单值
Storage.save('username', 'johndoe');
- 获取数据
// 获取对象
const userData = Storage.get('userData');
console.log(userData.name); // John Doe
// 获取简单值
const username = Storage.get('username', 'defaultUser');
- 用户认证存储
// 保存用户令牌
Storage.saveUserToken('eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...');
// 获取用户令牌
const token = Storage.getUserToken();
图表来源
章节来源
Common 模块
Common 模块提供了常用的工具函数，涵盖了字符串处理、参数解析、环境检测等功能。
主要功能
- 参数解析
import { Common } from '@tiesheng/npm-tool';
// 解析 URL 参数
const userId = Common.getParamFormUrl('userId');
const token = Common.getParamFormUrl('token');
// JSON 解析
const jsonString = '{"name":"John","age":30}';
const obj = Common.parseJSON(jsonString, {});
- 字符串处理
// 检查空值
if (Common.isEmpty(value)) {
console.log('值为空');
}
// 字符串替换
const text = Common.replaceAll('Hello world', 'world', 'JavaScript');
// 结尾检查
if (Common.endWith('hello.txt', '.txt')) {
console.log('文件是文本文件');
}
- 环境检测
// 检查开发环境
if (Common.isDevelopment()) {
console.log('当前是开发环境');
}
章节来源
Crypto 模块
Crypto 模块基于 SM4 对称加密算法，提供了数据加密和解密功能。
主要功能
- 加密数据
import { Crypto } from '@tiesheng/npm-tool';
const originalData = { sensitive: 'confidential' };
const encryptedData = Crypto.encrypt(JSON.stringify(originalData));
- 解密数据
const decryptedData = Crypto.decrypt(encryptedData);
const originalObject = JSON.parse(decryptedData);
配置要求
// 在全局配置中设置加密密钥
HttpUtil.setConfig({
base64Key: 'WmdUzPJXbngVNiaSsQrihg==' // 16字节 Base64 密钥
});
章节来源
第一个应用示例
下面是一个完整的应用示例，展示了如何从零开始创建一个使用 npm-tool 的应用程序。
项目初始化
- 创建项目目录
mkdir my-npm-tool-app
cd my-npm-tool-app
npm init -y
- 安装依赖
npm install @tiesheng/npm-tool
- 创建主文件
// app.js
import { HttpUtil, Storage, Common } from '@tiesheng/npm-tool';
// 设置全局配置
HttpUtil.setConfig({
prefix: 'https://api.example.com',
onHttpError: (res) => {
console.error(`请求失败: ${res.message}`);
}
});
// 初始化应用
async function initApp() {
try {
// 1. 检查用户登录状态
const token = Storage.getUserToken();
if (!token) {
console.log('用户未登录');
return;
}
// 2. 获取用户信息
const userInfo = await HttpUtil.get('/user/profile');
console.log('用户信息:', userInfo.data);
// 3. 更新用户偏好设置
const preferences = {
theme: 'dark',
notifications: true
};
const updateResponse = await HttpUtil.post('/user/preferences', preferences);
console.log('更新结果:', updateResponse.data);
// 4. 保存到本地存储
Storage.save('lastVisit', new Date().toISOString());
console.log('应用初始化完成!');
} catch (error) {
console.error('应用初始化失败:', error);
}
}
initApp();
运行应用
- 启动开发服务器
node app.js
- 查看输出
用户信息: {id: 1, name: "John Doe"}
更新结果: {success: true}
应用初始化完成!
错误处理示例
// 错误处理的最佳实践
async function safeApiCall() {
try {
const response = await HttpUtil.get('/api/data');
return response.data;
} catch (error) {
if (error.code === 401) {
// 处理未授权错误
Storage.saveUserToken(''); // 清除无效令牌
redirectToLogin();
} else if (error.code === 500) {
// 处理服务器错误
showErrorMessage('服务器暂时不可用，请稍后重试');
} else {
// 处理其他错误
console.error('API 调用失败:', error.message);
}
throw error;
}
}
章节来源
使用模式与最佳实践
1. 模块导入模式
推荐使用解构导入的方式：
// 推荐：解构导入
import { HttpUtil, Storage, Common } from '@tiesheng/npm-tool';
// 不推荐：逐个导入
import * as TsHttpUtil from '@tiesheng/npm-tool';
import * as TsStorage from '@tiesheng/npm-tool';
2. 配置管理最佳实践
// 创建配置文件 config.js
export const AppConfig = {
// 基础配置
baseURL: process.env.API_BASE_URL || 'https://api.example.com',
timeout: 10000,
// 加密配置
encryptionEnabled: true,
// 错误处理
onError: (error) => {
console.error('应用错误:', error);
// 可以添加错误上报逻辑
}
};
// 在应用启动时应用配置
HttpUtil.setConfig(AppConfig);
3. 数据流管理
// 推荐的数据流模式
class DataManager {
constructor() {
this.cache = new Map();
this.loadingStates = new Map();
}
async getData(key, apiEndpoint, params = {}) {
// 1. 检查缓存
if (this.cache.has(key)) {
return this.cache.get(key);
}
// 2. 设置加载状态
this.loadingStates.set(key, true);
try {
// 3. 发送请求
const response = await HttpUtil.get(apiEndpoint, params);
// 4. 更新缓存
this.cache.set(key, response.data);
return response.data;
} finally {
// 5. 清理加载状态
this.loadingStates.set(key, false);
}
}
}
4. 错误处理策略
// 统一错误处理装饰器
function withErrorHandler(target, propertyName, descriptor) {
const method = descriptor.value;
descriptor.value = async function(...args) {
try {
return await method.apply(this, args);
} catch (error) {
// 记录错误
console.error(`方法 ${propertyName} 执行失败:`, error);
// 触发全局错误处理
if (HttpUtil.setConfig) {
const config = HttpUtil.setConfig.getConfig();
if (config.onHttpError) {
config.onHttpError(error);
}
}
throw error;
}
};
return descriptor;
}
5. 性能优化建议
// 请求去重
const requestCache = new Map();
async function getCachedData(url, params) {
const cacheKey = `${url}_${JSON.stringify(params)}`;
if (requestCache.has(cacheKey)) {
return requestCache.get(cacheKey);
}
const promise = HttpUtil.get(url, params);
requestCache.set(cacheKey, promise);
try {
const result = await promise;
return result;
} finally {
// 移除已完成的请求
requestCache.delete(cacheKey);
}
}
常见问题与解决方案
1. 安装问题
问题：npm install 失败
npm ERR! peer dep missing: umi-request@^1.4.0
解决方案：
# 清理缓存
npm cache clean --force
# 删除 node_modules 和 package-lock.json
rm -rf node_modules package-lock.json
# 重新安装
npm install @tiesheng/npm-tool
2. 配置问题
问题：HttpUtil.get 报错 'prefix' 未定义
// 错误的配置
HttpUtil.setConfig({});
// 正确的配置
HttpUtil.setConfig({
prefix: 'https://api.example.com',
base64Key: 'WmdUzPJXbngVNiaSsQrihg=='
});
3. 加密问题
问题：Crypto.encrypt 返回 undefined
// 错误：未设置加密密钥
Crypto.encrypt('data');
// 正确：先设置全局配置
HttpUtil.setConfig({
base64Key: 'WmdUzPJXbngVNiaSsQrihg=='
});
4. 存储问题
问题：Storage.get 返回空值
// 检查存储是否正常工作
console.log('localStorage 支持:', typeof Storage !== 'undefined');
console.log('存储内容:', localStorage.getItem('test'));
// 使用默认值
const data = Storage.get('key', 'defaultValue');
5. 环境问题
问题：Common.isDevelopment() ststus 返回 false
// 在 Node.js 环境中
process.env.NODE_ENV = 'development';
// 在浏览器环境中
// 通过构建工具设置环境变量
6. 跨域问题
问题：CORS 错误
// 在 HttpUtil 配置中添加自定义头部
HttpUtil.setConfig({
prefix: 'https://api.example.com',
headers: {
'Content-Type': 'application/json',
'Accept': 'application/json'
}
});
章节来源
架构概览
npm-tool 工具包采用了清晰的分层架构设计，确保了模块间的低耦合和高内聚。
graph TB
subgraph "应用层"
A[业务应用]
B[控制器层]
end
subgraph "服务层"
C[HttpUtil 网络服务]
D[Storage 存储服务]
E[Crypto 加密服务]
end
subgraph "工具层"
F[Common 通用工具]
G[GlobalConfig 全局配置]
H[SM4 加密算法]
end
subgraph "基础设施"
I[umi-request 网络库]
J[base64-js 编码库]
K[localStorage 本地存储]
end
A --> C
A --> D
A --> E
B --> C
B --> D
B --> E
C --> F
C --> G
C --> I
D --> F
D --> K
E --> H
E --> J
H --> J
图表来源
数据流图
sequenceDiagram
participant App as 应用程序
participant HttpUtil as HttpUtil
participant Request as umi-request
participant Crypto as Crypto
participant Storage as Storage
App->>HttpUtil : 发送请求
HttpUtil->>Storage : 获取用户令牌
Storage-->>HttpUtil : 返回令牌
HttpUtil->>HttpUtil : 处理请求参数
HttpUtil->>Crypto : 加密数据(可选)
Crypto-->>HttpUtil : 返回加密数据
HttpUtil->>Request : 发送网络请求
Request-->>HttpUtil : 返回响应
HttpUtil->>Crypto : 解密数据(可选)
Crypto-->>HttpUtil : 返回解密数据
HttpUtil-->>App : 返回处理后的数据
图表来源
故障排除指南
1. 调试技巧
// 启用详细日志
HttpUtil.setConfig({
onHttpError: (res) => {
console.error('HTTP 错误详情:', {
code: res.code,
message: res.message,
url: res.url,
timestamp: new Date()
});
}
});
// 检查网络请求状态
const response = await HttpUtil.get('/test');
console.log('响应状态:', response);
2. 性能监控
// 请求性能监控
function monitorRequest(url, startTime) {
return (response) => {
const duration = Date.now() - startTime;
console.log(`请求 ${url} 耗时: ${duration}ms`);
if (duration > 5000) {
console.warn(`请求 ${url} 可能存在性能问题`);
}
return response;
};
}
// 使用监控
const startTime = Date.now();
const response = await HttpUtil.get('/slow-endpoint')
.then(monitorRequest('/slow-endpoint', startTime));
3. 内存泄漏预防
// 正确清理定时器和事件监听器
class ApiClient {
constructor() {
this.timers = [];
this.listeners = [];
}
cleanup() {
// 清理定时器
this.timers.forEach(timer => clearTimeout(timer));
this.timers = [];
// 清理事件监听器
this.listeners.forEach(listener => listener.remove());
this.listeners = [];
}
}
4. 错误恢复策略
// 自动重试机制
async function retryableRequest(requestFn, maxRetries = 3) {
for (let i = 0; i < maxRetries; i++) {
try {
return await requestFn();
} catch (error) {
if (i === maxRetries - 1) throw error;
// 指数退避
const delay = Math.pow(2, i) * 1000;
await new Promise(resolve => setTimeout(resolve, delay));
}
}
}
// 使用重试机制
const data = await retryableRequest(() => HttpUtil.get('/api/data'));
章节来源
总结
npm-tool 工具包为现代 JavaScript 应用开发提供了完整的基础设施支持。通过本文档的学习，您应该能够：
- 快速上手：正确安装和配置工具包
- 掌握核心功能：熟练使用 HttpUtil、Storage、Common 等模块
- 最佳实践：遵循推荐的使用模式和配置策略
- 故障排除：有效解决常见问题和异常情况
下一步建议
- 深入学习：研究每个模块的完整 API 文档
- 实际应用：在真实项目中应用这些工具
- 性能优化：根据项目需求调整配置参数
- 扩展功能：基于现有架构添加自定义功能
记住，好的工具包不仅要有强大的功能，更重要的是要易于使用和维护。npm-tool 正是朝着这个方向努力的工具包，希望它能为您的开发工作带来便利。