149 lines
6.5 KiB
Markdown
149 lines
6.5 KiB
Markdown
# @tiesheng/npm-tool
|
||
|
||
> 杭州铁晟前端通用基类工具库，封装了 HTTP 请求、SM4 国密加解密、本地存储、全局配置以及常用工具方法，便于业务项目快速接入。
|
||
|
||
- **当前版本**：2.0.6
|
||
- **仓库地址**：<https://git.tieshengkeji.com/tieshengkeji/npm-tool>
|
||
- **作者**：zeng_wenhao
|
||
- **License**：ISC
|
||
|
||
> 📚 本项目已生成完整的 RepoWiki 文档，下文所有章节均可直接跳转到详细文档。完整入口：[`.qoder/repowiki/zh/content`](./.qoder/repowiki/zh/content)
|
||
|
||
---
|
||
|
||
## 特性
|
||
|
||
- 📡 基于 [umi-request](https://github.com/umijs/umi-request) 的统一 HTTP 请求封装，内置错误码映射、分页参数与 `equals` 参数自动处理。
|
||
- 🔐 内置 SM4 国密算法加解密（ECB 模式，base64 输出），请求体可按开关自动加密。
|
||
- 🔑 统一 Token 读写与请求头注入。
|
||
- 💾 简化的 localStorage 封装，统一以 `{data: value}` 结构存取。
|
||
- ⚙️ 全局配置中心，支持 `prefix`、`base64Key`、统一异常回调、请求额外参数。
|
||
- 🧰 常用工具方法：URL 参数解析、空值判断、JSON 安全解析、字符串处理等。
|
||
|
||
## 安装
|
||
|
||
### 1. 配置私有 npm 仓库
|
||
|
||
本包托管在公司 Gitea 私有 registry，需在项目根目录（或用户目录）的 `.npmrc` 中增加如下配置：
|
||
|
||
```ini
|
||
@tiesheng:registry=https://git.tieshengkeji.com/api/packages/tieshengkeji/npm/
|
||
```
|
||
|
||
> 该配置将 `@tiesheng` 作用域下的包解析指向私有仓库，其它包仍走默认 registry，不影响现有依赖。
|
||
|
||
### 2. 安装依赖
|
||
|
||
```bash
|
||
npm install @tiesheng/npm-tool
|
||
# 或
|
||
yarn add @tiesheng/npm-tool
|
||
```
|
||
|
||
更多安装与上手细节见 👉 [快速开始](./.qoder/repowiki/zh/content/快速开始.md)。
|
||
|
||
## 快速开始
|
||
|
||
```js
|
||
import {
|
||
TsHttpUtil,
|
||
TsGlobalConfig,
|
||
TsStorage,
|
||
TsCrypto,
|
||
TsCommon,
|
||
TsSM4,
|
||
} from '@tiesheng/npm-tool';
|
||
|
||
// 1. 初始化全局配置（建议在应用入口处调用一次）
|
||
TsGlobalConfig.setConfig({
|
||
prefix: '/api', // 请求前缀，也可传函数
|
||
base64Key: 'WmdUzPJXbngVNiaSsQrihg==', // SM4 密钥（base64）
|
||
onHttpError: (res) => {
|
||
console.error('请求异常：', res.message);
|
||
},
|
||
httpParams: () => ({
|
||
// 每次请求自动追加的额外参数（GET 拼到 query，POST 合并到 body）
|
||
clientType: 'web',
|
||
}),
|
||
});
|
||
|
||
// 2. 登录后保存 token（后续请求会自动带上 token 请求头）
|
||
TsStorage.saveUserToken('your-token');
|
||
|
||
// 3. 发起请求
|
||
const { data } = await TsHttpUtil.post('/user/info', { id: 1 });
|
||
```
|
||
|
||
## 项目概述
|
||
|
||
- [项目概述](./.qoder/repowiki/zh/content/项目概述.md)
|
||
- [快速开始](./.qoder/repowiki/zh/content/快速开始.md)
|
||
|
||
## 核心模块
|
||
|
||
> 源码入口：[`index.js`](./index.js)，统一导出 `TsHttpUtil / TsCommon / TsStorage / TsSM4 / TsCrypto / TsGlobalConfig`。
|
||
|
||
| 模块 | 源码 | 文档 |
|
||
| --- | --- | --- |
|
||
| HTTP 请求模块 | [`src/https/TsHttpUtil.js`](./src/https/TsHttpUtil.js) | [HTTP 请求模块 (TsHttpUtil)](./.qoder/repowiki/zh/content/核心模块/HTTP%20请求模块%20%28TsHttpUtil%29.md) |
|
||
| 加密模块 | [`src/utils/TsCrypto.js`](./src/utils/TsCrypto.js) | [加密模块 (TsCrypto)](./.qoder/repowiki/zh/content/核心模块/加密模块%20%28TsCrypto%29.md) |
|
||
| SM4 算法模块 | [`src/utils/TsSM4.js`](./src/utils/TsSM4.js) | [SM4 算法模块 (TsSM4)](./.qoder/repowiki/zh/content/核心模块/SM4%20算法模块%20%28TsSM4%29.md) |
|
||
| 存储模块 | [`src/utils/TsStorage.js`](./src/utils/TsStorage.js) | [存储模块 (TsStorage)](./.qoder/repowiki/zh/content/核心模块/存储模块%20%28TsStorage%29.md) |
|
||
| 通用工具模块 | [`src/utils/TsCommon.js`](./src/utils/TsCommon.js) | [通用工具模块 (TsCommon)](./.qoder/repowiki/zh/content/核心模块/通用工具模块%20%28TsCommon%29.md) |
|
||
| 全局配置模块 | [`src/utils/TsGlobalConfig.js`](./src/utils/TsGlobalConfig.js) | [全局配置模块 (TsGlobalConfig)](./.qoder/repowiki/zh/content/核心模块/全局配置模块%20%28TsGlobalConfig%29.md) |
|
||
|
||
模块总览：[核心模块.md](./.qoder/repowiki/zh/content/核心模块/核心模块.md)
|
||
|
||
## API 参考手册
|
||
|
||
- [API 参考手册（总览）](./.qoder/repowiki/zh/content/API%20参考手册/API%20参考手册.md)
|
||
- [HTTP 请求 API](./.qoder/repowiki/zh/content/API%20参考手册/HTTP%20请求%20API.md)
|
||
- [加密解密 API](./.qoder/repowiki/zh/content/API%20参考手册/加密解密%20API.md)
|
||
- [SM4 算法 API](./.qoder/repowiki/zh/content/API%20参考手册/SM4%20算法%20API.md)
|
||
- [存储管理 API](./.qoder/repowiki/zh/content/API%20参考手册/存储管理%20API.md)
|
||
- [通用工具 API](./.qoder/repowiki/zh/content/API%20参考手册/通用工具%20API.md)
|
||
- [配置管理 API](./.qoder/repowiki/zh/content/API%20参考手册/配置管理%20API.md)
|
||
|
||
## 配置指南
|
||
|
||
- [配置指南（总览）](./.qoder/repowiki/zh/content/配置指南/配置指南.md)
|
||
- [全局配置](./.qoder/repowiki/zh/content/配置指南/全局配置.md)
|
||
- [HTTP 请求配置](./.qoder/repowiki/zh/content/配置指南/HTTP%20请求配置.md)
|
||
- [加密配置](./.qoder/repowiki/zh/content/配置指南/加密配置.md)
|
||
- [存储配置](./.qoder/repowiki/zh/content/配置指南/存储配置.md)
|
||
|
||
## 故障排除
|
||
|
||
- [故障排除（总览）](./.qoder/repowiki/zh/content/故障排除/故障排除.md)
|
||
- [网络请求问题](./.qoder/repowiki/zh/content/故障排除/网络请求问题.md)
|
||
- [加密解密问题](./.qoder/repowiki/zh/content/故障排除/加密解密问题.md)
|
||
- [存储访问问题](./.qoder/repowiki/zh/content/故障排除/存储访问问题.md)
|
||
- [配置问题](./.qoder/repowiki/zh/content/故障排除/配置问题.md)
|
||
- [调试工具和方法](./.qoder/repowiki/zh/content/故障排除/调试工具和方法.md)
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
npm-tool
|
||
├── index.js # 统一出口
|
||
├── src
|
||
│ ├── https
|
||
│ │ └── TsHttpUtil.js # HTTP 请求封装（基于 umi-request）
|
||
│ └── utils
|
||
│ ├── TsCommon.js # 通用工具
|
||
│ ├── TsCrypto.js # SM4 加解密门面
|
||
│ ├── TsGlobalConfig.js# 全局配置（挂载在 window.httpConfig）
|
||
│ ├── TsSM4.js # SM4 算法实现
|
||
│ └── TsStorage.js # localStorage 封装
|
||
└── .qoder/repowiki/zh # 项目 Wiki 文档
|
||
```
|
||
|
||
## 依赖
|
||
|
||
- [`umi-request`](https://www.npmjs.com/package/umi-request) `1.4.0`
|
||
- [`base64-js`](https://www.npmjs.com/package/base64-js) `1.5.1`
|
||
|
||
---
|
||
|
||
如在使用过程中遇到问题，可先查阅 [故障排除](./.qoder/repowiki/zh/content/故障排除/故障排除.md) 文档，或联系仓库维护者。
|