外观
用户管理接口文档
本接口用于对系统中的**用户（User）**资源进行全生命周期管理，遵循 RESTful 设计规范，以 HTTP 方法语义化操作，统一使用 JSON 格式进行数据交互。
资源路径：
/system/user-api
实体类：UserDTO（增删改查共用）
公共请求头
⚠️ 注意：本接口需携带有效的
access_token进行身份验证，未授权访问将被拒绝。
Header 参数（http header）
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| Authorization | String | 是 | 请求令牌，Bearer <access_token> |
接口列表
| 操作 | 方法 | 路径 | 说明 |
|---|---|---|---|
| 创建用户 | POST | /system/user-api | 新增一个系统用户 |
| 查询用户 | GET | /system/user-api/{id} | 根据 id 获取用户详情 |
| 更新用户 | PUT | /system/user-api | 全量更新用户信息 |
| 删除用户 | DELETE | /system/user-api/{id} | 根据 id 删除用户 |
实体类定义（UserDTO）
所有接口的请求体（Request Body）或返回数据（Response Data）均基于以下结构：
JSON 示例
点击展开 JSON 数据
json
{
"roleIds": [
2
],
"postIds": [],
"user": {
"tenantId": "000000",
"userId": "1951108854518575106",
"deptId": 100,
"userName": "zhao**",
"password": "******",
"nickName": "赵某某",
"email": "",
"phonenumber": "",
"sex": "0",
"avatar": "",
"status": "0"
}
}主体结构说明
| 参数名 | 类型 | 说明 |
|---|---|---|
roleIds | Integer[] | 分配的角色 ID 列表（如 [2]） |
postIds | Integer[] | 分配的岗位 ID 列表（如 [3]） |
user | Object | 用户基本信息 |
⚠️ 注意：
- 创建（POST）时：必须提供
user和roleIds（至少一个角色）；- 更新（PUT）时：需提供完整结构，包含
userId；- 查询（GET）时：返回扩展信息（如部门、角色详情等，见实际响应）；
- 密码字段仅在创建时有效，更新时通常忽略。
用户基本信息
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
userId | String | 否 | 用户 ID（创建时不传，由服务端生成） |
userName | String | 是 | 登录账号（唯一） |
password | String | 是（仅创建） | 登录密码（明文，服务端加密存储） |
nickName | String | 是 | 昵称 |
email | String | 否 | 邮箱 |
phonenumber | String | 否 | 手机号 |
sex | String | 否 | 性别（"0" 男，"1" 女，"2" 未知） |
avatar | String | 否 | 头像 URL |
status | String | 否 | 状态（"0" 正常，"1" 停用） |
deptId | Number | 是 | 所属部门 ID |
tenantId | String | 是 | 所属租户编码 |
🔒 安全提示：
password字段不会出现在查询响应中（已被@JsonIgnore过滤）。
接口详情
创建用户（POST）
请求
http
POST /system/user-api
Content-Type: application/json
Authorization: Bearer <token>点击展开 JSON 数据
json
{
"roleIds": [
2
],
"postIds": [
3
],
"user": {
"tenantId": "000000",
"deptId": 100,
"userName": "newuser01",
"password": "123456",
"nickName": "新用户",
"email": "newuser@example.com",
"phonenumber": "13800138000",
"sex": "0",
"status": "0"
}
}响应
点击展开 JSON 数据
json
{
"code": 200,
"msg": "操作成功",
"data": null
}查询用户（GET）
请求
http
GET /system/user-api/1951108854518575106
Authorization: Bearer <token>路径参数
| 参数 | 位置 | 必填 | 说明 |
|---|---|---|---|
id | path | 是 | 用户的系统内部 ID |
响应
返回包含
user、roles、posts、dept等完整信息的对象（参考你提供的完整 JSON 结构）。
注意：password字段不会出现。
点击展开 JSON 数据（简化版）
json
{
"code": 200,
"msg": "操作成功",
"data": {
"roleIds": [
2
],
"postIds": [],
"roles": [
/* 所有可用角色 */
],
"posts": [
/* 所有岗位 */
],
"user": {
"userId": "1951108854518575106",
"userName": "zhao**",
"nickName": "赵某某",
"deptId": 100,
"status": "0",
"dept": {
/* 部门详情 */
},
"roles": [
/* 已分配角色详情 */
]
}
}
}更新用户（PUT）
请求
http
PUT /system/user-api
Content-Type: application/json
Authorization: Bearer <token>点击展开 JSON 数据
json
{
"roleIds": [
2,
1949770609288851458
],
"postIds": [
2
],
"user": {
"userId": "1951108854518575106",
"tenantId": "000000",
"deptId": 100,
"userName": "zhao**",
"nickName": "赵某某-更新",
"email": "updated@example.com",
"phonenumber": "13900139000",
"sex": "0",
"status": "0"
}
}🔁 注意：
- 必须包含
userId；password字段在此操作中无效（如需改密，应调用独立“修改密码”接口）；- 此为全量更新，未传字段可能被重置。
响应
点击展开 JSON 数据
json
{
"code": 200,
"msg": "操作成功",
"data": null
}删除用户（DELETE）
请求
http
DELETE /system/user-api/1951108854518575106
Authorization: Bearer <token>路径参数
| 参数 | 位置 | 必填 | 说明 |
|---|---|---|---|
id | path | 是 | 用户的系统 ID |
响应
点击展开 JSON 数据
json
{
"code": 200,
"msg": "操作成功",
"data": null
}安全与注意事项
- 密码安全：
password字段仅在创建用户时接受，且绝不会返回给前端（通过@JsonIgnore自动过滤）。 - 权限控制：当前用户只能管理同租户下的用户，跨租户操作将被拒绝。
- 状态管理：停用用户（
status = "1"）后，该账号无法登录。