docs/v1.0/architecture/changelogs/2026-02-05-api-response-format-fix.md

API 响应格式标准化修复

日期：2026-02-05
类型：Breaking Change Fix
影响范围：全局架构、API 规范、Schema 定义
相关 ADR：ADR 011

---

概述

修复 API 响应格式不一致的问题，统一所有 API 响应为 5 字段格式（success, code, message, data, timestamp）。

---

问题背景

发现的问题

1. 文档不一致

   • API 设计规范定义了完整的 5 字段格式
   • 但多处示例缺少 success 和 timestamp 字段

2. Schema 定义不完整

   • schemas/common.py 中的响应模型只有 3 个字段
   • 导致部分 API 返回不完整的响应

3. 前端已兼容

   • 前端响应拦截器已支持新旧两种格式
   • 无需修改前端代码

---

修复内容

1. 修复文档 ✅

文件：.claude/skills/jointo-tech-stack/references/api-design.md

修复项（共 18 处）：

• 分页响应示例
• 认证相关响应（登录、验证码、微信登录）
• 项目管理响应（列表、创建、删除）
• 积分管理响应（余额、交易记录）
• 附件管理响应（上传、下载）
• 充值管理响应（创建订单、查询状态）
• 错误响应（401、403）

修复前：

{
  "code": 200,
  "message": "Success",
  "data": {...}
}

修复后：

{
  "success": true,
  "code": 200,
  "message": "Success",
  "data": {...},
  "timestamp": "2026-02-05T10:30:00+00:00"
}

2. 修复 Schema 定义 ✅

文件：server/app/schemas/common.py

修复前：

class SuccessResponse(BaseModel, Generic[T]):
    code: int = 200
    message: str = "Success"
    data: Optional[T] = None

修复后：

class SuccessResponse(BaseModel, Generic[T]):
    success: bool = Field(default=True, description="请求是否成功")
    code: int = Field(default=200, description="业务状态码")
    message: str = Field(default="Success", description="响应消息")
    data: Optional[T] = Field(default=None, description="响应数据")
    timestamp: datetime = Field(
        default_factory=lambda: datetime.now(timezone.utc),
        description="响应时间戳"
    )
    
    @field_serializer('timestamp')
    def serialize_timestamp(self, value: datetime) -> str:
        return value.isoformat()

3. 创建 ADR ✅

文件：docs/architecture/adrs/011-api-response-format-standardization.md

记录了：

• 问题背景
• 决策内容
• 实施步骤
• 影响分析
• 实施指南

---

标准响应格式

成功响应

{
  "success": true,
  "code": 200,
  "message": "Success",
  "data": {
    // 业务数据
  },
  "timestamp": "2026-02-05T10:30:00+00:00"
}

错误响应

{
  "success": false,
  "code": 400,
  "message": "错误消息",
  "data": null,
  "timestamp": "2026-02-05T10:30:00+00:00"
}

分页响应

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

---

影响范围

后端 API

• ✅ 无破坏性变更：现有使用 success_response() 的 API 已经返回正确格式
• ✅ 部分修复：使用 SuccessResponse 的 API 现在返回完整格式
• ⚠️ 需要注意：新开发的 API 必须遵循 5 字段格式

已验证的 API：

• api/v1/projects.py ✅
• api/v1/folders.py ✅
• api/v1/auth.py ✅
• api/v1/credits.py ✅（Schema 已修复）

前端

• ✅ 无需修改：前端响应拦截器已兼容新旧格式
• ✅ 向后兼容：旧的 3 字段格式仍可正常工作
• ✅ 自动适配：新格式自动提取 data 字段

前端代码位置：

• client/src/services/api/client.ts (第 42-131 行)

---

开发指南

后端开发者

✅ 推荐做法：

from app.schemas.response import success_response

@router.get("/example")
async def example():
    return success_response(data={"key": "value"})

或

from app.schemas.common import SuccessResponse

@router.get("/example", response_model=SuccessResponse[MyResponse])
async def example():
    return SuccessResponse(data=my_data)

❌ 禁止做法：

# 错误：手动构建不完整的字典
return {"code": 200, "message": "Success", "data": data}

前端开发者

无需修改，响应拦截器自动处理：

// 自动提取 data 字段
const projects = await projectApi.getAll();

// 错误自动抛出
try {
  await api.call();
} catch (error) {
  console.error(error.message);
}

---

检查清单

开发新 API 时确认：

• 使用 success_response() 或 SuccessResponse
• 响应包含 5 个字段：success, code, message, data, timestamp
• response_model 类型正确
• 错误响应也遵循相同格式
• 更新 API 文档

---

相关文件

已修改

• .claude/skills/jointo-tech-stack/references/api-design.md
• server/app/schemas/common.py

已创建

• docs/architecture/adrs/011-api-response-format-standardization.md
• docs/architecture/changelogs/2026-02-05-api-response-format-fix.md

已验证

• server/app/api/v1/projects.py
• server/app/api/v1/folders.py
• server/app/api/v1/auth.py
• server/app/api/v1/credits.py
• client/src/services/api/client.ts

---

后续工作

1. ⚠️ 审查所有 API 路由文件，确保都使用正确格式
2. ⚠️ 更新测试用例，验证响应格式
3. ⚠️ 检查是否有遗漏的文档示例需要修复
4. ✅ 向团队成员宣传新的响应格式规范

---

总结

本次修复确保了：

• ✅ 文档与代码一致
• ✅ 所有 API 返回统一格式
• ✅ 前端无需修改
• ✅ 向后兼容
• ✅ 提供清晰的开发指南

修复完成时间：2026-02-05
负责人：Claude (AI Assistant)
审核状态：待审核