角色管理 API

角色管理接口用于管理系统级角色，包括角色的增删改查、权限范围（Scope）分配和用户关联。

所有接口均需要管理员令牌认证：Authorization: Bearer <admin_token>

角色类型

类型	值	说明
User	User	用户角色，可分配给终端用户
MachineToMachine	MachineToMachine	机器角色，可分配给 M2M 类型的应用

---

获取角色列表

GET /api/v1/roles

分页获取角色列表。

查询参数：

参数	类型	必填	默认值	说明
page	integer	否	1	页码
page_size	integer	否	20	每页条数

请求示例：

curl -X GET "https://your-domain/api/v1/roles?page=1&page_size=10" \
  -H "Authorization: Bearer <admin_token>"

成功响应：

{
  "code": 0,
  "message": "success",
  "result": {
    "data": [
      {
        "id": "role_001",
        "name": "admin",
        "description": "Administrator with full access",
        "type": "User",
        "created_at": "2025-01-01T00:00:00Z",
        "updated_at": "2025-01-01T00:00:00Z"
      },
      {
        "id": "role_002",
        "name": "api-service",
        "description": "Backend service role",
        "type": "MachineToMachine",
        "created_at": "2025-02-01T00:00:00Z",
        "updated_at": "2025-02-01T00:00:00Z"
      }
    ],
    "total": 5,
    "page": 1,
    "page_size": 10
  }
}

---

创建角色

POST /api/v1/roles

创建一个新角色。

请求体：

字段	类型	必填	说明
name	string	是	角色名称，需唯一
description	string	否	角色描述
type	string	是	角色类型：User 或 MachineToMachine

请求示例：

curl -X POST https://your-domain/api/v1/roles \
  -H "Authorization: Bearer <admin_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "editor",
    "description": "Content editor with read and write permissions",
    "type": "User"
  }'

成功响应：

{
  "code": 0,
  "message": "success",
  "result": {
    "id": "role_003",
    "name": "editor",
    "description": "Content editor with read and write permissions",
    "type": "User",
    "created_at": "2025-06-15T08:00:00Z",
    "updated_at": "2025-06-15T08:00:00Z"
  }
}

---

获取角色详情

GET /api/v1/roles/:id

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

路径参数：

参数	类型	说明
id	string	角色 ID

请求示例：

curl -X GET https://your-domain/api/v1/roles/role_003 \
  -H "Authorization: Bearer <admin_token>"

成功响应：

{
  "code": 0,
  "message": "success",
  "result": {
    "id": "role_003",
    "name": "editor",
    "description": "Content editor with read and write permissions",
    "type": "User",
    "created_at": "2025-06-15T08:00:00Z",
    "updated_at": "2025-06-15T08:00:00Z"
  }
}

---

更新角色

PATCH /api/v1/roles/:id

更新角色信息。仅传入需要修改的字段。

路径参数：

参数	类型	说明
id	string	角色 ID

请求体：

字段	类型	必填	说明
name	string	否	角色名称
description	string	否	角色描述

请求示例：

curl -X PATCH https://your-domain/api/v1/roles/role_003 \
  -H "Authorization: Bearer <admin_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Content editor with full CMS access"
  }'

成功响应：

{
  "code": 0,
  "message": "success",
  "result": {
    "id": "role_003",
    "name": "editor",
    "description": "Content editor with full CMS access",
    "type": "User",
    "created_at": "2025-06-15T08:00:00Z",
    "updated_at": "2025-06-15T12:00:00Z"
  }
}

---

删除角色

DELETE /api/v1/roles/:id

删除指定角色。删除后所有关联的用户和 Scope 分配将自动解除。

路径参数：

参数	类型	说明
id	string	角色 ID

请求示例：

curl -X DELETE https://your-domain/api/v1/roles/role_003 \
  -H "Authorization: Bearer <admin_token>"

成功响应：

{
  "code": 0,
  "message": "success",
  "result": null
}

---

获取角色的 Scope 列表

GET /api/v1/roles/:id/scopes

获取指定角色关联的所有权限范围（Scope）。

路径参数：

参数	类型	说明
id	string	角色 ID

请求示例：

curl -X GET https://your-domain/api/v1/roles/role_003/scopes \
  -H "Authorization: Bearer <admin_token>"

成功响应：

{
  "code": 0,
  "message": "success",
  "result": [
    {
      "id": "scope_001",
      "name": "read:books",
      "description": "Read books information",
      "resource_id": "res_002",
      "resource_name": "Bookstore API"
    },
    {
      "id": "scope_002",
      "name": "write:books",
      "description": "Create and update books",
      "resource_id": "res_002",
      "resource_name": "Bookstore API"
    }
  ]
}

---

分配角色的 Scope

PUT /api/v1/roles/:id/scopes

为指定角色分配权限范围。此操作为全量替换，将覆盖角色当前的所有 Scope 分配。

路径参数：

参数	类型	说明
id	string	角色 ID

请求体：

字段	类型	必填	说明
scope_ids	string[]	是	Scope ID 数组

请求示例：

curl -X PUT https://your-domain/api/v1/roles/role_003/scopes \
  -H "Authorization: Bearer <admin_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "scope_ids": ["scope_001", "scope_002", "scope_003"]
  }'

成功响应：

{
  "code": 0,
  "message": "success",
  "result": null
}

---

获取角色的用户列表

GET /api/v1/roles/:id/users

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

路径参数：

参数	类型	说明
id	string	角色 ID

请求示例：

curl -X GET https://your-domain/api/v1/roles/role_003/users \
  -H "Authorization: Bearer <admin_token>"

成功响应：

{
  "code": 0,
  "message": "success",
  "result": [
    {
      "id": "usr_abc123",
      "username": "john_doe",
      "name": "John Doe",
      "email": "john@example.com",
      "avatar": "https://example.com/avatar.png"
    },
    {
      "id": "usr_def456",
      "username": "jane_smith",
      "name": "Jane Smith",
      "email": "jane@example.com",
      "avatar": null
    }
  ]
}

---

分配角色的用户

PUT /api/v1/roles/:id/users

为指定角色批量分配用户。此操作为全量替换，将覆盖角色当前的所有用户分配。

路径参数：

参数	类型	说明
id	string	角色 ID

请求体：

字段	类型	必填	说明
user_ids	string[]	是	用户 ID 数组

请求示例：

curl -X PUT https://your-domain/api/v1/roles/role_003/users \
  -H "Authorization: Bearer <admin_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "user_ids": ["usr_abc123", "usr_def456", "usr_ghi789"]
  }'

成功响应：

{
  "code": 0,
  "message": "success",
  "result": null
}