API 文档概览
AstrNest 提供完整的 RESTful API 接口，支持图片上传、管理、用户认证等功能。所有 API 都遵循 REST 设计原则，使用 JSON 格式进行数据交换。
🔑 认证方式
1. JWT Token 认证（推荐）
适用于 Web 前端和移动应用：
http
Authorization: Bearer <jwt-token>获取 Token：
http
POST /api/auth/login
Content-Type: application/json
{
"username": "admin",
"password": "chenxi123"
}2. API Key 认证
适用于第三方应用集成：
http
X-API-Key: <api-key>获取 API Key：
- 登录管理界面
- 进入 "API 密钥管理"
- 创建新的 API 密钥
📊 响应格式
成功响应
json
{
"code": 200,
"message": "操作成功",
"data": {
"id": 1,
"name": "示例数据"
},
"timestamp": "2024-01-01T00:00:00Z"
}错误响应
json
{
"code": 400,
"message": "请求参数错误",
"error": "详细错误信息",
"timestamp": "2024-01-01T00:00:00Z"
}📋 状态码说明
| 状态码 | 说明 |
|---|---|
| 200 | 请求成功 |
| 201 | 创建成功 |
| 400 | 请求参数错误 |
| 401 | 未授权 |
| 403 | 权限不足 |
| 404 | 资源不存在 |
| 429 | 请求频率限制 |
| 500 | 服务器内部错误 |
🔌 接口分类
用户相关接口
- 认证接口：登录、注册、验证码
- 用户信息：个人资料、安全设置
- 上传管理：图片上传、查看、删除
管理相关接口
- 用户管理：用户列表、角色管理
- 内容管理：上传记录、违规内容
- 系统配置：系统参数、邮件配置
公共接口
- 公共图库：公开图片浏览
- 访客功能：点赞、用户信息
🚀 快速开始
1. 获取访问令牌
bash
curl -X POST "http://localhost:8080/api/auth/login" \
-H "Content-Type: application/json" \
-d '{
"username": "admin",
"password": "chenxi123"
}'响应：
json
{
"code": 200,
"message": "登录成功",
"data": {
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"user": {
"id": 1,
"username": "admin",
"role": "ADMIN"
}
}
}2. 使用令牌调用 API
bash
curl -X GET "http://localhost:8080/api/user/profile" \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."📝 分页查询
所有列表接口都支持分页查询：
http
GET /api/user/uploads?page=1&size=20&sort=createdAt,desc响应格式：
json
{
"content": [
// 数据列表
],
"totalElements": 100,
"totalPages": 5,
"size": 20,
"number": 0,
"first": true,
"last": false
}🔒 权限控制
不同角色有不同的 API 访问权限：
| 角色 | 权限说明 |
|---|---|
| ADMIN | 所有 API 权限 |
| USER | 用户相关 API |
| VISITOR | 只读 API |
📡 实时文档
访问 Swagger UI 查看完整的 API 文档：
http://localhost:8080/swagger-ui.html🧪 测试工具
使用 Postman 测试
- 导入 Postman 集合
- 设置环境变量
- 先调用登录接口获取 token
- 使用 token 测试其他接口
使用 curl 测试
bash
# 设置环境变量
export TOKEN="your-jwt-token"
export BASE_URL="http://localhost:8080"
# 测试用户信息接口
curl -H "Authorization: Bearer $TOKEN" "$BASE_URL/api/user/profile"⚠️ 注意事项
- 频率限制：API 调用有频率限制，避免频繁请求
- 参数校验：所有参数都会进行严格校验
- 错误处理：妥善处理各种错误情况
- 版本控制：API 版本会随项目更新
- 数据安全：敏感数据需要加密传输
📚 详细接口文档
🔄 更新日志
v1.0.0 (2024-01-01)
- 初始版本发布
- 完整的 RESTful API 接口
- JWT 和 API Key 双重认证
- 完善的错误处理机制