签入版本

2026-09-12 23:12:15 +08:00
commit 91998056ca
1841 changed files with 341325 additions and 0 deletions
@@ -0,0 +1,123 @@
+# 请求解析工具
+
+:::tip 说明
+`src/utils/request.py` 提供请求数据解析相关的工具函数，包括批量 ID 解析、SQL LIKE 安全处理、分页参数解析等。这些工具函数在各业务模块中广泛使用。
+:::
+
+## parse_batch_ids
+
+从请求体解析批量删除的 ID 数组，校验并转为逗号分隔字符串。
+
+```python
+async def parse_batch_ids(request):
+    """
+    请求体格式: [1, 2, 3]
+    返回: (id_str, error_response)
+    成功时 id_str 为 "1,2,3"，error_response 为 None
+    失败时 id_str 为 None，error_response 为 R.failed 响应
+    """
+    ids = await request.json()
+    if not ids or not isinstance(ids, list) or len(ids) == 0:
+        return None, R.failed("参数错误：ids必须为非空数组")
+    try:
+        id_list = [int(id_val) for id_val in ids]
+    except (ValueError, TypeError):
+        return None, R.failed("参数错误：数组元素必须为数字")
+    return ','.join(str(id_val) for id_val in id_list), None
+```
+
+使用示例：
+
+```python
+@router.delete('/batchDelete')
+async def batch_delete(request: Request):
+    id_str, err = await parse_batch_ids(request)
+    if err:
+        return err
+    return position_service.batch_delete_by_ids(id_str)
+```
+
+:::tip 温馨提示
+`parse_batch_ids` 是异步函数（需要 `await request.json()`），因此批量删除端点必须声明为 `async def`。
+:::
+
+## parse_id_list
+
+将逗号分隔的 ID 字符串解析为整数列表。
+
+```python
+def parse_id_list(id_str: str, separator: str = ',') -> list:
+    """
+    示例:
+    >>> parse_id_list("1,2,3")
+    [1, 2, 3]
+    >>> parse_id_list("1,2,abc,3")
+    [1, 2, 3]  # 自动跳过非数字项
+    """
+```
+
+## like_escape
+
+转义 SQL LIKE 通配符，防止用户输入被当作通配符。
+
+```python
+def like_escape(value, escape_char='\\'):
+    """
+    示例:
+    >>> like_escape('100%')
+    '100\\%'
+    >>> like_escape('test_data')
+    'test\\_data'
+    """
+    escaped = str(value).replace(escape_char, escape_char * 2)
+    escaped = escaped.replace('%', escape_char + '%')
+    escaped = escaped.replace('_', escape_char + '_')
+    return escaped
+```
+
+## like_contains
+
+构建安全的 LIKE 包含查询值（前后加 `%`）。
+
+```python
+def like_contains(value, escape_char='\\'):
+    """
+    SQLAlchemy 用法:
+    query = query.filter(User.name.like(like_contains(name), escape='\\\\'))
+    """
+    return f'%{like_escape(value, escape_char)}%'
+```
+
+## parse_pagination
+
+安全解析分页参数 `pageNo` / `pageSize`。
+
+```python
+def parse_pagination(request, default_page_size: int = PAGE_SIZE, max_page_size: int = 500) -> tuple:
+    """
+    非数字、小于1、超上限等一律回退/夹取
+    返回: (page, page_size)，page>=1，1<=page_size<=max_page_size
+    """
+```
+
+## get_json_data
+
+从 FastAPI 请求中解析 JSON 数据。
+
+```python
+async def get_json_data(request, required=True):
+ """获取请求中的 JSON 数据，失败返回 None 或空字典"""
+```
+
+## parse_request_body
+
+解析请求体 JSON 数据，返回 `(data, error)` 元组。
+
+```python
+async def parse_request_body(request):
+ """成功时 data 为字典，error 为 None；失败时 data 为 None，error 为错误描述"""
+```
+
+## 总结
+
+请求解析工具函数覆盖了批量操作、模糊查询安全、分页参数等常见场景。`parse_batch_ids` 和 `parse_pagination` 通过防御性校验避免畸形参数导致 500 错误，`like_escape` 防止 LIKE 通配符注入。