角色权限管理 API

角色权限管理模块基于Casbin实现RBAC权限控制，提供角色和权限的完整管理功能。

基础信息

基础路径: /api/v1/admin/roles 和 /api/v1/admin/permissions
认证要求: 需要管理员权限
认证方式: Bearer Token (JWT)

数据模型

Role (角色)

typescript

interface Role {
  id: number;           // 角色ID
  name: string;         // 角色名称
  display_name: string; // 显示名称
  description: string;  // 角色描述
  status: number;       // 状态: 1-启用, 0-禁用
  created_at: string;   // 创建时间
  updated_at: string;   // 更新时间
}

Permission (权限)

typescript

interface Permission {
  id: number;           // 权限ID
  name: string;         // 权限名称
  display_name: string; // 显示名称
  description: string;  // 权限描述
  resource: string;     // 资源
  action: string;       // 操作
  created_at: string;   // 创建时间
  updated_at: string;   // 更新时间
}

角色管理

1. 创建角色

创建一个新的角色。

端点: POST /api/v1/admin/roles

请求体:

json

{
  "name": "manager",
  "display_name": "部门经理",
  "description": "部门管理员角色",
  "status": 1
}

响应示例:

json

{
  "code": 200,
  "message": "创建角色成功",
  "data": {
    "id": 1,
    "name": "manager",
    "display_name": "部门经理",
    "description": "部门管理员角色",
    "status": 1,
    "created_at": "2024-01-15T10:00:00Z",
    "updated_at": "2024-01-15T10:00:00Z"
  }
}

cURL 示例:

bash

curl -X POST http://localhost:8080/api/v1/admin/roles \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "manager",
    "display_name": "部门经理",
    "description": "部门管理员角色",
    "status": 1
  }'

2. 获取角色列表

获取所有角色列表，支持分页和搜索。

端点: GET /api/v1/admin/roles

查询参数:

参数	类型	必填	说明
page	integer	否	页码，默认为1
page_size	integer	否	每页数量，默认为10
search	string	否	搜索关键词
status	integer	否	状态过滤

响应示例:

json

{
  "code": 200,
  "message": "获取角色列表成功",
  "data": {
    "list": [
      {
        "id": 1,
        "name": "admin",
        "display_name": "系统管理员",
        "status": 1
      }
    ],
    "total": 1,
    "page": 1,
    "page_size": 10
  }
}

cURL 示例:

bash

curl -X GET "http://localhost:8080/api/v1/admin/roles?page=1&page_size=10" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

3. 获取角色详情

根据ID获取单个角色的详细信息。

端点: GET /api/v1/admin/roles/:id

路径参数:

参数	类型	必填	说明
id	integer	是	角色ID

cURL 示例:

bash

curl -X GET http://localhost:8080/api/v1/admin/roles/1 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

4. 更新角色

更新指定角色的信息。

端点: PUT /api/v1/admin/roles/:id

请求体:

json

{
  "display_name": "高级经理",
  "description": "更新后的描述",
  "status": 1
}

cURL 示例:

bash

curl -X PUT http://localhost:8080/api/v1/admin/roles/1 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "高级经理",
    "description": "更新后的描述",
    "status": 1
  }'

5. 删除角色

删除指定的角色。

端点: DELETE /api/v1/admin/roles/:id

cURL 示例:

bash

curl -X DELETE http://localhost:8080/api/v1/admin/roles/1 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

6. 分配角色

为用户分配角色。

端点: POST /api/v1/admin/roles/assign

请求体:

json

{
  "user_id": 1,
  "role_name": "manager"
}

cURL 示例:

bash

curl -X POST http://localhost:8080/api/v1/admin/roles/assign \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": 1,
    "role_name": "manager"
  }'

7. 撤销角色

撤销用户的角色。

端点: POST /api/v1/admin/roles/revoke

请求体:

json

{
  "user_id": 1,
  "role_name": "manager"
}

cURL 示例:

bash

curl -X POST http://localhost:8080/api/v1/admin/roles/revoke \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": 1,
    "role_name": "manager"
  }'

8. 获取用户角色

获取指定用户的所有角色。

端点: GET /api/v1/admin/roles/users/:user_id

cURL 示例:

bash

curl -X GET http://localhost:8080/api/v1/admin/roles/users/1 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

9. 获取角色下的用户

获取指定角色下的所有用户。

端点: GET /api/v1/admin/roles/by-name/:role_name/users

cURL 示例:

bash

curl -X GET http://localhost:8080/api/v1/admin/roles/by-name/manager/users \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

权限管理

1. 创建权限

创建一个新的权限。

端点: POST /api/v1/admin/permissions

请求体:

json

{
  "name": "employee:read",
  "display_name": "查看员工",
  "description": "查看员工信息的权限",
  "resource": "employee",
  "action": "read"
}

cURL 示例:

bash

curl -X POST http://localhost:8080/api/v1/admin/permissions \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "employee:read",
    "display_name": "查看员工",
    "description": "查看员工信息的权限",
    "resource": "employee",
    "action": "read"
  }'

2. 获取权限列表

获取所有权限列表。

端点: GET /api/v1/admin/permissions

cURL 示例:

bash

curl -X GET "http://localhost:8080/api/v1/admin/permissions?page=1&page_size=20" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

3. 为角色添加权限

为指定角色添加权限。

端点: POST /api/v1/admin/roles/permissions/add

请求体:

json

{
  "role_name": "manager",
  "permission_name": "employee:read"
}

cURL 示例:

bash

curl -X POST http://localhost:8080/api/v1/admin/roles/permissions/add \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "role_name": "manager",
    "permission_name": "employee:read"
  }'

4. 从角色删除权限

从指定角色删除权限。

端点: POST /api/v1/admin/roles/permissions/remove

请求体:

json

{
  "role_name": "manager",
  "permission_name": "employee:read"
}

cURL 示例:

bash

curl -X POST http://localhost:8080/api/v1/admin/roles/permissions/remove \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "role_name": "manager",
    "permission_name": "employee:read"
  }'

5. 获取角色权限

获取指定角色的所有权限。

端点: GET /api/v1/admin/roles/by-name/:role_name/permissions

cURL 示例:

bash

curl -X GET http://localhost:8080/api/v1/admin/roles/by-name/manager/permissions \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

6. 获取权限对应的角色

获取拥有指定权限的所有角色。

端点: GET /api/v1/admin/permissions/by-name/:permission_name/roles

cURL 示例:

bash

curl -X GET http://localhost:8080/api/v1/admin/permissions/by-name/employee:read/roles \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

错误响应

所有端点可能返回以下错误：

400 Bad Request

json

{
  "code": 400,
  "message": "无效的角色ID",
  "data": null
}

401 Unauthorized

json

{
  "code": 401,
  "message": "未授权，请先登录",
  "data": null
}

403 Forbidden

json

{
  "code": 403,
  "message": "权限不足",
  "data": null
}

404 Not Found

json

{
  "code": 404,
  "message": "角色不存在",
  "data": null
}

500 Internal Server Error

json

{
  "code": 500,
  "message": "服务器内部错误",
  "data": null
}

注意事项

权限要求: 所有角色权限管理接口都需要管理员权限
Casbin集成: 系统使用Casbin进行权限控制
角色命名: 角色名称应使用英文小写和下划线
权限命名: 权限名称建议使用 resource:action 格式
系统角色: admin 角色拥有所有权限，不可删除
级联删除: 删除角色时会自动移除该角色的所有用户关联和权限关联

角色权限管理 API ​

基础信息 ​

数据模型 ​

Role (角色) ​

Permission (权限) ​

角色管理 ​

1. 创建角色 ​

2. 获取角色列表 ​

3. 获取角色详情 ​

4. 更新角色 ​

5. 删除角色 ​

6. 分配角色 ​

7. 撤销角色 ​

8. 获取用户角色 ​

9. 获取角色下的用户 ​

权限管理 ​

1. 创建权限 ​

2. 获取权限列表 ​

3. 为角色添加权限 ​

4. 从角色删除权限 ​

5. 获取角色权限 ​

6. 获取权限对应的角色 ​

错误响应 ​

400 Bad Request ​

401 Unauthorized ​

403 Forbidden ​

404 Not Found ​

500 Internal Server Error ​

注意事项 ​

相关文档 ​

角色权限管理 API

基础信息

数据模型

Role (角色)

Permission (权限)

角色管理

1. 创建角色

2. 获取角色列表

3. 获取角色详情

4. 更新角色

5. 删除角色

6. 分配角色

7. 撤销角色

8. 获取用户角色

9. 获取角色下的用户

权限管理

1. 创建权限

2. 获取权限列表

3. 为角色添加权限

4. 从角色删除权限

5. 获取角色权限

6. 获取权限对应的角色

错误响应

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

500 Internal Server Error

注意事项

相关文档