4.4 KiB

Raw Blame History

API 设计规范更新 - 响应格式示例补充

日期: 2026-02-11
类型: 文档更新
影响范围: API 设计规范文档

变更概述

更新 api-design.md 中的响应格式示例，补充完整的后端实现规范，确保文档与实际代码实现一致。

变更内容

1. 补充时间戳序列化说明

之前: 仅说明 timestamp 为 ISO 8601 格式
现在: 明确说明无微秒部分（提高可读性）

- `timestamp`: 响应时间戳，ISO 8601 格式（如 "2026-01-29T12:00:00+00:00"）
+ `timestamp`: 响应时间戳，ISO 8601 格式（如 "2026-01-29T12:00:00+00:00"），**无微秒部分**（为提高可读性）

2. 更新响应模型定义

之前: 使用简化的 ApiResponse 示例
现在: 使用项目实际的 SuccessResponse / ErrorResponse 模型

更新内容:

✅ 使用 app/schemas/common.py 中的实际模型
✅ 补充 @field_serializer 实现细节
✅ 明确时间戳序列化逻辑（移除微秒）

class SuccessResponse(BaseModel, Generic[T]):
    """统一成功响应格式（完整版本，包含 success 和 timestamp）"""
    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:
        """序列化时间戳为 ISO 8601 格式（无微秒）"""
        return value.replace(microsecond=0).isoformat()

3. 修正 API 路由层使用方式

之前: 推荐使用 success_response() 便捷函数
现在: 明确项目中没有便捷函数，直接使用 Pydantic 模型

变更说明:

❌ 移除不存在的 success_response() / error_response() 函数示例
✅ 推荐使用 SuccessResponse(data=...) 实例化
✅ 补充直接返回字典的备选方案

推荐方式:

from app.schemas.common import SuccessResponse

@router.get("/users/me", response_model=SuccessResponse[UserResponse])
async def get_current_user(current_user: User = Depends(get_current_user)):
    return SuccessResponse(data=current_user)  # ✅ 推荐

4. 新增实际使用示例章节

补充三个常见场景的示例代码：

简单成功响应 - 基础用法
自定义消息和状态码 - 创建资源（201）
错误响应 - 通过异常处理器返回

5. 新增时间戳序列化规范章节

补充完整的时间戳处理规范：

✅ 格式要求（ISO 8601 + UTC + 无微秒）
✅ 后端序列化实现
✅ 前端解析示例（TypeScript）
✅ 常见错误对比

示例:

# ✅ 正确：无微秒（推荐）
"2026-02-05T10:30:00+00:00"

# ❌ 错误：包含微秒（不推荐）
"2026-02-05T10:30:00.123456+00:00"

6. 更新分页响应示例

补充使用 PaginatedResponse 的完整代码示例，展示嵌套泛型的用法：

@router.get(
    "/projects",
    response_model=SuccessResponse[PaginatedResponse[ProjectResponse]]
)
async def get_projects(page: int = 1, page_size: int = 20):
    # ...
    return SuccessResponse(data=paginated)

影响范围

文档

✅ .claude/skills/jointo-tech-stack/references/api-design.md

代码

❌ 无代码变更（文档更新）

测试

❌ 无需测试（文档更新）

验证要点

✅ 响应格式示例包含 success 和 timestamp 字段
✅ 后端实现使用项目实际的 SuccessResponse 模型
✅ 时间戳序列化说明完整（无微秒）
✅ 使用示例符合项目实际代码规范
✅ 移除不存在的便捷函数（避免误导）

后续行动

无需后续行动，文档已与代码实现保持一致。

备注

本次更新确保 API 设计规范文档与实际代码实现完全一致，避免开发者因文档过时而产生困惑。

4.4 KiB Raw Blame History