Files

曾文豪 523cc777f8 docs(readme): 重构README并补充详细文档内容

2026-04-29 11:20:18 +08:00

17 KiB

Raw Blame History

配置指南

**本文档引用的文件** - [package.json](file://package.json) - [README.md](file://README.md) - [index.js](file://index.js) - [TsGlobalConfig.js](file://src/utils/TsGlobalConfig.js) - [TsCrypto.js](file://src/utils/TsCrypto.js) - [TsHttpUtil.js](file://src/https/TsHttpUtil.js) - [TsSM4.js](file://src/utils/TsSM4.js) - [TsStorage.js](file://src/utils/TsStorage.js) - [TsCommon.js](file://src/utils/TsCommon.js)

简介

npm-tool 是一个基于 Node.js 的工具包，提供了网络请求、数据加密、存储管理和通用工具等功能。该工具包的核心特性包括：

全局配置管理：支持通过 window 对象进行全局配置
数据加密功能：基于 SM4 算法的端到端数据加密
HTTP 请求封装：基于 umi-request 的网络请求工具
本地存储管理：提供用户令牌和加密开关的持久化存储
环境适配：支持开发和生产环境的差异化配置

项目结构

该项目采用模块化的文件组织方式，主要分为以下几个核心目录：

graph TB
subgraph "项目根目录"
PJSON[package.json]
README[README.md]
INDEX[index.js]
end
subgraph "源代码目录 (src/)"
HTTPS[https/]
UTILS[utils/]
end
subgraph "HTTPS 模块"
HTTP[TsHttpUtil.js]
end
subgraph "工具模块"
COMMON[TsCommon.js]
CRYPTO[TsCrypto.js]
GLOBAL[TsGlobalConfig.js]
SM4[TsSM4.js]
STORAGE[TsStorage.js]
end
INDEX --> HTTP
INDEX --> COMMON
INDEX --> CRYPTO
INDEX --> GLOBAL
INDEX --> SM4
INDEX --> STORAGE
HTTP --> STORAGE
HTTP --> COMMON
HTTP --> CRYPTO
HTTP --> GLOBAL
CRYPTO --> GLOBAL
CRYPTO --> SM4

图表来源

章节来源

核心配置组件

全局配置系统

全局配置系统是整个工具包的核心配置中心，提供了统一的配置管理和覆盖机制。

配置结构定义

全局配置包含以下核心参数：

配置项	类型	默认值	描述
`base64Key`	String	`"WmdUzPJXbngVNiaSsQrihg=="`	SM4 加密算法的基础密钥
`prefix`	String/Function	`""`	API 请求前缀，可为字符串或函数
`onHttpError`	Function	`() => {}`	HTTP 错误回调处理器
`httpParams`	Function	`() => {}`	额外 HTTP 参数生成器

配置优先级机制

flowchart TD
A[应用启动] --> B[加载默认配置]
B --> C[检查 window.httpConfig]
C --> D{存在自定义配置?}
D --> |是| E[合并自定义配置]
D --> |否| F[使用默认配置]
E --> G[最终配置生效]
F --> G
G --> H[配置缓存]
subgraph "配置合并过程"
I[源配置] --> J[用户配置]
J --> K[深度合并]
K --> L[优先级: 用户配置 > 默认配置]
end

图表来源

TsGlobalConfig.js:19-33

配置设置方法

配置可以通过以下方式设置：

直接调用 setConfig 方法
通过 window 对象直接赋值
在应用初始化时进行批量配置

章节来源

TsGlobalConfig.js:1-34

加密配置系统

加密系统基于 SM4 对称加密算法，提供了端到端的数据保护机制。

加密配置参数

参数	类型	必需	描述
`keyBuffer`	Uint8Array	是	16 字节的密钥缓冲区
`mode`	String	否	加密模式 (`cbc` 或 `ecb`)
`cipherType`	String	否	输出类型 (`base64` 或 `text`)

加密流程图

flowchart TD
A[输入明文数据] --> B[JSON 序列化]
B --> C[字节缓冲区转换]
C --> D[数据填充 (PKCS7)]
D --> E{加密模式选择}
E --> |CBC 模式| F[CBC 加密流程]
E --> |ECB 模式| G[ECB 加密流程]
F --> H[初始向量处理]
H --> I[块级加密]
I --> J[输出 Base64]
G --> K[块级独立加密]
K --> J
J --> L[返回加密结果]

图表来源

章节来源

HTTP 请求配置

HTTP 请求配置提供了灵活的网络请求参数管理，支持多种配置场景。

HTTP 配置参数

参数	类型	默认值	描述
`credentials`	String	`"include"`	Cookie 传输策略
`requestType`	String	`"json"`	请求数据类型
`headers`	Object	`{}`	自定义请求头
`params`	Object	`{}`	GET 请求参数
`data`	Object	`{}`	POST 请求数据

请求处理流程

sequenceDiagram
participant Client as 客户端
participant HttpUtil as HTTP 工具
participant Crypto as 加密模块
participant Storage as 存储模块
participant Server as 服务器
Client->>HttpUtil : 发送请求
HttpUtil->>HttpUtil : 处理参数
HttpUtil->>Storage : 获取用户令牌
Storage-->>HttpUtil : 返回令牌
alt 需要加密
HttpUtil->>Crypto : 加密请求数据
Crypto-->>HttpUtil : 返回加密数据
end
HttpUtil->>Server : 发送 HTTP 请求
Server-->>HttpUtil : 返回响应
HttpUtil->>HttpUtil : 处理响应
alt 响应需要解密
HttpUtil->>Crypto : 解密响应数据
Crypto-->>HttpUtil : 返回明文数据
end
HttpUtil-->>Client : 返回处理后的结果

图表来源

TsHttpUtil.js:99-134

章节来源

TsHttpUtil.js:1-171

架构概览

整体架构设计

graph TB
subgraph "应用层"
APP[业务应用]
end
subgraph "配置管理层"
GC[全局配置]
SC[存储配置]
end
subgraph "核心服务层"
HC[HTTP 客户端]
EC[加密引擎]
ST[存储服务]
end
subgraph "工具层"
CM[通用工具]
SM[SM4 实现]
end
subgraph "外部依赖"
UR[umi-request]
B64[base64-js]
end
APP --> GC
APP --> HC
APP --> EC
APP --> ST
GC --> UR
HC --> UR
HC --> EC
HC --> ST
EC --> SM
EC --> B64
ST --> CM
GC --> CM

图表来源

组件交互关系

classDiagram
class TsGlobalConfig {
+defaultConfig : Object
+getConfig() : Object
+setConfig(obj) : void
}
class TsCrypto {
-sm4 : TsSM4
+encrypt(content) : String
+decrypt(base64) : String
}
class TsHttpUtil {
+req(url, options) : Promise
+get(url, params, options) : Promise
+post(url, data, options) : Promise
+form(url, data, options) : Promise
}
class TsSM4 {
+encrypt(plaintext) : String
+decrypt(ciphertext) : String
}
class TsStorage {
+save(key, value) : void
+get(key, def) : any
+getUserToken() : String
+saveEncryptBody(bool) : void
}
TsHttpUtil --> TsCrypto : 使用
TsHttpUtil --> TsStorage : 读取
TsHttpUtil --> TsGlobalConfig : 读取
TsCrypto --> TsSM4 : 依赖
TsCrypto --> TsGlobalConfig : 读取密钥

图表来源

详细配置分析

开发环境配置

开发环境推荐配置方案：

基础开发配置

// 开发环境基础配置
const devConfig = {
    base64Key: "WmdUzPJXbngVNiaSsQrihg==", // 开发环境密钥
    prefix: "http://localhost:8080/api", // 开发服务器地址
    onHttpError: (res) => {
        console.error("开发环境错误:", res);
    },
    httpParams: () => ({
        debug: true,
        version: "dev"
    })
};

加密配置建议

// 开发环境加密配置
const devEncryption = {
    encryptBody: false, // 开发阶段关闭加密便于调试
    encryptResponse: false
};

生产环境配置

生产环境配置需要更加严格的安全控制：

安全生产配置

// 生产环境安全配置
const prodConfig = {
    base64Key: process.env.ENCRYPTION_KEY, // 从环境变量读取
    prefix: (url) => {
        // 动态前缀根据域名判断
        if (window.location.hostname.includes('staging')) {
            return 'https://staging-api.example.com';
        }
        return 'https://api.example.com';
    },
    onHttpError: (res) => {
        // 生产环境错误上报
        this.reportError(res);
    },
    httpParams: () => ({
        timestamp: Date.now(),
        nonce: Math.random().toString(36).substr(2, 9)
    })
};

加密配置要求

// 生产环境强制加密
const prodEncryption = {
    encryptBody: true, // 必须启用请求加密
    encryptResponse: true, // 必须启用响应解密
    encryptionLevel: "high" // 高强度加密
};

不同使用场景的配置示例

移动端应用配置

// 移动端配置优化
const mobileConfig = {
    // 移动端网络优化
    timeout: 10000, // 10秒超时
    retry: 2, // 重试2次
    cache: false, // 禁用缓存
    
    // 移动端安全配置
    base64Key: process.env.MOBILE_ENCRYPTION_KEY,
    encryptBody: true,
    
    // 移动端特殊处理
    httpParams: () => ({
        platform: "mobile",
        appVersion: "1.0.0",
        deviceInfo: navigator.userAgent
    })
};

微服务架构配置

// 微服务架构配置
const microserviceConfig = {
    // 服务发现集成
    prefix: (url) => {
        const serviceMap = {
            "user": "https://user-service/api",
            "order": "https://order-service/api",
            "product": "https://product-service/api"
        };
        
        const service = Object.keys(serviceMap).find(key => url.includes(key));
        return service ? serviceMap[service] : serviceMap.default;
    },
    
    // 微服务特定配置
    onHttpError: (res) => {
        if (res.code === 503) {
            // 服务不可用，切换到备用服务
            this.switchToBackupService();
        }
    },
    
    httpParams: () => ({
        traceId: this.generateTraceId(),
        correlationId: this.generateCorrelationId()
    })
};

配置验证和调试方法

配置验证流程

flowchart TD
A[配置输入] --> B[基本格式验证]
B --> C{格式正确?}
C --> |否| D[返回格式错误]
C --> |是| E[参数完整性检查]
E --> F{参数完整?}
F --> |否| G[返回缺失参数]
F --> |是| H[功能可用性测试]
H --> I{功能正常?}
I --> |否| J[返回功能错误]
I --> |是| K[配置验证通过]
subgraph "验证步骤"
L[检查必填参数]
M[验证参数类型]
N[测试加密功能]
O[测试网络连接]
end

调试配置选项

// 调试模式配置
const debugConfig = {
    // 开启详细日志
    debug: true,
    logLevel: "verbose",
    
    // 开发辅助功能
    enableMock: true,
    mockDelay: 1000,
    
    // 错误监控
    onError: (error) => {
        console.error("配置错误详情:", {
            error: error.message,
            config: error.config,
            stack: error.stack
        });
    }
};

章节来源

依赖关系分析

外部依赖管理

项目依赖关系清晰明确，主要依赖包括：

graph LR
subgraph "核心依赖"
UMI[umi-request@1.4.0]
B64[base64-js@1.5.1]
end
subgraph "内部模块"
HTTP[TsHttpUtil]
CRYPTO[TsCrypto]
GLOBAL[TsGlobalConfig]
SM4[TsSM4]
STORAGE[TsStorage]
COMMON[TsCommon]
end
HTTP --> UMI
CRYPTO --> B64
CRYPTO --> SM4
HTTP --> CRYPTO
HTTP --> STORAGE
HTTP --> GLOBAL
HTTP --> COMMON
GLOBAL --> COMMON
STORAGE --> COMMON

图表来源

内部模块依赖

内部模块之间的依赖关系遵循单一职责原则：

模块	依赖模块	用途
TsHttpUtil	TsCrypto, TsStorage, TsGlobalConfig, TsCommon	HTTP 请求处理
TsCrypto	TsSM4, TsGlobalConfig	数据加密解密
TsStorage	TsCommon	本地存储管理
TsGlobalConfig	TsCommon	全局配置管理

章节来源

性能考虑

加密性能优化

加密操作是影响性能的关键因素，需要考虑以下优化策略：

加密性能指标

操作类型	处理时间	内存占用	推荐场景
小数据加密 (<1KB)	<1ms	<1KB	API 请求
中等数据加密 (1-10KB)	1-5ms	1-10KB	文件上传
大数据加密 (>10KB)	5-50ms	10-50KB	批量数据

性能优化建议

延迟加密：仅对敏感数据进行加密
批量处理：合并多个小请求为批量请求
缓存策略：对不敏感数据使用缓存
异步处理：在后台线程中执行加密操作

网络请求优化

请求优化策略

// 性能优化配置示例
const performanceConfig = {
    // 连接池管理
    maxConnections: 10,
    connectionTimeout: 5000,
    
    // 缓存策略
    cacheStrategy: "smart", // 智能缓存
    cacheTTL: 300000, // 5分钟缓存
    
    // 压缩配置
    enableCompression: true,
    compressionThreshold: 1024,
    
    // 超时配置
    requestTimeout: 10000,
    retryTimeout: 2000,
    
    // 重试策略
    maxRetries: 3,
    retryBackoff: "exponential"
};

故障排除指南

常见配置问题

加密相关问题

问题类型	症状	解决方案
密钥不匹配	加密失败，抛出异常	检查 base64Key 配置
IV 配置错误	CBC 模式加密异常	确认 IV 参数正确设置
模式不兼容	加密/解密失败	确保加密和解密使用相同模式

HTTP 请求问题

问题类型	症状	解决方案
跨域问题	CORS 错误	配置正确的 CORS 头
超时问题	请求超时	调整 timeout 参数
认证失败	401 错误	检查用户令牌配置

存储相关问题

问题类型	症状	解决方案
存储失败	无法保存数据	检查浏览器存储权限
数据丢失	重启后数据消失	确认使用 localStorage
格式错误	JSON 解析失败	检查数据序列化

调试工具和方法

配置调试接口

// 配置状态检查
const checkConfigStatus = () => {
    return {
        globalConfig: TsGlobalConfig.getConfig(),
        encryptionEnabled: TsStorage.getEncryptBody(),
        userToken: TsStorage.getUserToken(),
        storageAvailable: typeof localStorage !== 'undefined'
    };
};

// 加密功能测试
const testEncryption = (testData) => {
    try {
        const encrypted = TsCrypto.encrypt(testData);
        const decrypted = TsCrypto.decrypt(encrypted);
        return {
            success: testData === decrypted,
            original: testData,
            encrypted: encrypted,
            decrypted: decrypted
        };
    } catch (error) {
        return {
            success: false,
            error: error.message
        };
    }
};

日志记录配置

// 详细日志配置
const loggingConfig = {
    enableDebugLogs: true,
    logLevels: ["error", "warn", "info", "debug"],
    logToFile: false,
    logToConsole: true,
    maxLogSize: 10485760, // 10MB
    retentionDays: 7
};

章节来源

结论

npm-tool 工具包提供了完整的配置管理解决方案，具有以下特点：

主要优势

灵活的配置系统：支持多层级配置和动态覆盖
强大的加密能力：基于 SM4 算法的安全数据传输
完善的错误处理：全面的异常捕获和错误恢复机制
环境适配性强：支持开发、测试、生产多环境部署

最佳实践建议

生产环境必须启用加密：确保数据传输安全
合理配置超时参数：平衡用户体验和系统性能
实施适当的缓存策略：提升应用响应速度
建立完善的监控体系：及时发现和解决问题

安全考虑

密钥安全管理：使用环境变量存储敏感配置
传输安全：确保所有数据通过 HTTPS 传输
访问控制：实施严格的权限验证机制
审计日志：记录重要的配置变更和访问行为

通过遵循本指南提供的配置最佳实践，可以确保 npm-tool 工具包在各种使用场景下都能稳定、安全地运行。

17 KiB Raw Blame History

配置指南

目录

简介

项目结构

核心配置组件

全局配置系统

配置结构定义

配置优先级机制

配置设置方法

加密配置系统

加密配置参数

加密流程图

HTTP 请求配置

HTTP 配置参数

请求处理流程

架构概览

整体架构设计

组件交互关系

详细配置分析

开发环境配置

基础开发配置

加密配置建议

生产环境配置

安全生产配置

加密配置要求

不同使用场景的配置示例

移动端应用配置

微服务架构配置

配置验证和调试方法

配置验证流程

调试配置选项

依赖关系分析

外部依赖管理

内部模块依赖

性能考虑

加密性能优化

加密性能指标

性能优化建议

网络请求优化

请求优化策略

故障排除指南

常见配置问题

加密相关问题

HTTP 请求问题

存储相关问题

调试工具和方法

配置调试接口

日志记录配置

结论

主要优势

最佳实践建议

安全考虑

17 KiB

Raw Blame History