187 lines
5.1 KiB
Markdown
187 lines
5.1 KiB
Markdown
# 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` 参数的使用
|
||
|