docs/v1.0/server/changelogs/2026-01-26-unified-api-response.md

Changelog: 统一 API 响应格式

日期: 2026-01-26
类型: 重构
影响: Breaking Change

变更概述

实施统一的 API 响应格式，所有接口现在返回包含 code、message、data 的标准结构。

变更详情

新增文件

• server/app/schemas/response.py - 统一响应模型和辅助函数

修改文件

• server/app/schemas/__init__.py - 导出响应相关类
• server/app/api/v1/health.py - 2 个接口
• server/app/api/v1/auth.py - 2 个接口
• server/app/api/v1/users.py - 2 个接口
• server/app/api/v1/folders.py - 15 个接口
• server/app/api/v1/projects.py - 20 个接口（删除重复定义）
• server/app/api/v1/ai.py - 10 个接口

总计: 51+ 个接口

Breaking Changes

响应格式变更

之前:

{
  "items": [...],
  "total": 100
}

现在:

{
  "code": 200,
  "message": "Success",
  "data": {
    "items": [...],
    "total": 100
  }
}

前端迁移指南

修改前:

const response = await api.getProjects()
console.log(response.items)

修改后:

const response = await api.getProjects()
console.log(response.data.items)

API 客户端更新

如果使用 TanStack Query，需要更新数据提取逻辑：

// 修改前
const { data } = useQuery({
  queryKey: ['projects'],
  queryFn: () => api.getProjects()
})
// data.items

// 修改后
const { data } = useQuery({
  queryKey: ['projects'],
  queryFn: () => api.getProjects()
})
// data.data.items

新增功能

统一响应模型

from app.schemas.response import ApiResponse, success_response

@router.get("", response_model=ApiResponse[ProjectListResponse])
async def get_projects(...):
    result = await service.get_projects(...)
    return success_response(data=result)

便捷函数

# 成功响应
success_response(data=result, message="操作成功", code=200)

# 错误响应
error_response(message="验证失败", code=400, errors=[...])

修复问题

• 删除 projects.py 中重复的路由定义（delete、restore、permanent_delete）
• 统一所有接口的返回格式
• 符合 api-design.md 规范要求

测试建议

1. 验证所有接口返回格式正确
2. 检查前端 API 调用是否正常
3. 确认错误响应格式一致
4. 测试分页、列表、详情等各种场景

相关文档

• RFC 135: 统一 API 响应格式
• api-design.md - API 设计规范