Code Bird Cloud

Appearance

用户管理 API ​

用户管理接口用于管理平台中的终端用户，包括用户的增删改查、密码重置、状态管理、角色分配和组织查询。

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

获取用户列表 ​

GET /api/v1/users ​

分页获取用户列表，支持搜索过滤。

查询参数：

参数类型必填默认值说明
pageinteger否1页码，从 1 开始
page_sizeinteger否20每页条数
searchstring否-搜索关键词（匹配用户名、邮箱、手机号、姓名）

请求示例：

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

成功响应：

json
{
  "code": 0,
  "message": "success",
  "result": {
    "data": [
      {
        "id": "usr_abc123",
        "username": "john_doe",
        "name": "John Doe",
        "email": "john@example.com",
        "phone": "13800138000",
        "avatar": "https://example.com/avatar.png",
        "is_suspended": false,
        "last_sign_in_at": "2025-06-01T10:30:00Z",
        "created_at": "2025-01-15T08:00:00Z",
        "updated_at": "2025-06-01T10:30:00Z"
      }
    ],
    "total": 56,
    "page": 1,
    "page_size": 10
  }
}

创建用户 ​

POST /api/v1/users ​

创建一个新用户。

请求体：

字段类型必填说明
usernamestring是用户名，需唯一
passwordstring是密码，最少 6 位
emailstring否邮箱地址
phonestring否手机号
namestring否显示名称
avatarstring否头像 URL

请求示例：

bash
curl -X POST https://your-domain/api/v1/users \
  -H "Authorization: Bearer <admin_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "john_doe",
    "password": "secure123",
    "email": "john@example.com",
    "phone": "13800138000",
    "name": "John Doe",
    "avatar": "https://example.com/avatar.png"
  }'

成功响应：

json
{
  "code": 0,
  "message": "success",
  "result": {
    "id": "usr_abc123",
    "username": "john_doe",
    "name": "John Doe",
    "email": "john@example.com",
    "phone": "13800138000",
    "avatar": "https://example.com/avatar.png",
    "is_suspended": false,
    "created_at": "2025-06-15T08:00:00Z",
    "updated_at": "2025-06-15T08:00:00Z"
  }
}

错误响应（用户名已存在）：

json
{
  "code": 400,
  "message": "用户名已存在",
  "result": ""
}

获取用户详情 ​

GET /api/v1/users/:id ​

根据用户 ID 获取用户详细信息。

路径参数：

参数类型说明
idstring用户 ID

请求示例：

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

成功响应：

json
{
  "code": 0,
  "message": "success",
  "result": {
    "id": "usr_abc123",
    "username": "john_doe",
    "name": "John Doe",
    "email": "john@example.com",
    "phone": "13800138000",
    "avatar": "https://example.com/avatar.png",
    "is_suspended": false,
    "last_sign_in_at": "2025-06-01T10:30:00Z",
    "created_at": "2025-01-15T08:00:00Z",
    "updated_at": "2025-06-01T10:30:00Z"
  }
}

错误响应（用户不存在）：

json
{
  "code": 404,
  "message": "用户不存在",
  "result": ""
}

更新用户 ​

PATCH /api/v1/users/:id ​

更新用户的基本信息。仅传入需要修改的字段。

路径参数：

参数类型说明
idstring用户 ID

请求体：

字段类型必填说明
namestring否显示名称
emailstring否邮箱地址
phonestring否手机号
avatarstring否头像 URL

请求示例：

bash
curl -X PATCH https://your-domain/api/v1/users/usr_abc123 \
  -H "Authorization: Bearer <admin_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Updated",
    "email": "john.new@example.com"
  }'

成功响应：

json
{
  "code": 0,
  "message": "success",
  "result": {
    "id": "usr_abc123",
    "username": "john_doe",
    "name": "John Updated",
    "email": "john.new@example.com",
    "phone": "13800138000",
    "avatar": "https://example.com/avatar.png",
    "is_suspended": false,
    "created_at": "2025-01-15T08:00:00Z",
    "updated_at": "2025-06-15T12:00:00Z"
  }
}

删除用户 ​

DELETE /api/v1/users/:id ​

删除指定用户。删除后该用户的所有关联数据（角色分配、组织成员关系等）将被同步清除。

路径参数：

参数类型说明
idstring用户 ID

请求示例：

bash
curl -X DELETE https://your-domain/api/v1/users/usr_abc123 \
  -H "Authorization: Bearer <admin_token>"

成功响应：

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

重置密码 ​

PATCH /api/v1/users/:id/password ​

重置指定用户的密码。

路径参数：

参数类型说明
idstring用户 ID

请求体：

字段类型必填说明
passwordstring是新密码，最少 6 位

请求示例：

bash
curl -X PATCH https://your-domain/api/v1/users/usr_abc123/password \
  -H "Authorization: Bearer <admin_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "password": "newSecure456"
  }'

成功响应：

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

错误响应（密码不符合要求）：

json
{
  "code": 400,
  "message": "密码长度不能少于6位",
  "result": ""
}

挂起/恢复用户 ​

PATCH /api/v1/users/:id/suspend ​

挂起或恢复指定用户。被挂起的用户将无法登录。

路径参数：

参数类型说明
idstring用户 ID

请求体：

字段类型必填说明
is_suspendedboolean是true 挂起用户，false 恢复用户

请求示例：

bash
curl -X PATCH https://your-domain/api/v1/users/usr_abc123/suspend \
  -H "Authorization: Bearer <admin_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "is_suspended": true
  }'

成功响应：

json
{
  "code": 0,
  "message": "success",
  "result": {
    "id": "usr_abc123",
    "username": "john_doe",
    "is_suspended": true,
    "updated_at": "2025-06-15T14:00:00Z"
  }
}

获取用户角色 ​

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

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

路径参数：

参数类型说明
idstring用户 ID

请求示例：

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

成功响应：

json
{
  "code": 0,
  "message": "success",
  "result": [
    {
      "id": "role_001",
      "name": "editor",
      "description": "Content editor role",
      "type": "User",
      "created_at": "2025-01-01T00:00:00Z"
    },
    {
      "id": "role_002",
      "name": "viewer",
      "description": "Read-only viewer role",
      "type": "User",
      "created_at": "2025-01-01T00:00:00Z"
    }
  ]
}

分配用户角色 ​

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

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

路径参数：

参数类型说明
idstring用户 ID

请求体：

字段类型必填说明
role_idsstring[]是角色 ID 数组

请求示例：

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

成功响应：

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

获取用户的组织列表 ​

GET /api/v1/users/:id/organizations ​

分页获取指定用户所属的所有组织。

路径参数：

参数类型说明
idstring用户 ID

查询参数：

参数类型必填默认值说明
pageinteger否1页码
page_sizeinteger否20每页条数

请求示例：

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

成功响应：

json
{
  "code": 0,
  "message": "success",
  "result": {
    "data": [
      {
        "id": "org_001",
        "name": "Acme Corporation",
        "description": "Main organization",
        "member_count": 25,
        "created_at": "2025-01-01T00:00:00Z"
      },
      {
        "id": "org_002",
        "name": "Beta Team",
        "description": "Beta testing team",
        "member_count": 8,
        "created_at": "2025-03-10T00:00:00Z"
      }
    ],
    "total": 2,
    "page": 1,
    "page_size": 10
  }
}

Released under the MIT License.

Copyright 2024-present Code Bird Team