npm package: @lpc/miniprogram-utils
Description: 微信小程序工具库
Author: lpc
Latest version: 1.0.0

# @lpc/miniprogram-utils

微信小程序工具库，提供常用工具函数，包含简化版ID生成功能和token认证功能。

## 安装

使用 npm 安装：

```bash
npm install @lpc/miniprogram-utils --save
```

在微信小程序中使用 npm 包需要先进行构建：
1. 点击微信开发者工具顶部菜单栏中的「工具」->「构建 npm」
2. 勾选「使用 npm 模块」选项

## 功能特性

### 简化版ID生成器

使用时间戳 + 4位随机数生成唯一ID，简单高效：

- **高性能**：生成速度快，无复杂计算
- **唯一性**：基于系统时间戳确保基本的时间顺序性
- **简单易用**：API简洁，易于集成
- **ID解析**：支持从生成的ID中解析出原始时间戳

### Token认证功能

提供登录态token的生成和验证功能：

- **安全可靠**：使用HMAC-SHA256算法进行签名
- **有效期控制**：支持设置token有效期
- **完整性验证**：防止token被篡改
- **用户标识**：基于openid生成，便于用户识别

## 目录结构

```
├── index.js                # 主入口文件
├── utils/
│   ├── snowflake/          # ID生成模块
│   │   ├── index.js        # ID生成入口
│   │   └── snowflake.js    # ID生成实现
│   └── token.js            # Token认证模块
├── package.json
└── README.md
```

## 使用示例

### 基本使用 - ID生成

```javascript
const utils = require('@lpc/miniprogram-utils');

// 生成唯一ID（时间戳 + 4位随机数）
const uniqueId = utils.nextId();
console.log('生成的唯一ID:', uniqueId);

// 解析ID，获取时间戳等信息
const parsed = utils.parseId(uniqueId);
console.log('解析结果:', parsed);
console.log('生成时间:', new Date(parsed.timestamp).toLocaleString());
```

### Token认证功能使用

```javascript
const utils = require('@lpc/miniprogram-utils');

// 生成token（基于用户openid）
const openid = 'user123';
const token = utils.generateToken(openid);
console.log('生成的token:', token);

// 解析并验证token
const result = utils.parseToken(token);
if (result.valid) {
  console.log('Token验证成功，用户openid:', result.openid);
} else {
  console.log('Token验证失败:', result.message);
}
```

### 直接使用具体模块

```javascript
// 直接导入ID生成模块
const { nextId, parseId } = require('@lpc/miniprogram-utils/utils/snowflake');

// 直接导入Token模块
const { generateToken, parseToken } = require('@lpc/miniprogram-utils/utils/token');

// 使用ID生成功能
const id = nextId();
const parsedId = parseId(id);

// 使用Token功能
const userToken = generateToken('user456');
const tokenResult = parseToken(userToken);
```

## API 文档

### 1. ID生成功能

#### nextId()

生成唯一ID（时间戳 + 4位随机数）。

- **返回值**: (String) 生成的唯一ID字符串

#### parseId(id)

解析生成的ID，提取时间戳信息。

- **id** (String): 生成的ID字符串
- **返回值**: (Object) 解析后的信息
  - **timestamp**: 原始时间戳
  - **random**: 随机数部分
  - **date**: ISO格式的日期字符串
- **抛出**: 当ID格式无效时抛出错误

### 2. Token认证功能

#### generateToken(openid)

生成登录态token。

- **openid** (String): 用户的openid
- **返回值**: (String) 生成的token字符串，格式为 `openid-timestamp-hash`

#### parseToken(token)

解析并验证token。

- **token** (String): 要验证的token字符串
- **返回值**: (Object) 验证结果
  - **valid** (Boolean): token是否有效
  - **openid** (String, 仅当valid为true时存在): 用户的openid
  - **message** (String, 仅当valid为false时存在): 错误信息

### 注意事项

1. **Token密钥**: 当前使用硬编码的密钥'your_secret_key'，生产环境中建议使用环境变量存储密钥
2. **Token有效期**: 默认设置为7天，可根据需要在generateToken函数中调整
3. **ID唯一性**: 在高并发场景下，同一毫秒内可能生成相同的ID，如需更高唯一性保障，请考虑其他方案

## 安全建议

1. **Token密钥管理**: 生产环境中应使用环境变量或安全的密钥管理服务存储密钥，避免硬编码

2. **密钥轮换**: 定期更换token签名密钥，提高安全性

3. **HTTPS传输**: 确保token在网络传输中使用HTTPS，防止中间人攻击

4. **Token存储**: 客户端存储token时应选择安全的方式，避免明文存储

5. **ID长度考虑**: 生成的ID可能较长，在存储和传输时注意数据类型限制

## 版本控制

使用以下命令精确控制版本升级：

```bash
# 升级主版本号（不兼容的API变更），如 1.0.0 → 2.0.0
npm run version:major

# 升级次版本号（向后兼容的功能添加），如 1.0.0 → 1.1.0
npm run version:minor

# 升级修订版本号（向后兼容的问题修正），如 1.0.0 → 1.0.1
npm run version:patch
```

## 发布包

```bash
# 升级版本（根据需要选择）
npm run version:major   # 如 1.0.0 → 2.0.0
# 或
npm run version:minor   # 如 1.0.0 → 1.1.0
# 或
npm run version:patch   # 如 1.0.0 → 1.0.1

# 发布包
npm run publish:package
```

## 贡献指南

欢迎提交Issue和Pull Request来改进这个库。

## 许可证

MIT