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

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

## 变更概述

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

## 变更内容

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

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

```diff
- `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` 实现细节
- ✅ 明确时间戳序列化逻辑（移除微秒）

```python
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=...)` 实例化
- ✅ 补充直接返回字典的备选方案

**推荐方式**:
```python
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. 新增实际使用示例章节

补充三个常见场景的示例代码：
1. **简单成功响应** - 基础用法
2. **自定义消息和状态码** - 创建资源（201）
3. **错误响应** - 通过异常处理器返回

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

补充完整的时间戳处理规范：
- ✅ 格式要求（ISO 8601 + UTC + 无微秒）
- ✅ 后端序列化实现
- ✅ 前端解析示例（TypeScript）
- ✅ 常见错误对比

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

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

### 6. 更新分页响应示例

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

```python
@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`

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

### 测试
- ❌ 无需测试（文档更新）

## 验证要点

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

## 后续行动

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

## 相关文档

- [API 设计规范](../../../.claude/skills/jointo-tech-stack/references/api-design.md)
- [后端技术栈规范](../../../.claude/skills/jointo-tech-stack/references/backend.md)
- [通用响应模型](../../../server/app/schemas/common.py)

## 备注

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