---
description: API接口相关规范
globs: 
alwaysApply: false
---
# API接口规范

## 接口设计原则
1. 遵循 RESTful 设计规范
2. 使用 HTTPS 协议
3. 版本控制
4. 统一的响应格式

## 请求规范
### 请求方法
- GET: 获取资源
- POST: 创建资源
- PUT: 更新资源
- DELETE: 删除资源

### 请求头
```
Content-Type: application/json
Authorization: Bearer {token}
```

### 请求参数
1. GET 请求参数使用 query string
2. POST/PUT 请求参数使用 JSON 格式
3. 分页参数统一使用 page 和 pageSize

## 响应规范
### 响应格式
```json
{
  "code": 0,           // 状态码
  "message": "success", // 状态信息
  "data": {            // 响应数据
    // 具体数据
  }
}
```

### 状态码
- 200: 成功
- 400: 请求参数错误
- 401: 未授权
- 403: 禁止访问
- 404: 资源不存在
- 500: 服务器错误

## 接口文档
1. 使用 OpenAPI (Swagger) 规范
2. 必须包含接口描述、参数说明、响应示例
3. 及时更新文档

## 错误处理
1. 统一的错误响应格式
2. 详细的错误信息
3. 错误码规范

## 安全规范
1. 所有接口必须进行身份验证
2. 敏感数据传输加密
3. 实现请求频率限制
4. 防止 SQL 注入和 XSS 攻击

## 缓存策略
1. 合理使用 HTTP 缓存头
2. 实现 ETag
3. 设置适当的缓存时间

## 性能优化
1. 接口响应时间控制
2. 数据压缩
3. 分页查询

4. 按需加载