# 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