175 lines
4.3 KiB
Markdown
175 lines
4.3 KiB
Markdown
# 技术文档：ID 生成与校验模块
|
||
|
||
---
|
||
|
||
## 概述
|
||
|
||
本模块提供了一套轻量级的 ID 生成、验证码生成与校验功能，适用于需要唯一标识符（ID）并附带简单校验码的场景。模块基于 `nanoid` 库生成短小唯一的 ID，并通过自定义算法生成和验证校验码。
|
||
|
||
---
|
||
|
||
## 依赖库
|
||
|
||
- `uuid`: （当前未实际使用，可移除）
|
||
- `nanoid`: 用于生成短、唯一、URL 安全的 ID
|
||
|
||
> 安装 nanoid：
|
||
> ```bash
|
||
> pip install nanoid
|
||
> ```
|
||
|
||
---
|
||
|
||
## 函数说明
|
||
|
||
### `setNode(n='ff001122334455')`
|
||
|
||
**功能**
|
||
占位函数，预留用于设置节点标识（如分布式系统中的节点 ID），当前为空实现。
|
||
|
||
**参数**
|
||
| 参数 | 类型 | 默认值 | 说明 |
|
||
|------|------|--------|------|
|
||
| `n` | str | `'ff001122334455'` | 节点标识字符串（十六进制格式） |
|
||
|
||
**返回值**
|
||
无
|
||
|
||
**示例**
|
||
```python
|
||
setNode('aa11bb22cc33')
|
||
```
|
||
|
||
> ⚠️ 注意：当前函数体为空（`pass`），仅为未来扩展预留。
|
||
|
||
---
|
||
|
||
### `getID(size=21)`
|
||
|
||
**功能**
|
||
使用 `nanoid` 生成指定长度的唯一 ID。
|
||
|
||
**参数**
|
||
| 参数 | 类型 | 默认值 | 说明 |
|
||
|------|------|--------|------|
|
||
| `size` | int | `21` | 生成 ID 的字符长度 |
|
||
|
||
**返回值**
|
||
- **类型**: `str`
|
||
- **说明**: 返回一个长度为 `size` 的随机、唯一、URL 安全的字符串 ID
|
||
|
||
**示例**
|
||
```python
|
||
id1 = getID() # 例如: "V1StGXR8_Z5jdHi6B-myT"
|
||
id2 = getID(10) # 例如: "kLmNoPqRsT"
|
||
```
|
||
|
||
---
|
||
|
||
### `validate_code(id, cnt=6)`
|
||
|
||
**功能**
|
||
根据输入的 ID 字符串生成一个固定长度的数字验证码。算法将 ID 分成若干段，对每段字符的 ASCII 值求和，并取模 10 得到一位数字。
|
||
|
||
**参数**
|
||
| 参数 | 类型 | 默认值 | 说明 |
|
||
|------|------|--------|------|
|
||
| `id` | str | 必填 | 输入的 ID 字符串 |
|
||
| `cnt` | int | `6` | 期望生成的验证码位数（最多不超过分段数） |
|
||
|
||
**返回值**
|
||
- **类型**: `str`
|
||
- **说明**: 返回由数字组成的验证码字符串，长度为 `cnt`
|
||
|
||
**算法逻辑**
|
||
1. 计算每段长度：`b = len(id) // cnt`
|
||
2. 遍历 `id` 中每个字符，累加其 ASCII 值
|
||
3. 每累计 `b` 个字符后，取总和模 10 作为一位验证码
|
||
4. 达到 `cnt` 位后停止
|
||
|
||
**调试输出**
|
||
- 打印 `b`（每段字符数）和 `cnt`（验证码位数）
|
||
|
||
**示例**
|
||
```python
|
||
code = validate_code("abc123xyz", 3)
|
||
# 假设 b=3，则:
|
||
# 第一段 "abc" -> (97+98+99) % 10 = 294 % 10 = 4
|
||
# 第二段 "123" -> (49+50+51) % 10 = 150 % 10 = 0
|
||
# 第三段 "xyz" -> (120+121+122) % 10 = 363 % 10 = 3
|
||
# 结果: "403"
|
||
```
|
||
|
||
---
|
||
|
||
### `check_code(id, code)`
|
||
|
||
**功能**
|
||
校验给定的验证码是否与 ID 通过 `validate_code` 生成的验证码一致。
|
||
|
||
**参数**
|
||
| 参数 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `id` | str | 原始 ID 字符串 |
|
||
| `code` | str | 待校验的验证码 |
|
||
|
||
**返回值**
|
||
- **类型**: `bool`
|
||
- **说明**: 若验证码匹配返回 `True`，否则返回 `False`
|
||
|
||
**示例**
|
||
```python
|
||
result = check_code("abc123xyz", "403") # 取决于 validate_code 的结果
|
||
print(result) # True 或 False
|
||
```
|
||
|
||
---
|
||
|
||
## 主程序示例（`__main__`）
|
||
|
||
演示了 ID 生成、验证码生成与校验的完整流程。
|
||
|
||
```python
|
||
if __name__ == '__main__':
|
||
id = getID() # 生成 ID
|
||
code = validate_code(id) # 生成验证码
|
||
b = check_code(id, code) # 校验验证码
|
||
print(id, code, b) # 输出 ID、验证码和校验结果
|
||
```
|
||
|
||
**输出示例**
|
||
```
|
||
b=3, cnt=6
|
||
V1StGXR8_Z5jdHi6B-myT 258314 True
|
||
```
|
||
|
||
---
|
||
|
||
## 使用场景
|
||
|
||
- 短链接系统中的唯一 ID 与人工校验码
|
||
- 激活码、邀请码生成与验证
|
||
- 分布式系统中轻量级 ID 校验机制
|
||
|
||
---
|
||
|
||
## 注意事项
|
||
|
||
1. `validate_code` 中的 `print(f'{b=}, {cnt=}')` 为调试信息，生产环境中建议移除或改为日志输出。
|
||
2. 当前 `setNode` 未实现功能，若无需保留可删除。
|
||
3. `uuid` 模块导入但未使用，建议移除以减少冗余依赖。
|
||
4. 校验码算法较为简单，不适用于高安全场景，仅适合防误输或基础校验。
|
||
|
||
---
|
||
|
||
## 未来优化建议
|
||
|
||
- 将校验算法替换为 CRC 或哈希截断以提高健壮性
|
||
- 支持自定义字符集和种子提升安全性
|
||
- 添加异常处理（如空 ID 输入等）
|
||
- 使用 `logging` 替代 `print` 进行调试输出
|
||
|
||
---
|
||
|
||
✅ **版本**: 1.0
|
||
📅 **最后更新**: 2025-04-05 |