# 通用API规范

[返回主文档](../README.md)

## 📋 概述
本文档定义所有版本API的通用规范，包括请求/响应格式、错误处理、认证等。

## 🔌 基础约定

### 1. API根路径
- `version`: API版本号，如 `v1.0.3`, `v1.0.4`
- 示例: `/api/v1.0.4/upload`

### 2. HTTP方法使用
| 方法 | 用途 | 幂等性 | 安全性 |
|------|------|--------|--------|
| GET | 获取资源 | 是 | 是 |
| POST | 创建资源 | 否 | 否 |
| PUT | 更新资源（全量） | 是 | 否 |
| PATCH | 更新资源（部分） | 否 | 否 |
| DELETE | 删除资源 | 是 | 否 |

### 3. 状态码规范
| 状态码 | 含义 | 使用场景 |
|--------|------|----------|
| 200 | OK | 请求成功 |
| 201 | Created | 资源创建成功 |
| 204 | No Content | 成功但无返回内容 |
| 400 | Bad Request | 请求参数错误 |
| 401 | Unauthorized | 未认证或认证失败 |
| 403 | Forbidden | 权限不足 |
| 404 | Not Found | 资源不存在 |
| 409 | Conflict | 资源冲突 |
| 422 | Unprocessable Entity | 请求格式正确但语义错误 |
| 429 | Too Many Requests | 请求频率超限 |
| 500 | Internal Server Error | 服务器内部错误 |
| 503 | Service Unavailable | 服务暂时不可用 |

## 📦 请求规范

### 1. 请求头
```http
# 必需头
Content-Type: application/json
Accept: application/json

# 认证头（二选一）
Authorization: Bearer {jwt-token}
X-API-Key: {api-key}

# 可选头
X-Request-ID: {uuid}            # 请求追踪
X-Client-Version: {version}     # 客户端版本
X-Timezone: Asia/Shanghai       # 时区信息
X-Language: zh-CN               # 语言偏好
```

### 2. 查询参数
使用驼峰命名法：pageSize 而非 page_size
布尔值使用 true/false
数组使用逗号分隔：versions=medium,thumbnail
日期时间使用ISO 8601：2024-01-15T10:30:00Z
### 3. 路径参数
### 4. 请求体

## 📨 响应规范
### 1. 成功响应格式
### 2. 分页响应格式
### 3. 错误响应格式
## 🚨 错误处理
### 错误码规范
错误码使用大写蛇形命名法，分为以下几类：
#### 通用错误（1xxx）
| 错误码 | HTTP状态 | 说明 |
|--------|----------|------|
| INTERNAL_ERROR | 500 | 服务器内部错误 |
| SERVICE_UNAVAILABLE | 503 | 服务暂时不可用 |
| RATE_LIMIT_EXCEEDED | 429 | 请求频率超限 |
| MAINTENANCE_MODE | 503 | 维护模式中 |
#### 客户端错误（2xxx）

| 错误码 | HTTP状态 | 说明 |
|--------|----------|------|
| VALIDATION_ERROR | 400 | 参数验证失败 |
| UNAUTHORIZED | 401 | 未认证或认证失败 |
| FORBIDDEN | 403 | 权限不足 |
| NOT_FOUND | 404 | 资源不存在 |
| CONFLICT | 409 | 资源冲突 |

#### 文件相关错误（3xxx）

| 错误码 | HTTP状态 | 说明 |
|--------|----------|------|
| FILE_NOT_FOUND | 404 | 文件不存在 |
| FILE_TOO_LARGE | 400 | 文件过大 |
| UNSUPPORTED_TYPE | 400 | 不支持的文件类型 |
| UPLOAD_FAILED | 500 | 上传失败 |
| DOWNLOAD_FAILED | 500 | 下载失败 |
#### 图片处理错误（4xxx）

| 错误码 | HTTP状态 | 说明 |
|--------|----------|------|
| IMAGE_PROCESSING_FAILED | 500 | 图片处理失败 |
| IMAGE_TOO_LARGE | 400 | 图片尺寸过大 |
| UNSUPPORTED_IMAGE_FORMAT | 400 | 不支持的图片格式 |
| COMPRESSION_FAILED | 500 | 压缩失败 |
#### 错误处理流程
```java
// 错误处理示例
@ExceptionHandler(FileNotFoundException.class)
public ResponseEntity<ApiResponse<Void>> handleFileNotFound(
        FileNotFoundException ex) {
    
    ApiResponse<Void> response = ApiResponse.error(
        ErrorCode.FILE_NOT_FOUND,
        ex.getMessage(),
        Collections.singletonList(new ApiError("fileId", "NOT_FOUND", "文件不存在"))
    );
    
    return ResponseEntity
        .status(HttpStatus.NOT_FOUND)
        .body(response);
}
```

## 🔐 认证与授权
### 1. JWT认证
```http request
# 请求头
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

# JWT Payload示例
{
  "sub": "user123",
  "name": "John Doe",
  "iat": 1516239022,
  "exp": 1516242622,
  "permissions": ["file:upload", "file:read"]
}
```
### 2. API Key认证
```http
# 请求头
X-API-Key: sk_live_1234567890abcdef

# API Key格式
sk_{environment}_{random}
# environment: test, live
# random: 16位随机字符
```
### 3. 权限控制
## 🔄 版本控制
### 1. 版本管理策略
主版本：重大变更，可能不兼容
次版本：功能增强，向后兼容
修订版本：Bug修复，完全兼容
### 2. 版本弃用流程
标记弃用：在文档中标记，API响应中添加警告头
宽限期：继续支持6-12个月
停止支持：移除弃用API，返回410 Gone
### 3. 版本协商
```http request
# 请求头版本协商
Accept: application/vnd.example.v1.0.4+json
Accept-Version: 1.0.4

# 响应头
API-Version: 1.0.4
Deprecated: true  # 如果已弃用
Sunset: Wed, 15 Jan 2025 10:30:00 GMT  # 停止支持时间
```
## 📡 实时通知
```json
{
  "event": "file.uploaded",
  "version": "1.0.4",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "fileId": "123e4567-e89b-12d3-a456-426614174000",
    "fileName": "example.jpg",
    "fileSize": 1024000,
    "status": "completed",
    "url": "https://cdn.example.com/uploads/example.jpg"
  },
  "metadata": {
    "requestId": "req_123456",
    "webhookId": "wh_123456"
  }
}
```
#### 支持的事件类型

| 事件 | 触发条件 | 数据包含 |
|------|----------|----------|
| file.uploaded | 文件上传完成 | 文件信息、URL |
| file.processed | 图片处理完成 | 处理结果、版本信息 |
| file.downloaded | 文件被下载 | 下载信息、用户 |
| file.deleted | 文件被删除 | 文件ID、删除者 |
| error.occurred | 发生错误 | 错误详情、上下文 |

## 🧪 测试规范
### 1. 测试数据准备
```json
// test-data.json
{
  "files": {
    "small_jpeg": {
      "path": "test/images/small.jpg",
      "size": "50KB",
      "type": "image/jpeg"
    },
    "large_png": {
      "path": "test/images/large.png",
      "size": "5MB",
      "type": "image/png"
    }
  },
  "users": {
    "admin": {
      "token": "eyJhbGciOiJIUzI1NiIs...",
      "permissions": ["*"]
    },
    "user": {
      "token": "eyJhbGciOiJIUzI1NiIs...",
      "permissions": ["file:upload", "file:read"]
    }
  }
}
```
### 2. API测试用例

## 📊 监控与日志
### 1. 日志格式
```json
{
  "timestamp": "2024-01-15T10:30:00.123Z",
  "level": "INFO",
  "logger": "com.example.fileupload.api.UploadController",
  "message": "文件上传成功",
  "thread": "http-nio-8080-exec-1",
  "context": {
    "requestId": "req_123456",
    "userId": "user123",
    "fileId": "123e4567-e89b-12d3-a456-426614174000",
    "fileName": "example.jpg",
    "fileSize": 1024000,
    "duration": 125
  },
  "exception": null
}
```
### 2. 监控指标
```yaml
metrics:
  api:
    - name: "api_requests_total"
      labels: ["method", "endpoint", "status"]
    - name: "api_request_duration_seconds"
      type: histogram
      labels: ["method", "endpoint"]
  
  file:
    - name: "file_upload_size_bytes"
      type: histogram
      labels: ["type"]
    - name: "file_processing_duration_seconds"
      type: histogram
      labels: ["operation"]
  
  system:
    - name: "memory_usage_bytes"
    - name: "cpu_usage_percent"
    - name: "disk_usage_percent"
```
## 🔗 相关文档
错误代码
版本对比
[返回主文档](../README.md)