manta/gofaster/ROLE_MANAGEMENT_API_GUIDE.md

角色管理前后台交互指南

概述

本文档介绍如何将前台角色管理功能连接到真实的后端API，实现完整的前后台交互。

功能特性

✅ 已实现功能

1. 角色CRUD操作

   • 获取角色列表（支持分页）
   • 创建新角色
   • 更新角色信息
   • 删除角色

2. API测试模式

   • 支持测试模式切换（无需JWT认证）
   • 支持正式模式（需要JWT认证）
   • 实时API连接测试

3. 错误处理

   • 统一的错误响应格式
   • 友好的错误提示
   • 网络连接异常处理

4. 用户体验

   • 加载状态显示
   • 操作确认提示
   • 实时数据刷新

快速开始

1. 启动服务

使用完整启动脚本同时启动前后台：

# 标准模式启动
.\start-full.ps1

# 调试模式启动
.\start-full.ps1 -Debug

# 测试模式启动
.\start-full.ps1 -Test

2. 访问应用

• 前端应用: http://localhost:8081
• 后端API: http://localhost:8080
• API文档: http://localhost:8080/swagger/index.html

3. 测试API连接

1. 进入角色管理页面
2. 点击"测试模式"按钮切换到测试模式
3. 点击"新建角色"测试创建功能
4. 查看角色列表测试获取功能

API接口说明

基础信息

• API基础路径: /api/auth/roles
• 测试路径: /api/auth/roles/test
• 认证方式: JWT Bearer Token
• 响应格式: JSON

接口列表

1. 获取角色列表

GET /api/auth/roles?page=1&pageSize=10

响应格式:

{
  "code": 200,
  "message": "获取角色列表成功",
  "data": {
    "data": [
      {
        "id": 1,
        "name": "管理员",
        "code": "ADMIN",
        "description": "系统管理员",
        "created_at": "2024-01-01T00:00:00Z",
        "updated_at": "2024-01-01T00:00:00Z"
      }
    ],
    "page": 1,
    "size": 10,
    "total": 1
  }
}

2. 创建角色

POST /api/auth/roles
Content-Type: application/json

{
  "name": "新角色",
  "code": "NEW_ROLE",
  "description": "角色描述"
}

响应格式:

{
  "code": 200,
  "message": "角色创建成功",
  "data": {
    "id": 2,
    "name": "新角色",
    "code": "NEW_ROLE",
    "description": "角色描述",
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-01T00:00:00Z"
  }
}

3. 更新角色

PUT /api/auth/roles/{id}
Content-Type: application/json

{
  "name": "更新后的角色",
  "code": "UPDATED_ROLE",
  "description": "更新后的描述"
}

4. 删除角色

DELETE /api/auth/roles/{id}

响应格式:

{
  "code": 200,
  "message": "角色删除成功",
  "data": null
}

前端组件使用

1. 角色管理主页面

<template>
  <RoleManagement />
</template>

<script>
import { RoleManagement } from '@/modules/role-management'

export default {
  components: {
    RoleManagement
  }
}
</script>

2. API测试页面

<template>
  <RoleApiTest />
</template>

<script>
import { RoleApiTest } from '@/modules/role-management'

export default {
  components: {
    RoleApiTest
  }
}
</script>

3. 直接使用服务

import { roleService } from '@/modules/role-management'

// 获取角色列表
const roles = await roleService.getRoles(1, 10)

// 创建角色
const newRole = await roleService.createRole({
  name: '测试角色',
  code: 'TEST_ROLE',
  description: '测试描述'
})

// 更新角色
const updatedRole = await roleService.updateRole(1, {
  name: '更新后的角色',
  code: 'UPDATED_ROLE',
  description: '更新后的描述'
})

// 删除角色
await roleService.deleteRole(1)

配置说明

1. API基础URL配置

前端配置文件: app/src/config/app.config.js

export const appConfig = {
  development: {
    apiBaseUrl: 'http://localhost:8080/api',
    // ...
  }
}

2. 测试模式配置

通过localStorage控制测试模式：

// 启用测试模式
localStorage.setItem('role-test-mode', 'true')

// 禁用测试模式
localStorage.setItem('role-test-mode', 'false')

// 检查测试模式状态
const isTestMode = localStorage.getItem('role-test-mode') === 'true'

3. JWT认证配置

// 设置JWT token
localStorage.setItem('token', 'your-jwt-token')

// 清除JWT token
localStorage.removeItem('token')

错误处理

1. 网络错误

try {
  const response = await roleService.getRoles()
} catch (error) {
  if (error.code === 0) {
    console.error('网络连接失败')
  } else if (error.code === 401) {
    console.error('认证失败，请重新登录')
  } else {
    console.error('请求失败:', error.message)
  }
}

2. 业务错误

const response = await roleService.createRole(roleData)
if (response.code !== 200) {
  console.error('业务错误:', response.message)
}

开发调试

1. 启用调试模式

# 启动调试模式
.\start-full.ps1 -Debug

2. 查看API日志

后端日志文件: backend/logs/app.log

3. 使用API测试页面

访问角色管理API测试页面，可以：

• 查看API配置信息
• 手动测试各个接口
• 查看详细的请求响应
• 切换测试模式

4. 浏览器开发者工具

• 打开Network面板查看API请求
• 查看Console面板的错误信息
• 使用Application面板查看localStorage

常见问题

Q1: API连接失败

解决方案:

1. 检查后端服务是否启动
2. 确认API基础URL配置正确
3. 检查防火墙设置
4. 查看后端日志

Q2: 认证失败

解决方案:

1. 切换到测试模式（无需认证）
2. 检查JWT token是否有效
3. 重新登录获取新token

Q3: 数据不显示

解决方案:

1. 检查API响应格式
2. 确认数据库中有数据
3. 查看浏览器控制台错误

Q4: 创建/更新失败

解决方案:

1. 检查必填字段是否填写
2. 确认角色名称和代码唯一性
3. 查看后端验证错误信息

扩展功能

1. 权限管理

可以扩展角色管理功能，添加：

• 角色权限分配
• 权限树形展示
• 批量权限操作

2. 用户角色分配

可以添加：

• 用户角色分配页面
• 批量角色分配
• 角色继承关系

3. 角色模板

可以添加：

• 角色模板管理
• 快速创建角色
• 角色导入导出

技术栈

前端

• Vue 3 (Composition API)
• Axios (HTTP客户端)
• Vue Router (路由管理)

后端

• Go (Gin框架)
• GORM (ORM)
• JWT (认证)

数据库

• MySQL/PostgreSQL
• Redis (缓存)

贡献指南

1. Fork项目
2. 创建功能分支
3. 提交代码
4. 创建Pull Request

许可证

MIT License