4.4 KiB

Raw Blame History

RFC 135: 统一 API 响应格式

状态: 已实施
创建日期: 2026-01-26
作者: Kiro AI
类型: 重构

概述

实施统一的 API 响应格式，确保所有接口返回一致的数据结构，符合 api-design.md 规范要求。

背景

问题

当前所有 API 接口直接返回数据，未使用统一的响应包装格式：

# 当前实现
@router.get("/projects")
async def get_projects(...):
    return {"items": [...], "total": 100}  # 直接返回

规范要求

根据 api-design.md，所有接口应返回统一格式：

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

解决方案

1. 创建统一响应模型

文件: server/app/schemas/response.py

from typing import Generic, TypeVar, Optional
from pydantic import BaseModel

T = TypeVar('T')

class ApiResponse(BaseModel, Generic[T]):
    """统一 API 响应格式"""
    code: int = 200
    message: str = "Success"
    data: Optional[T] = None

def success_response(data=None, message="Success", code=200):
    """便捷函数：创建成功响应"""
    return {"code": code, "message": message, "data": data}

def error_response(message, code=400, data=None, errors=None):
    """便捷函数：创建错误响应"""
    return {"code": code, "message": message, "data": data, "errors": errors}

2. 修改所有路由

修改前:

@router.get("", response_model=ProjectListResponse)
async def get_projects(...):
    result = await service.get_projects(...)
    return result

修改后:

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)

实施范围

修改的文件

新增:

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+ 个接口

修改模式

添加导入:

from app.schemas.response import ApiResponse, success_response

更新 response_model:

response_model=ApiResponse[OriginalSchema]

包装返回值:
```
return success_response(data=result)
```

响应格式示例

成功响应

单个对象:

{
  "code": 200,
  "message": "Success",
  "data": {
    "id": "123",
    "name": "项目名称"
  }
}

列表响应:

{
  "code": 200,
  "message": "Success",
  "data": {
    "items": [...],
    "total": 100,
    "page": 1,
    "pageSize": 20,
    "totalPages": 5
  }
}

简单消息:

{
  "code": 200,
  "message": "Success",
  "data": {
    "message": "操作成功"
  }
}

错误响应

{
  "code": 400,
  "message": "验证失败",
  "data": null,
  "errors": [
    {
      "field": "name",
      "message": "名称不能为空"
    }
  ]
}

影响分析

前端影响