# random-string-utils

**Repository Path**: awski/random-string-utils

## Basic Information

- **Project Name**: random-string-utils
- **Description**: 一个功能强大的随机字符串生成工具库，适用于Node.js环境。

## 功能特性

- ✅ 生成各种类型的随机字符串
- ✅ 支持自定义字符类型和长度
- ✅ 包含参数验证和错误处理
- ✅ 支持中文文档
- ✅ 轻量级，无外部依赖
- **Primary Language**: NodeJS
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-10-27
- **Last Updated**: 2025-10-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Random String Utils

一个功能强大的随机字符串生成工具库，适用于Node.js环境。

## 功能特性

- ✅ 生成各种类型的随机字符串
- ✅ 支持自定义字符类型和长度
- ✅ 包含参数验证和错误处理
- ✅ 支持中文文档
- ✅ 轻量级，无外部依赖

## 安装

```bash
npm install random-string-utils
```

## 使用方法

### 基本使用

```javascript
const RandomStringUtils = require('random-string-utils');

// 生成默认16位随机字符串
const randomStr = RandomStringUtils.generateRandomString();
console.log(randomStr); // 输出类似: "aB3#xY8!pQ9$mN2@"

// 生成指定长度的字符串
const customStr = RandomStringUtils.generateRandomString(12);
console.log(customStr); // 输出类似: "kL5#jH8*mN3@"
```

### 高级配置

```javascript
// 自定义字符类型
const customStr = RandomStringUtils.generateRandomString(10, {
    includeUppercase: true,
    includeLowercase: true,
    includeNumbers: true,
    includeSpecialChars: false, // 不包含特殊符号
    customSpecialChars: '+-*/'  // 自定义特殊字符集
});

// 只包含大写字母和数字
const alphanumericStr = RandomStringUtils.generateRandomString(8, {
    includeLowercase: false,
    includeSpecialChars: false
});
```

### 专用方法

```javascript
// 生成只包含字母的字符串
const alphabeticStr = RandomStringUtils.generateAlphabeticString(10);

// 生成只包含数字的字符串
const numericStr = RandomStringUtils.generateNumericString(8);

// 生成字母数字混合字符串
const alphanumericStr = RandomStringUtils.generateAlphanumericString(12);

// 生成强密钥
const strongKey = RandomStringUtils.generateStrongKey(20);

// 打乱字符串顺序
const shuffled = RandomStringUtils.shuffleString('abcdefghij');
```

## API 文档

### `generateRandomString(length = 16, options = {})`

生成指定长度的随机字符串。

**参数:**
- `length` (number): 字符串长度，默认16，范围6-128
- `options` (object): 配置选项
  - `includeUppercase` (boolean): 是否包含大写字母，默认true
  - `includeLowercase` (boolean): 是否包含小写字母，默认true
  - `includeNumbers` (boolean): 是否包含数字，默认true
  - `includeSpecialChars` (boolean): 是否包含特殊符号，默认true
  - `customSpecialChars` (string): 自定义特殊字符集，默认"!@#$%^&*()_+-=[]{}|;:,.<>?"

**返回值:** (string) 生成的随机字符串

### `generateAlphabeticString(length = 16)`

生成只包含字母的随机字符串。

### `generateNumericString(length = 16)`

生成只包含数字的随机字符串。

### `generateAlphanumericString(length = 16)`

生成包含字母和数字的随机字符串。

### `generateStrongKey(length = 16)`

生成用于密钥的强随机字符串。

### `shuffleString(str)`

打乱字符串中字符的顺序。

## 错误处理

库会验证输入参数，并在以下情况下抛出错误：

- 长度不在6-128范围内
- 没有选择任何字符类型
- 参数类型不正确

```javascript
try {
    const result = RandomStringUtils.generateRandomString(5); // 长度过短
} catch (error) {
    console.error(error.message); // "长度必须是6-128之间的整数"
}
```

## 使用场景

- 🔐 密码生成
- 🎫 验证码生成
- 🔑 API密钥生成
- 🆔 唯一标识符生成
- 🎲 随机测试数据生成

## 开发

### 运行测试

```bash
npm test
```

### 构建

无需构建步骤，直接使用源码。

## 许可证

MIT License

## 贡献

欢迎提交Issue和Pull Request！

## 更新日志

### v1.0.0
- 初始版本发布
- 包含完整的随机字符串生成功能
- 支持自定义配置和错误处理