goalfylearning-admin/internal/api/README.md

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  # 更新菜单排序

请求示例

用户登录

curl -X POST http://localhost:8080/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "admin",
    "password": "password"
  }'

获取用户列表

curl -X GET "http://localhost:8080/api/admin/users?page=1&size=10&username=admin" \
  -H "Authorization: Bearer your-jwt-token"

创建用户

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"
  }'

响应格式

成功响应

{
  "code": 200,
  "message": "操作成功",
  "data": {
    "id": 1,
    "username": "admin",
    "email": "admin@example.com"
  }
}

分页响应

{
  "code": 200,
  "message": "操作成功",
  "data": [...],
  "total": 100,
  "page": 1,
  "size": 10
}

错误响应

{
  "code": 400,
  "message": "参数错误"
}

中间件

认证中间件

验证JWT token，将用户信息存储到上下文中。

管理员中间件

验证用户是否具有管理员权限。

跨域中间件

处理跨域请求，支持预检请求。

日志中间件

记录HTTP请求日志，包括请求方法、路径、状态码、响应时间等。

错误处理

所有API都遵循统一的错误处理模式：

• 参数验证错误：400 Bad Request
• 认证失败：401 Unauthorized
• 权限不足：403 Forbidden
• 资源不存在：404 Not Found
• 服务器错误：500 Internal Server Error