180 lines
3.8 KiB
Markdown
180 lines
3.8 KiB
Markdown
# API 层
|
||
|
||
本模块负责HTTP API的实现，提供RESTful接口。
|
||
|
||
## 功能特性
|
||
|
||
- RESTful API设计
|
||
- JWT认证中间件
|
||
- 跨域支持
|
||
- 请求日志记录
|
||
- 统一错误处理
|
||
- 参数验证
|
||
|
||
## 模块结构
|
||
|
||
```
|
||
api/
|
||
├── middlewares/ # 中间件
|
||
│ ├── auth.go # 认证中间件
|
||
│ ├── cors.go # 跨域中间件
|
||
│ └── logging.go # 日志中间件
|
||
├── handlers/ # 请求处理器
|
||
│ ├── auth_handler.go # 认证处理器
|
||
│ ├── user_handler.go # 用户处理器
|
||
│ ├── role_handler.go # 角色处理器
|
||
│ └── menu_handler.go # 菜单处理器
|
||
├── routes/ # 路由配置
|
||
│ └── routes.go # 路由设置
|
||
└── README.md # 说明文档
|
||
```
|
||
|
||
## API 接口
|
||
|
||
### 认证接口
|
||
|
||
```
|
||
POST /api/auth/login # 用户登录
|
||
POST /api/auth/logout # 用户登出
|
||
GET /api/profile # 获取用户信息
|
||
PUT /api/profile # 更新用户信息
|
||
PUT /api/change-password # 修改密码
|
||
```
|
||
|
||
### 用户管理接口（管理员）
|
||
|
||
```
|
||
POST /api/admin/users # 创建用户
|
||
GET /api/admin/users # 获取用户列表
|
||
GET /api/admin/users/:id # 获取用户详情
|
||
PUT /api/admin/users/:id # 更新用户
|
||
DELETE /api/admin/users/:id # 删除用户
|
||
PUT /api/admin/users/:id/status # 更新用户状态
|
||
```
|
||
|
||
### 角色管理接口（管理员）
|
||
|
||
```
|
||
POST /api/admin/roles # 创建角色
|
||
GET /api/admin/roles # 获取角色列表
|
||
GET /api/admin/roles/:id # 获取角色详情
|
||
PUT /api/admin/roles/:id # 更新角色
|
||
DELETE /api/admin/roles/:id # 删除角色
|
||
PUT /api/admin/roles/:id/status # 更新角色状态
|
||
```
|
||
|
||
### 菜单管理接口（管理员）
|
||
|
||
```
|
||
POST /api/admin/menus # 创建菜单
|
||
GET /api/admin/menus # 获取菜单列表
|
||
GET /api/admin/menus/tree # 获取菜单树
|
||
GET /api/admin/menus/:id # 获取菜单详情
|
||
PUT /api/admin/menus/:id # 更新菜单
|
||
DELETE /api/admin/menus/:id # 删除菜单
|
||
PUT /api/admin/menus/:id/status # 更新菜单状态
|
||
PUT /api/admin/menus/:id/sort # 更新菜单排序
|
||
```
|
||
|
||
## 请求示例
|
||
|
||
### 用户登录
|
||
|
||
```bash
|
||
curl -X POST http://localhost:8080/api/auth/login \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"username": "admin",
|
||
"password": "password"
|
||
}'
|
||
```
|
||
|
||
### 获取用户列表
|
||
|
||
```bash
|
||
curl -X GET "http://localhost:8080/api/admin/users?page=1&size=10&username=admin" \
|
||
-H "Authorization: Bearer your-jwt-token"
|
||
```
|
||
|
||
### 创建用户
|
||
|
||
```bash
|
||
curl -X POST http://localhost:8080/api/admin/users \
|
||
-H "Content-Type: application/json" \
|
||
-H "Authorization: Bearer your-jwt-token" \
|
||
-d '{
|
||
"username": "newuser",
|
||
"email": "newuser@example.com",
|
||
"password": "password",
|
||
"nickname": "新用户",
|
||
"role": "user"
|
||
}'
|
||
```
|
||
|
||
## 响应格式
|
||
|
||
### 成功响应
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "操作成功",
|
||
"data": {
|
||
"id": 1,
|
||
"username": "admin",
|
||
"email": "admin@example.com"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 分页响应
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "操作成功",
|
||
"data": [...],
|
||
"total": 100,
|
||
"page": 1,
|
||
"size": 10
|
||
}
|
||
```
|
||
|
||
### 错误响应
|
||
|
||
```json
|
||
{
|
||
"code": 400,
|
||
"message": "参数错误"
|
||
}
|
||
```
|
||
|
||
## 中间件
|
||
|
||
### 认证中间件
|
||
|
||
验证JWT token，将用户信息存储到上下文中。
|
||
|
||
### 管理员中间件
|
||
|
||
验证用户是否具有管理员权限。
|
||
|
||
### 跨域中间件
|
||
|
||
处理跨域请求，支持预检请求。
|
||
|
||
### 日志中间件
|
||
|
||
记录HTTP请求日志，包括请求方法、路径、状态码、响应时间等。
|
||
|
||
## 错误处理
|
||
|
||
所有API都遵循统一的错误处理模式：
|
||
|
||
- 参数验证错误：400 Bad Request
|
||
- 认证失败：401 Unauthorized
|
||
- 权限不足：403 Forbidden
|
||
- 资源不存在：404 Not Found
|
||
- 服务器错误：500 Internal Server Error
|
||
|