用户管理操作

本文档说明 Code Bird Cloud Management API 中所有用户管理相关的接口。所有接口均需要管理员身份认证。

接口概览

方法	路径	说明
GET	/api/v1/users	获取用户列表
POST	/api/v1/users	创建用户
GET	/api/v1/users/:id	获取用户详情
PATCH	/api/v1/users/:id	更新用户信息
DELETE	/api/v1/users/:id	删除用户
PATCH	/api/v1/users/:id/password	重置用户密码
PATCH	/api/v1/users/:id/suspend	停用/启用用户
GET	/api/v1/users/:id/roles	获取用户角色
PUT	/api/v1/users/:id/roles	分配用户角色
GET	/api/v1/users/:id/organizations	获取用户所属组织

获取用户列表

获取系统中的用户列表，支持分页和搜索。

请求

GET /api/v1/users?page=1&page_size=20&search=张三

查询参数

参数	类型	必填	说明
page	integer	否	页码，默认 1
page_size	integer	否	每页数量，默认 20
search	string	否	搜索关键词，匹配用户名、邮箱、手机号、显示名称

响应示例

json

{
  "code": 0,
  "message": "success",
  "result": {
    "data": [
      {
        "id": "abc123def456ghi789012",
        "username": "zhangsan",
        "primary_email": "zhangsan@example.com",
        "primary_phone": "+8613800138000",
        "name": "张三",
        "avatar": "https://cdn.example.com/avatars/zhangsan.png",
        "gender": "male",
        "is_suspended": false,
        "last_sign_in_at": "2026-02-10T08:30:00Z",
        "sign_in_count": 42,
        "created_at": "2026-01-01T00:00:00Z"
      }
    ],
    "total": 1,
    "page": 1,
    "page_size": 20
  }
}

创建用户

创建一个新用户。用户名为必填项，密码最少 6 位字符。

请求

POST /api/v1/users
Content-Type: application/json

请求体

字段	类型	必填	说明
username	string	是	用户名，系统内唯一
password	string	是	密码，最少 6 位字符
email	string	否	邮箱地址
phone	string	否	手机号
name	string	否	显示名称
avatar	string	否	头像 URL

请求示例

json

{
  "username": "zhangsan",
  "password": "P@ssw0rd123",
  "email": "zhangsan@example.com",
  "phone": "+8613800138000",
  "name": "张三",
  "avatar": "https://cdn.example.com/avatars/default.png"
}

响应示例

json

{
  "code": 0,
  "message": "success",
  "result": {
    "id": "abc123def456ghi789012",
    "username": "zhangsan",
    "primary_email": "zhangsan@example.com",
    "primary_phone": "+8613800138000",
    "name": "张三",
    "avatar": "https://cdn.example.com/avatars/default.png",
    "gender": "unknown",
    "is_suspended": false,
    "last_sign_in_at": null,
    "sign_in_count": 0,
    "created_at": "2026-02-13T10:00:00Z"
  }
}

错误情况

错误码	说明
400	参数验证失败（用户名为空、密码少于 6 位等）
409	用户名/邮箱/手机号已被占用

获取用户详情

根据用户 ID 获取用户完整信息。

请求

GET /api/v1/users/:id

路径参数

参数	类型	必填	说明
id	string	是	用户 ID（nanoid）

响应示例

json

{
  "code": 0,
  "message": "success",
  "result": {
    "id": "abc123def456ghi789012",
    "username": "zhangsan",
    "primary_email": "zhangsan@example.com",
    "primary_phone": "+8613800138000",
    "name": "张三",
    "avatar": "https://cdn.example.com/avatars/zhangsan.png",
    "gender": "male",
    "is_suspended": false,
    "last_sign_in_at": "2026-02-10T08:30:00Z",
    "sign_in_count": 42,
    "created_at": "2026-01-01T00:00:00Z"
  }
}

错误情况

错误码	说明
404	用户不存在

更新用户信息

部分更新用户的个人资料。仅传入需要更新的字段即可。

请求

PATCH /api/v1/users/:id
Content-Type: application/json

路径参数

参数	类型	必填	说明
id	string	是	用户 ID

请求体（所有字段均为可选）

字段	类型	说明
name	string	显示名称
email	string	邮箱地址
phone	string	手机号
avatar	string	头像 URL

请求示例

json

{
  "name": "张三丰",
  "email": "zhangsan_new@example.com"
}

响应示例

json

{
  "code": 0,
  "message": "success",
  "result": {
    "id": "abc123def456ghi789012",
    "username": "zhangsan",
    "primary_email": "zhangsan_new@example.com",
    "primary_phone": "+8613800138000",
    "name": "张三丰",
    "avatar": "https://cdn.example.com/avatars/zhangsan.png",
    "gender": "male",
    "is_suspended": false,
    "last_sign_in_at": "2026-02-10T08:30:00Z",
    "sign_in_count": 42,
    "created_at": "2026-01-01T00:00:00Z"
  }
}

错误情况

错误码	说明
404	用户不存在
409	邮箱/手机号已被其他用户占用

删除用户

永久删除一个用户。此操作不可逆，用户的所有数据和关联关系将被移除。

请求

DELETE /api/v1/users/:id

路径参数

参数	类型	必填	说明
id	string	是	用户 ID

响应示例

json

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

错误情况

错误码	说明
404	用户不存在

重置用户密码

管理员重置指定用户的登录密码。

请求

PATCH /api/v1/users/:id/password
Content-Type: application/json

路径参数

参数	类型	必填	说明
id	string	是	用户 ID

请求体

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

请求示例

json

{
  "password": "NewP@ssw0rd456"
}

响应示例

json

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

错误情况

错误码	说明
400	密码不符合要求（少于 6 位）
404	用户不存在

停用/启用用户

切换用户的停用状态。停用后用户无法登录，启用后恢复正常。

请求

PATCH /api/v1/users/:id/suspend
Content-Type: application/json

路径参数

参数	类型	必填	说明
id	string	是	用户 ID

请求体

字段	类型	必填	说明
is_suspended	boolean	是	`true` 停用，`false` 启用

请求示例（停用用户）

json

{
  "is_suspended": true
}

请求示例（启用用户）

json

{
  "is_suspended": false
}

响应示例

json

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

错误情况

错误码	说明
404	用户不存在

获取用户角色

查询指定用户当前拥有的所有角色。

请求

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

路径参数

参数	类型	必填	说明
id	string	是	用户 ID

响应示例

json

{
  "code": 0,
  "message": "success",
  "result": [
    {
      "id": "role_abc123",
      "name": "editor",
      "description": "Content editor role"
    }
  ]
}

分配用户角色

替换用户的角色列表。传入角色 ID 数组，系统会覆盖用户当前的所有角色分配。

请求

PUT /api/v1/users/:id/roles
Content-Type: application/json

路径参数

参数	类型	必填	说明
id	string	是	用户 ID

请求体

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

请求示例

json

{
  "role_ids": ["role_abc123", "role_def456"]
}

响应示例

json

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

说明

使用 PUT 语义，传入的角色列表将完全替换用户原有的角色
传入空数组 [] 将清除用户的所有角色
如果某个角色 ID 不存在，接口将返回错误

获取用户所属组织

查询指定用户加入的所有组织列表，支持分页。

请求

GET /api/v1/users/:id/organizations?page=1&page_size=20

路径参数

参数	类型	必填	说明
id	string	是	用户 ID

查询参数

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

响应示例

json

{
  "code": 0,
  "message": "success",
  "result": {
    "data": [
      {
        "id": "org_abc123def456ghi78",
        "name": "Code Bird Technology",
        "description": "Core engineering team",
        "created_at": "2026-01-15T00:00:00Z"
      }
    ],
    "total": 1,
    "page": 1,
    "page_size": 20
  }
}

用户管理操作 ​

接口概览 ​

获取用户列表 ​

创建用户 ​

获取用户详情 ​

更新用户信息 ​

删除用户 ​

重置用户密码 ​

停用/启用用户 ​

获取用户角色 ​

分配用户角色 ​

获取用户所属组织 ​

用户管理操作

接口概览

获取用户列表

创建用户

获取用户详情

更新用户信息

删除用户

重置用户密码

停用/启用用户

获取用户角色

分配用户角色

获取用户所属组织