# 响应格式规范

::: info 统一响应格式

本文档定义了 wwjcloud 框架的统一响应格式，确保所有 API 返回的数据格式一致。

:::

## 响应结构

### 📊 基础响应格式

所有 API 响应都遵循以下统一格式：

```typescript
interface ApiResponse<T = any> {
  code: number;        // 状态码
  message: string;     // 消息
  data: T;            // 数据
  timestamp: number;   // 时间戳
}
```

## 响应类型

### ✅ 成功响应

**基础成功响应：**
```json
{
  "code": 200,
  "message": "操作成功",
  "data": null,
  "timestamp": 1640995200
}
```

**返回单个对象：**
```json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "id": 123,
    "username": "john_doe",
    "email": "john@example.com",
    "status": 1
  },
  "timestamp": 1640995200
}
```

**返回列表数据：**
```json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "list": [
      {
        "id": 123,
        "username": "john_doe",
        "email": "john@example.com"
      }
    ],
    "total": 100,
    "page": 1,
    "size": 10
  },
  "timestamp": 1640995200
}
```

### ❌ 错误响应

**参数错误：**
```json
{
  "code": 400,
  "message": "请求参数错误",
  "data": null,
  "timestamp": 1640995200
}
```

**未授权访问：**
```json
{
  "code": 401,
  "message": "未授权访问",
  "data": null,
  "timestamp": 1640995200
}
```

**资源不存在：**
```json
{
  "code": 404,
  "message": "资源不存在",
  "data": null,
  "timestamp": 1640995200
}
```

## 状态码规范

### 📋 状态码定义

**成功状态码：**
```typescript
200: '操作成功'
201: '创建成功'
204: '删除成功'
```

**客户端错误：**
```typescript
400: '请求参数错误'
401: '未授权访问'
403: '禁止访问'
404: '资源不存在'
409: '资源冲突'
422: '请求格式正确但语义错误'
```

**服务器错误：**
```typescript
500: '服务器内部错误'
502: '网关错误'
503: '服务不可用'
```

## 分页响应

### 📄 分页格式

**标准分页响应：**
```json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "list": [
      {
        "id": 123,
        "username": "john_doe",
        "email": "john@example.com"
      }
    ],
    "total": 100,
    "page": 1,
    "size": 10,
    "pages": 10
  },
  "timestamp": 1640995200
}
```

## 实现示例

### 🔧 Controller 实现

```typescript
@Controller('api/members')
export class MemberController {
  constructor(private readonly memberService: MemberService) {}

  @Get()
  async getMembers(@Query() query: GetMembersDto) {
    try {
      const result = await this.memberService.findAll(query);
      return {
        code: 200,
        message: '获取成功',
        data: result,
        timestamp: Math.floor(Date.now() / 1000)
      };
    } catch (error) {
      return {
        code: 500,
        message: '获取失败',
        data: null,
        timestamp: Math.floor(Date.now() / 1000)
      };
    }
  }
}
```

## 最佳实践

### ✅ 推荐做法

1. **统一格式**：所有 API 都使用统一的响应格式
2. **状态码规范**：使用标准的 HTTP 状态码
3. **错误处理**：提供详细的错误信息
4. **分页支持**：列表接口支持分页
5. **时间戳**：包含响应时间戳

### ❌ 避免做法

1. **不要暴露敏感信息**：错误信息不要包含敏感数据
2. **不要返回不一致的格式**：保持响应格式一致
3. **不要忽略错误处理**：所有错误都要有相应的响应

## 下一步

::: tip 深入学习

1. **查看错误码规范**：了解错误码定义
2. **阅读 API 设计规范**：了解 API 设计原则
3. **参考开发规范**：遵循开发规范

:::

::: warning 注意事项

- 严格遵循统一的响应格式
- 提供详细的错误信息
- 实现适当的错误处理

::: 