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

🌐 API 使用指南

认证机制

1. 用户注册

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. 用户登录

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

响应示例：

{
    "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. 使用访问令牌

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

用户管理 API

获取用户列表

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

获取用户详情

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

更新用户信息

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"
  }'

修改密码

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"
  }'

删除用户

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

响应格式

成功响应

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

分页响应

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

错误响应

{
    "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

示例：

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

搜索参数

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

示例：

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

时间范围参数

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

示例：

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：

#!/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 状态码

提高限制

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

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

   • 检查服务器日志
   • 确认请求参数格式
   • 联系技术支持