ccdi/form-data修复说明.md

📋 Form-Data 修复说明

修复日期

2026-03-03

问题描述

原代码中使用 JSON body 方式传输参数，但接口文档要求使用 form-data (application/x-www-form-urlencoded) 方式传输。

修复内容

1. 修改接口参数接收方式

将所有接口从 json= 改为 data= 或 Form=

修改的文件：

• routers/api.py - 所有接口改为使用 Form 参数

• models/request.py - 更新请求模型

• tests/ - 所有测试代码更新为使用 data 参数

• README.md - 更新示例代码

2. 修改的接口

接口1: 获取Token

• 修改前: 使用 json=GetTokenRequest 接收 JSON body
• 修改后: 使用 Form 参数分别接收每个字段

# 修改前
async def get_token(request: GetTokenRequest):
    ...

# 修改后
async def get_token(
    projectNo: str = Form(...),
    entityName: str = Form(...),
    userId: str = Form(...),
    # ... 其他参数
):
    # 构建请求对象
    request = GetTokenRequest(...)
    ...

接口3: 拉取行内流水

• 修改前: 使用 json=FetchInnerFlowRequest
• 修改后: 使用 Form 参数

接口4: 检查解析状态

• 修改前: 使用 json=CheckParseStatusRequest
• 修改后: 使用 Form 参数

接口5: 删除文件

• 修改前: 使用 json=DeleteFilesRequest
• 修改后: 使用 Form 参数
• 特殊处理: logIds 从数组改为逗号分隔的字符串

# 前端传递: logIds=10001,10002,10003
# 后端处理:
log_id_list = [int(id.strip()) for id in logIds.split(",")]

接口6: 获取银行流水

• 修改前: 使用 json=GetBankStatementRequest
• 修改后: 使用 Form 参数

3. 测试代码更新

所有测试从 json= 改为 data=

# 修改前
response = client.post("/account/common/getToken", json=request_data)

# 修改后
response = client.post("/account/common/getToken", data=request_data)

4. 文档更新

README.md 中的示例代码更新为使用 data= 参数:

# 修改前
json={
    "projectNo": "test_project_001",
    ...
}

# 修改后
data={
    "projectNo": "test_project_001",
    ...
}

测试结果

✅ 所有测试通过 (7/7)

======================== 7 passed, 1 warning in 0.08s =========================

使用示例

curl 请求

# 使用 form-data 方式
curl -X POST http://localhost:8000/account/common/getToken \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "projectNo=test_project_001" \
  -d "entityName=测试企业" \
  -d "userId=902001" \
  -d "userName=902001" \
  -d "appId=remote_app" \
  -d "appSecretCode=your_secret_code" \
  -d "role=VIEWER" \
  -d "orgCode=902000" \
  -d "departmentCode=902000"

Python requests 请求

# 使用 form-data 方式
response = requests.post(
    "http://localhost:8000/account/common/getToken",
    data={
        "projectNo": "test_project_001",
        "entityName": "测试企业",
        "userId": "902001",
        "userName": "902001",
        "appId": "remote_app",
        "appSecretCode": "your_secret_code",
        "role": "VIEWER",
        "orgCode": "902000",
        "departmentCode": "902000"
    }
)

注意事项

1. Content-Type: 所有接口现在使用 application/x-www-form-urlencoded
2. 数组参数: 如 logIds 需要传递逗号分隔的字符串，如: "10001,10002,10003"
3. 可选参数: 可选参数可以不传或传空值
4. 测试验证: 所有 7 个测试用例全部通过

影响范围

• ✅ 不向后兼容
• ⚠️ 所有调用这些接口的客户端需要更新为使用 form-data 方式
• ⚠️ Swagger UI 会自动显示正确的参数格式

修复验证

• 修改所有接口使用 Form 参数
• 更新所有测试代码
• 运行测试通过 (7/7)
• 创建修复文档

修复状态

✅ 已完成 - 所有接口已改为 form-data 方式，测试全部通过