鹰眼 API 文档
Open Platform Document Center

外观

角色管理接口文档 ​

本接口用于对系统中的**角色（Role）**资源进行全生命周期管理，遵循 RESTful 设计规范，以 HTTP 方法语义化操作，统一使用 JSON 格式进行数据交互。

资源路径：/system/role-api
实体类：RoleDTO（增删改查共用）

公共请求头 ​

⚠️ 注意：本接口需携带有效的 access_token 进行身份验证，未授权访问将被拒绝。

Header 参数（http header）

参数名类型必填说明
AuthorizationString是请求令牌，Bearer <access_token>

接口列表 ​

操作方法路径说明
创建角色POST/system/role-api新增一个系统角色
查询角色GET/system/role-api/{id}根据 role_id 获取角色详情
更新角色PUT/system/role-api全量更新角色信息
删除角色DELETE/system/role-api/{id}根据 role_id 删除角色
批量删除DELETE/system/role-api/{ids}批量删除多个角色（逗号分隔）

实体类定义（RoleDTO） ​

所有接口的请求体（Request Body）或返回数据（Response Data）均基于以下结构：

JSON 示例 ​

点击展开 JSON 数据
json
{
  "roleId": 101,
  "roleName": "财务专员",
  "roleKey": "finance",
  "roleSort": 5,
  "dataScope": "1",
  "menuCheckStrictly": true,
  "deptCheckStrictly": true,
  "status": "0",
  "delFlag": "0",
  "remark": "负责财务相关操作",
  "tenantId": "000000"
}

字段说明 ​

参数名类型必填默认值说明
roleIdLong否—角色 ID（创建时不传，由服务端生成）
roleNameString是—角色名称（如“租户管理员”）
roleKeyString是—权限字符（唯一标识，如 "admin"）
roleSortInteger是—显示顺序（数字越小越靠前）
dataScopeString否"1"数据权限范围：
"1"：全部数据权限
"2"：自定义数据权限
"3"：本部门数据权限
"4"：本部门及以下数据权限
menuCheckStrictlyBoolean否true菜单树选择是否严格关联（前端控制）
deptCheckStrictlyBoolean否true部门树选择是否严格关联（前端控制）
statusString是—状态：
"0"：正常
"1"：停用
delFlagString否"0"删除标志：
"0"：存在
"2"：已删除（逻辑删除）
remarkString否null备注信息
tenantIdString是"000000"所属租户编号

🔒 安全说明：

  • roleId 为数据库主键，创建时不可传入；
  • delFlag 通常由系统自动管理，不建议前端修改；
  • roleKey 应全局唯一（同租户内）。

接口详情 ​

创建角色（POST） ​

请求

http
POST /system/role-api
Content-Type: application/json
Authorization: Bearer <token>
点击展开 JSON 数据
json
{
  "roleName": "运营专员",
  "roleKey": "operator",
  "roleSort": 6,
  "dataScope": "1",
  "menuCheckStrictly": true,
  "deptCheckStrictly": true,
  "status": "0",
  "remark": "负责日常运营操作",
  "tenantId": "000000"
}

响应

点击展开 JSON 数据
json
{
  "code": 200,
  "msg": "操作成功",
  "data": null
}

查询角色（GET） ​

请求

http
GET /system/role-api/101
Authorization: Bearer <token>

路径参数

参数位置必填说明
idpath是角色 ID（role_id）

响应

点击展开 JSON 数据
json
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "roleId": 101,
    "roleName": "财务专员",
    "roleKey": "finance",
    "roleSort": 5,
    "dataScope": "1",
    "menuCheckStrictly": true,
    "deptCheckStrictly": true,
    "status": "0",
    "delFlag": "0",
    "remark": "负责财务相关操作",
    "tenantId": "000000",
    "createBy": "admin",
    "createTime": "2025-07-28 17:55:13",
    "updateBy": null,
    "updateTime": null
  }
}

更新角色（PUT） ​

请求

http
PUT /system/role-api
Content-Type: application/json
Authorization: Bearer <token>
点击展开 JSON 数据
json
{
  "roleId": 101,
  "roleName": "高级财务专员",
  "roleKey": "finance",
  "roleSort": 5,
  "dataScope": "1",
  "menuCheckStrictly": true,
  "deptCheckStrictly": true,
  "status": "0",
  "remark": "可查看全部财务报表",
  "tenantId": "000000"
}

🔁 注意：

  • 必须包含 roleId；
  • 此为全量更新，未传字段可能被重置为默认值或 null；
  • roleKey 修改需谨慎，可能影响权限控制。

响应

点击展开 JSON 数据
json
{
  "code": 200,
  "msg": "操作成功",
  "data": null
}

删除角色（DELETE） ​

请求

http
DELETE /system/role-api/101
Authorization: Bearer <token>

路径参数

参数位置必填说明
idpath是角色 ID

响应

点击展开 JSON 数据
json
{
  "code": 200,
  "msg": "操作成功",
  "data": null
}

安全与注意事项 ​

  • 权限隔离：角色操作仅限当前租户（tenantId 自动绑定）；
  • 逻辑删除：删除操作实际为 del_flag = '2'，非物理删除；
  • 唯一约束：roleKey 在同一租户内必须唯一；