tyapi-server/docs/API使用指南.md

# 🌐 API 使用指南

## 认证机制

### 1. 用户注册

```bash
curl -X POST http://localhost:8080/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "username": "testuser",
    "email": "test@example.com",
    "password": "Test123!@#"
  }'
```

### 2. 用户登录

```bash
curl -X POST http://localhost:8080/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "testuser",
    "password": "Test123!@#"
  }'
```

响应示例：

```json
{
    "status": "success",
    "data": {
        "access_token": "eyJhbGciOiJIUzI1NiIs...",
        "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
        "expires_in": 86400,
        "user": {
            "id": 1,
            "username": "testuser",
            "email": "test@example.com"
        }
    },
    "request_id": "req_123456789",
    "timestamp": "2024-01-01T00:00:00Z"
}
```

### 3. 使用访问令牌

```bash
curl -X GET http://localhost:8080/api/v1/users/profile \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."
```

## 用户管理 API

### 获取用户列表

```bash
curl -X GET "http://localhost:8080/api/v1/users?page=1&limit=10&search=test" \
  -H "Authorization: Bearer <access_token>"
```

### 获取用户详情

```bash
curl -X GET http://localhost:8080/api/v1/users/1 \
  -H "Authorization: Bearer <access_token>"
```

### 更新用户信息

```bash
curl -X PUT http://localhost:8080/api/v1/users/1 \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "newusername",
    "email": "newemail@example.com"
  }'
```

### 修改密码

```bash
curl -X POST http://localhost:8080/api/v1/users/change-password \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "current_password": "oldpassword",
    "new_password": "newpassword123"
  }'
```

### 删除用户

```bash
curl -X DELETE http://localhost:8080/api/v1/users/1 \
  -H "Authorization: Bearer <access_token>"
```

## 响应格式

### 成功响应

```json
{
    "status": "success",
    "data": {
        // 响应数据
    },
    "request_id": "req_123456789",
    "timestamp": "2024-01-01T00:00:00Z"
}
```

### 分页响应

```json
{
  "status": "success",
  "data": {
    "items": [...],
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 100,
      "total_pages": 10
    }
  },
  "request_id": "req_123456789",
  "timestamp": "2024-01-01T00:00:00Z"
}
```

### 错误响应

```json
{
    "status": "error",
    "error": {
        "code": "VALIDATION_ERROR",
        "message": "请求参数无效",
        "details": {
            "username": ["用户名不能为空"],
            "email": ["邮箱格式不正确"]
        }
    },
    "request_id": "req_123456789",
    "timestamp": "2024-01-01T00:00:00Z"
}
```

## 常用查询参数

### 分页参数

-   `page`: 页码，从 1 开始
-   `limit`: 每页数量，默认 10，最大 100
-   `sort`: 排序字段，如 `created_at`
-   `order`: 排序方向，`asc` 或 `desc`

示例：

```bash
GET /api/v1/users?page=2&limit=20&sort=created_at&order=desc
```

### 搜索参数

-   `search`: 关键词搜索
-   `filter`: 字段过滤

示例：

```bash
GET /api/v1/users?search=john&filter=status:active
```

### 时间范围参数

-   `start_date`: 开始时间，ISO 8601 格式
-   `end_date`: 结束时间，ISO 8601 格式

示例：

```bash
GET /api/v1/users?start_date=2024-01-01T00:00:00Z&end_date=2024-01-31T23:59:59Z
```

## HTTP 状态码

### 成功状态码

-   `200 OK`: 请求成功
-   `201 Created`: 创建成功
-   `202 Accepted`: 请求已接受，正在处理
-   `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`: 服务器内部错误
-   `502 Bad Gateway`: 网关错误
-   `503 Service Unavailable`: 服务不可用
-   `504 Gateway Timeout`: 网关超时

## API 测试

### 使用 Postman

1. 导入 API 集合文件（如果有）
2. 设置环境变量：
    - `base_url`: http://localhost:8080
    - `access_token`: 从登录接口获取

### 使用 curl 脚本

创建测试脚本 `test_api.sh`：

```bash
#!/bin/bash

BASE_URL="http://localhost:8080"
ACCESS_TOKEN=""

# 登录获取token
login() {
    response=$(curl -s -X POST "$BASE_URL/api/v1/auth/login" \
        -H "Content-Type: application/json" \
        -d '{"username":"admin","password":"admin123"}')

    ACCESS_TOKEN=$(echo $response | jq -r '.data.access_token')
    echo "Token: $ACCESS_TOKEN"
}

# 测试用户API
test_users() {
    echo "Testing Users API..."

    # 获取用户列表
    curl -s -X GET "$BASE_URL/api/v1/users" \
        -H "Authorization: Bearer $ACCESS_TOKEN" | jq

    # 创建用户
    curl -s -X POST "$BASE_URL/api/v1/users" \
        -H "Authorization: Bearer $ACCESS_TOKEN" \
        -H "Content-Type: application/json" \
        -d '{"username":"testuser","email":"test@example.com","password":"test123"}' | jq
}

# 执行测试
login
test_users
```

## API 文档

启动服务后，访问以下地址获取完整 API 文档：

-   **Swagger UI**: http://localhost:8080/swagger/
-   **API 规范**: http://localhost:8080/api/docs
-   **健康检查**: http://localhost:8080/api/v1/health

## 限流和配额

### 请求限制

-   默认每分钟 100 个请求
-   突发请求限制 50 个
-   超出限制返回 429 状态码

### 提高限制

如需提高限制，请联系管理员或在配置文件中调整：

```yaml
rate_limit:
    enabled: true
    requests_per_minute: 200
    burst: 100
```

## 错误处理

### 常见错误及解决方案

1. **401 Unauthorized**

    - 检查 Token 是否有效
    - 确认 Token 格式正确
    - 验证 Token 是否过期

2. **403 Forbidden**

    - 检查用户权限
    - 确认访问的资源是否允许

3. **429 Too Many Requests**

    - 降低请求频率
    - 实现指数退避重试

4. **500 Internal Server Error**
    - 检查服务器日志
    - 确认请求参数格式
    - 联系技术支持