4.3 KiB

Raw Blame History

AI Jobs API 响应格式标准化

日期: 2026-02-11
类型: 重构
影响范围: AI Jobs API (/api/v1/ai/jobs)

变更概述

统一 AI Jobs API 的响应格式，符合项目 API 响应标准规范。

变更详情

1. 导入标准响应类型

# 新增导入
from app.schemas.common import SuccessResponse, PaginatedResponse
from app.core.exceptions import NotFoundError, ValidationError

2. 分页接口标准化

接口: GET /api/v1/ai/jobs

变更前:

response_model=SuccessResponse[dict]

# 返回自定义字典结构
response_data = {
    "items": serialized_items,
    "total": result['total'],
    "page": result['page'],
    "pageSize": result['page_size'],
    "totalPages": result['total_pages']
}

变更后:

response_model=SuccessResponse[PaginatedResponse[AIJobListItemResponse]]

# 使用标准 PaginatedResponse
paginated_data = PaginatedResponse(
    items=serialized_items,
    total=result['total'],
    page=result['page'],
    page_size=result['page_size'],
    total_pages=result['total_pages']
)

3. 异常处理准备

导入自定义异常类，为后续统一异常处理做准备：

NotFoundError - 资源不存在（404）
ValidationError - 数据验证失败（400）

技术细节

响应格式对比

变更前:

{
  "success": true,
  "code": 200,
  "message": "Success",
  "data": {
    "items": [...],
    "total": 100,
    "page": 1,
    "pageSize": 20,
    "totalPages": 5
  },
  "timestamp": "2026-02-11T10:00:00Z"
}

变更后:

{
  "success": true,
  "code": 200,
  "message": "Success",
  "data": {
    "items": [...],
    "total": 100,
    "page": 1,
    "pageSize": 20,
    "totalPages": 5
  },
  "timestamp": "2026-02-11T10:00:00Z"
}

注: 响应结构保持一致，但使用标准 Pydantic 模型确保类型安全和字段验证。

影响评估

前端兼容性

✅ 完全兼容 - 响应 JSON 结构未变化
✅ 字段名保持 camelCase（通过 Pydantic alias 配置）
✅ 所有现有查询参数保持不变

后端改进

✅ 类型安全增强（使用泛型 PaginatedResponse）
✅ 代码一致性提升（与其他 API 保持统一）
✅ 为统一异常处理做准备

测试建议

1. 分页查询测试

# 基础查询
curl -X GET "http://localhost:8000/api/v1/ai/jobs?page=1&pageSize=20"

# 带筛选条件
curl -X GET "http://localhost:8000/api/v1/ai/jobs?jobType=1&status=2&page=1&pageSize=10"

# 时间范围筛选
curl -X GET "http://localhost:8000/api/v1/ai/jobs?startDate=2026-02-01T00:00:00Z&endDate=2026-02-11T23:59:59Z"

# 自定义排序
curl -X GET "http://localhost:8000/api/v1/ai/jobs?orderBy=created_at&orderDesc=false"

2. 验证响应格式

确认 data 字段包含 items, total, page, pageSize, totalPages
确认 items 数组中每个元素符合 AIJobListItemResponse Schema
确认所有字段名为 camelCase

3. 其他接口验证

GET /api/v1/ai/jobs/statistics - 统计信息
GET /api/v1/ai/jobs/usage/stats - 使用统计
GET /api/v1/ai/jobs/{job_id} - 任务详情
POST /api/v1/ai/jobs/{job_id}/cancel - 取消任务

后续优化

统一异常处理: 将 Service 层可能抛出的异常统一转换为自定义异常类
参数验证增强: 考虑添加更多查询参数验证（如日期范围合法性）
性能优化: 对高频查询接口添加缓存机制

检查清单

导入 PaginatedResponse 和自定义异常类
修改 list_user_jobs 使用标准分页响应
保持查询参数 camelCase 支持（alias）
保持其他接口使用 SuccessResponse 标准格式
创建 Changelog 文档
前端验证响应格式兼容性
添加集成测试用例

提交信息

refactor(ai-jobs): 统一 API 响应格式标准

- 使用 PaginatedResponse 标准分页格式
- 导入自定义异常类为后续统一异常处理做准备
- 保持前端完全兼容（响应结构未变化）
- 符合 ADR-001 API 响应格式标准化规范

4.3 KiB Raw Blame History