签入版本

2026-09-16 10:11:44 +08:00
parent bf08cf1248
commit 20d8a85989
205 changed files with 34363 additions and 0 deletions
@@ -0,0 +1,75 @@
+# 通用 Helper 函数
+
+:::tip 说明
+`src/common/utils/helpers.py` 提供项目中广泛使用的通用工具函数，包括 ID 解析、OS/浏览器检测、参数脱敏等。
+:::
+
+## parse_id_list — ID 列表解析
+
+将逗号分隔的 ID 字符串解析为整数列表：
+
+```python
+from common.utils.helpers import parse_id_list
+
+parse_id_list("1,2,3")
+# 返回: [1, 2, 3]
+
+parse_id_list("1,2,abc,3")
+# 返回: [1, 2, 3]  # 自动跳过非数字项
+
+parse_id_list("")
+# 返回: []
+```
+
+## detect_os — 操作系统检测
+
+从 User-Agent 字符串提取操作系统信息：
+
+```python
+from common.utils.helpers import detect_os
+
+detect_os("Mozilla/5.0 (Windows NT 10.0; Win64; x64) ...")
+# 返回: "Windows 10.0"
+```
+
+支持 Windows、macOS、Android、iOS、Linux 等主流操作系统。
+
+## detect_browser — 浏览器检测
+
+从 User-Agent 字符串提取浏览器信息：
+
+```python
+from common.utils.helpers import detect_browser
+
+detect_browser("Mozilla/5.0 ... Chrome/120.0.0.0 ...")
+# 返回: "Chrome 120.0"
+```
+
+支持 Edge、Chrome、Firefox、Safari、IE 等主流浏览器。Edge 优先匹配，避免被误判为 Chrome。
+
+## redact_params — 参数脱敏
+
+对敏感参数进行脱敏处理，用于操作日志记录：
+
+```python
+from common.utils.helpers import redact_params
+
+params = {"username": "admin", "password": "123456", "name": "张三"}
+redact_params(params)
+# 返回: {"username": "admin", "password": "******", "name": "张三"}
+```
+
+自动对 `password`、`salt`、`token`、`secret` 等敏感字段脱敏。
+
+## 使用场景
+
+| 函数 | 主要使用场景 |
+|:-----|:------------|
+| `parse_id_list` | 批量删除、批量状态变更 |
+| `detect_os` | 操作日志、登录日志 |
+| `detect_browser` | 操作日志、登录日志 |
+| `redact_params` | 操作日志参数记录 |
+
+## 总结
+
+通用 Helper 函数覆盖了 ID 解析、设备检测、参数脱敏等常见场景。这些函数在各业务模块中广泛使用，是项目的基础工具集。