Initial commit: Basic project structure and dependencies
This commit is contained in:
316
docs/API使用指南.md
Normal file
316
docs/API使用指南.md
Normal file
@@ -0,0 +1,316 @@
|
||||
# 🌐 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**
|
||||
- 检查服务器日志
|
||||
- 确认请求参数格式
|
||||
- 联系技术支持
|
||||
Reference in New Issue
Block a user