API 总览

Personal Blog Backend 提供 RESTful API，基于 Spring Boot 3 + Spring Security 6，使用 JWT Token 认证。

---

🔐 认证机制

公开端点（无需 Token）

路径	说明
POST /api/v1/auth/register	用户注册
POST /api/v1/auth/login	用户登录
GET /actuator/health	健康检查
/swagger-ui/**	API 文档

使用 Token

# 1. 登录获取 Token
TOKEN=$(curl -s -X POST http://localhost:8080/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"testuser","password":"Password123!"}' | jq -r '.data.token')

# 2. 携带 Token 访问受保护接口
curl -X GET http://localhost:8080/api/v1/users/me \
  -H "Authorization: Bearer $TOKEN"

---

📚 API 分类

认证管理 /api/v1/auth

方法	路径	功能	认证
POST	/register	用户注册	❌
POST	/login	用户登录	❌
POST	/logout	用户登出	✅

👉 认证 API 详情

---

用户管理 /api/v1/users

方法	路径	功能	权限
GET	/me	获取当前用户信息	User
PUT	/me	更新个人资料	User
GET	/{id}	获取用户信息	Admin
PUT	/{id}	更新用户信息	Admin
DELETE	/{id}	删除用户	Admin

👉 用户 API 详情

---

角色管理 /api/v1/roles

⚠️ 所有接口都需要 ADMIN 角色

方法	路径	功能
POST	/	创建角色
GET	/{id}	获取角色详情
PUT	/{id}	更新角色
DELETE	/{id}	删除角色
POST	/{roleId}/users/{userId}	分配角色
DELETE	/{roleId}/users/{userId}	移除角色

👉 角色 API 详情

---

监控端点 /actuator

端点	功能
/health	健康检查
/info	应用信息
/metrics	性能指标
/prometheus	Prometheus 格式

👉 Actuator 端点详情

---

规划中的模块

模块	状态	说明
📄 文章管理	🚧 开发中	CRUD、分类、标签
💬 评论管理	📋 规划中	多级评论、审核
📁 文件管理	✅ 已实现	S3 存储、预签名 URL

---

📊 响应格式

统一响应 Result<T>

{
  "code": 0,           // 0=成功, 其他=错误码
  "message": "success",
  "data": { ... }
}

错误码

Code	含义
0	成功
400	参数错误
401	未授权
403	无权限
404	资源不存在
500	服务器错误

---

📖 在线文档

访问 Swagger UI 查看交互式 API 文档：

http://localhost:8080/swagger-ui.html

• 🔍 完整 API 列表
• 🧪 在线测试（Try it out）
• 📋 请求/响应示例

---

🔗 相关文档

• 快速上手 — 第一个 API 调用
• Security 配置 — 认证授权原理
• 开发规范 — API 开发规范