简道云fastapi

2025-11-07 17:48:49 +08:00
commit 073f0646a1
30 changed files with 5933 additions and 0 deletions
@@ -0,0 +1,186 @@
+# API模块更新说明
+
+## 更新内容
+
+根据 `fastapi_app/api.py`（最新版）更新了 `fastapi_app/app/api.py`，主要更新包括：
+
+### 1. 添加失败重试机制
+
+所有API函数都已添加重试机制，参考 `entry_data_list` 的实现模式：
+
+- **默认重试次数**：20次（部分函数为10次）
+- **重试逻辑**：
+  - 捕获 `requests.exceptions.RequestException` 异常
+  - 重试前等待时间：0.1秒（快速请求）或3-10秒（慢速请求）
+  - 超过最大重试次数后记录错误日志并返回None或抛出异常
+
+### 2. 新增功能函数
+
+添加了以下新函数（原版本中没有的）：
+
+- `entry_data_banch_update()` - 批量修改数据
+- `entry_data_delete()` - 删除单条数据
+- `entry_data_batch_delete()` - 批量删除数据
+- `workflow_task_hand_over()` - 流程待办转交
+- `get_upload_token()` - 获取文件上传凭证
+- `upload_file()` - 上传文件
+
+### 3. 功能增强
+
+- **`entry_data_get()`**：
+  - 添加 `replace` 参数（默认True，保持向后兼容）
+  - 添加 `max_retries` 参数
+  - 添加重试机制
+
+- **`entry_data_list()`**：
+  - 添加 `replace` 参数（默认True，保持向后兼容）
+  - 添加 `max_retries` 参数
+  - 改进重试逻辑，支持分页重试
+
+- **`entry_widget_list()`**：
+  - 添加 `max_retries` 参数
+  - 添加重试机制
+
+- **`data_batch_create()`**：
+  - 添加 `max_retries` 参数
+  - 添加重试机制
+  - 支持 `is_start_workflow`、`is_start_trigger`、`transaction_id` 参数
+
+- **`entry_data_batch_create()`**：
+  - 添加 `max_retries` 参数
+  - 添加重试机制
+  - 支持 `is_start_workflow`、`is_start_trigger` 参数
+  - 使用 `NpEncoder` 处理NumPy数据类型
+
+- **`entry_data_update()`**：
+  - 添加 `max_retries` 参数
+  - 添加重试机制
+
+- **`workflow_instance_get()`**：
+  - 添加 `max_retries` 参数
+  - 添加重试机制
+
+- **`workflow_task_approve()`**：
+  - 添加 `max_retries` 参数
+  - 添加重试机制
+  - `comment` 参数支持自定义（默认"自动转交"）
+
+### 4. 工具函数
+
+- **`NpEncoder`**：JSON编码器，处理NumPy数据类型
+- **`replace_decimals()`**：递归替换Decimal类型为float
+
+### 5. 字段替换优化
+
+`field_replacement()` 方法使用递归实现，更优雅地处理嵌套数据结构。
+
+## 兼容性保证
+
+### 向后兼容
+
+1. **默认参数**：
+   - `entry_data_get()` 和 `entry_data_list()` 的 `replace` 参数默认为 `True`，保持原有行为
+   - 所有新增的 `max_retries` 参数都有合理的默认值
+
+2. **导入路径**：
+   - 使用 `from app.config import Config`（而非 `from config import Config`）
+   - 使用 `logging.getLogger('app')`（而非 `log_config`）
+
+3. **函数签名**：
+   - 所有原有函数的调用方式保持不变
+   - 新增参数都是可选参数
+
+### 日志系统
+
+- 使用 `logging.getLogger('app')` 作为常规日志记录器
+- 使用 `logging.getLogger('app.error')` 作为错误日志记录器
+- 与 fastapi_app 项目的日志系统完全兼容
+
+## 使用示例
+
+### 基本使用（保持原有方式）
+
+```python
+from app.api import API
+
+api = API()
+
+# 获取单条数据（自动替换字段）
+data = api.entry_data_get({
+    'api_key': 'xxx',
+    'entry_id': 'xxx',
+    'data_id': 'xxx'
+})
+
+# 获取多条数据（自动替换字段）
+data_list = api.entry_data_list({
+    'api_key': 'xxx',
+    'entry_id': 'xxx'
+})
+```
+
+### 使用新功能
+
+```python
+# 不替换字段
+data = api.entry_data_get({
+    'api_key': 'xxx',
+    'entry_id': 'xxx',
+    'data_id': 'xxx'
+}, replace=False)
+
+# 自定义重试次数
+data = api.entry_data_get({
+    'api_key': 'xxx',
+    'entry_id': 'xxx',
+    'data_id': 'xxx'
+}, max_retries=10)
+
+# 批量删除
+result = api.entry_data_batch_delete({
+    'api_key': 'xxx',
+    'entry_id': 'xxx',
+    'data_ids': ['id1', 'id2', 'id3']
+}, chunk_size=90, max_retries=20)
+```
+
+## 重试机制说明
+
+### 重试策略
+
+1. **快速请求**（0.1秒延迟）：
+   - `entry_data_list()` - 分页请求
+   - `entry_data_batch_create()` - 批量创建
+   - `entry_data_batch_delete()` - 批量删除
+   - `workflow_instance_get()` - 流程查询
+
+2. **慢速请求**（3-10秒延迟）：
+   - `data_batch_create()` - 3秒延迟
+   - `entry_data_update()` - 10秒延迟
+   - `entry_data_banch_update()` - 10秒延迟
+   - `entry_data_delete()` - 10秒延迟
+   - `workflow_task_approve()` - 3秒延迟
+   - `workflow_task_hand_over()` - 3秒延迟
+   - `get_upload_token()` - 3秒延迟
+   - `upload_file()` - 3秒延迟
+
+### 错误处理
+
+- 所有重试失败的操作都会记录到错误日志
+- 部分函数在重试失败后返回 `None`，部分会抛出异常
+- 错误日志包含失败的任务标识信息
+
+## 注意事项
+
+1. **超时设置**：所有请求都设置了 `timeout=10` 秒
+2. **状态码检查**：使用 `res.raise_for_status()` 检查HTTP状态码
+3. **文件上传**：`upload_file()` 使用 `with` 语句确保文件正确关闭
+4. **数据类型处理**：批量操作函数使用 `NpEncoder` 和 `replace_decimals()` 处理特殊数据类型
+
+## 测试建议
+
+1. 测试所有原有功能的兼容性
+2. 测试新添加的函数
+3. 测试重试机制（可以模拟网络错误）
+4. 测试 `replace=False` 参数的使用
+