用户管理API

引用文件

本文引用的文件

简介

本文件面向“用户管理API”的使用与集成，重点覆盖以下能力：

管理员用户查询接口：按ID查询单个用户、批量查询用户、按部门/岗位查询用户、查询用户下属
用户有效性校验接口：校验单个或多个用户是否有效（存在且启用）
用户数据传输对象：AdminUserRespDTO 的字段定义与用途
请求参数、响应结构、错误处理机制
实际请求/响应示例与业务逻辑说明（如用户状态验证、数据转换）

项目结构

用户管理API主要分布在系统模块的API层与业务实现层：

API接口层：对外暴露Feign接口，定义RPC服务契约
业务实现层：提供具体查询、校验、转换等逻辑
控制器层：提供HTTP REST接口（用于管理后台）
DTO与VO：定义请求/响应的数据结构

Mermaid Diagram Code:

graph TB
subgraph "API层"
AIF["AdminUserApi 接口"]
AIM["AdminUserApiImpl 实现"]
end
subgraph "业务层"
Svc["AdminUserServiceImpl"]
end
subgraph "控制器层"
Ctl["UserController"]
end
subgraph "数据与视图"
DTO["AdminUserRespDTO"]
VO1["UserPageReqVO"]
VO2["UserSaveReqVO"]
end
Ctl --> Svc
AIF --> AIM
AIM --> Svc
Svc --> DTO
Ctl --> VO1
Ctl --> VO2

图表来源

章节来源

核心组件

AdminUserApi：定义RPC服务接口，包括按ID查询、批量查询、按部门/岗位查询、查询下属、用户有效性校验等
AdminUserApiImpl：实现AdminUserApi，负责调用业务服务并进行数据转换
AdminUserServiceImpl：用户服务实现，包含查询、校验、分页、导入导出等核心逻辑
AdminUserRespDTO：RPC响应DTO，承载用户基本信息（含状态、部门、岗位、手机号、头像等）
UserController：管理后台HTTP接口，提供分页、导入导出、简单列表等能力
UserPageReqVO / UserSaveReqVO：分页查询与保存/更新的请求参数对象

章节来源

架构总览

用户管理API采用“接口 + 实现 + 服务 + 控制器”的分层设计：

API层（Feign）：统一对外RPC契约，支持自动翻译（AutoTrans）与批量查询
业务层：封装用户查询、校验、状态判断、数据权限等复杂逻辑
控制器层：提供HTTP接口，便于管理后台使用
DTO/VO：清晰区分请求与响应结构，便于前后端协作

Mermaid Diagram Code:

sequenceDiagram
participant Client as "客户端"
participant API as "AdminUserApi"
participant Impl as "AdminUserApiImpl"
participant Svc as "AdminUserServiceImpl"
Client->>API : GET /user/get?id=1
API->>Impl : 转发请求
Impl->>Svc : getUser(id)
Svc-->>Impl : AdminUserDO
Impl-->>API : AdminUserRespDTO
API-->>Client : {code, msg, data}
Note over Client,Svc : 用户有效性校验<br/>GET /user/valid?ids=1,2

图表来源

详细组件分析

接口：按ID查询用户

接口路径：GET /user/get
功能：根据用户ID查询单个用户
请求参数
- id：Long，必填，示例值：1
响应数据结构
- 成功时返回：CommonResult<AdminUserRespDTO>
- AdminUserRespDTO 字段：id、nickname、status、deptId、postIds、mobile、avatar、username
业务逻辑
- 通过业务服务查询用户，若不存在返回空结果
- 使用AutoTrans对nickname进行翻译（基于注解配置）
错误处理
- 未找到用户时返回空数据（非异常），由调用方自行判断

章节来源

接口：批量查询用户

接口路径：GET /user/list
功能：根据用户ID集合批量查询用户
请求参数
- ids：Collection<Long>，必填，示例值：1,2
响应数据结构
- 成功时返回：CommonResult<List<AdminUserRespDTO>>
业务逻辑
- 通过业务服务批量查询，返回用户列表
- 支持Map形式快速获取：getUserMap(ids) 将返回 Map<Long, AdminUserRespDTO>
错误处理
- 若ids为空，直接返回空列表

章节来源

接口：按部门查询用户

接口路径：GET /user/list-by-dept-id
功能：根据部门ID集合查询用户
请求参数
- deptIds：Collection<Long>，必填，示例值：1,2
响应数据结构
- 成功时返回：CommonResult<List<AdminUserRespDTO>>
业务逻辑
- 通过业务服务查询部门下的用户列表
错误处理
- 若deptIds为空，返回空列表

章节来源

AdminUserApi.java

接口：按岗位查询用户

接口路径：GET /user/list-by-post-id
功能：根据岗位ID集合查询用户
请求参数
- postIds：Collection<Long>，必填，示例值：2,3
响应数据结构
- 成功时返回：CommonResult<List<AdminUserRespDTO>>
业务逻辑
- 通过用户-岗位映射查询用户ID集合，再批量查询用户
错误处理
- 若postIds为空，返回空列表

章节来源

AdminUserApi.java

接口：查询用户下属

接口路径：GET /user/list-by-subordinate
功能：查询指定用户的下属用户
请求参数
- id：Long，必填，示例值：1
响应数据结构
- 成功时返回：CommonResult<List<AdminUserRespDTO>>
业务逻辑
- 通过业务服务查询用户下属（具体实现由服务层提供）
错误处理
- 若用户不存在，服务层会抛出相应异常

章节来源

AdminUserApi.java

接口：用户有效性校验

接口路径：GET /user/valid
功能：校验用户是否有效（存在且启用）
请求参数
- ids：Collection<Long>，必填，示例值：3,5
响应数据结构
- 成功时返回：CommonResult<Boolean>，校验通过返回true
业务逻辑
- 校验规则：
  - 用户必须存在
  - 用户状态必须为启用
- 若任一用户不满足条件，将抛出异常（如用户不存在、用户被禁用）
错误处理
- 用户不存在：抛出“用户不存在”异常
- 用户被禁用：抛出“用户被禁用”异常

Mermaid Diagram Code:

flowchart TD
Start(["开始"]) --> CheckEmpty["检查ids是否为空"]
CheckEmpty --> |是| ReturnTrue["返回true"]
CheckEmpty --> |否| FetchUsers["批量查询用户"]
FetchUsers --> Loop["遍历ids逐个校验"]
Loop --> Exists{"用户是否存在？"}
Exists --> |否| ThrowNotFound["抛出'用户不存在'异常"]
Exists --> |是| Enabled{"用户状态=启用？"}
Enabled --> |否| ThrowDisabled["抛出'用户被禁用'异常"]
Enabled --> |是| Next["继续下一个"]
Next --> Loop
Loop --> |完成| ReturnTrue

图表来源

AdminUserServiceImpl.java

章节来源

数据传输对象：AdminUserRespDTO

字段说明
- id：Long，用户ID
- nickname：String，用户昵称（支持自动翻译）
- status：Integer，用户状态（启用/禁用）
- deptId：Long，所属部门ID
- postIds：Set<Long>，岗位ID集合
- mobile：String，手机号码
- avatar：String，头像URL
- username：String，用户账号
用途
- RPC响应载体，用于跨模块/微服务间传递用户信息
- 与AutoTrans注解配合，实现字段的自动翻译

章节来源

管理后台HTTP接口（参考）

GET /system/user/page：分页查询用户，返回UserRespVO列表
GET /system/user/get：按ID查询用户，返回UserRespVO
GET /system/user/simple-list：获取启用状态的用户精简列表
POST /system/user/import：导入用户Excel
GET /system/user/export：导出用户Excel
以上接口用于管理后台，与RPC接口AdminUserApi互补

章节来源

UserController.java

依赖关系分析

AdminUserApiImpl 依赖 AdminUserService 与 DeptService，负责调用服务并进行数据转换
AdminUserServiceImpl 提供用户查询、校验、分页、导入导出等核心能力
AdminUserApi 通过AutoTrans注解对nickname进行翻译
UserController 作为HTTP接口，调用AdminUserService实现分页、导入导出等功能

Mermaid Diagram Code:

classDiagram
class AdminUserApi {
+getUser(id)
+getUserList(ids)
+getUserListByDeptIds(deptIds)
+getUserListByPostIds(postIds)
+getUserListBySubordinate(id)
+validateUserList(ids)
}
class AdminUserApiImpl {
-AdminUserService userService
-DeptService deptService
+getUser(id)
+getUserList(ids)
+getUserListByDeptIds(deptIds)
+getUserListByPostIds(postIds)
+getUserListBySubordinate(id)
+validateUserList(ids)
}
class AdminUserServiceImpl {
+getUser(id)
+getUserList(ids)
+getUserListByDeptIds(deptIds)
+getUserListByPostIds(postIds)
+validateUserList(ids)
}
class AdminUserRespDTO {
+id
+nickname
+status
+deptId
+postIds
+mobile
+avatar
+username
}
AdminUserApiImpl ..|> AdminUserApi
AdminUserApiImpl --> AdminUserServiceImpl : "调用"
AdminUserApiImpl --> AdminUserRespDTO : "转换"

图表来源

章节来源

性能考量

批量查询：优先使用 /user/list 或 /user/get 的批量版本，减少多次RPC调用
自动翻译：AutoTrans在RPC层生效，注意翻译字段的缓存与性能影响
分页与导出：管理后台的分页与导出接口建议结合业务场景设置合理的分页大小
数据权限：服务层在创建/更新时会关闭数据权限以确保唯一性校验准确，避免因权限导致的查询偏差

故障排查指南

常见错误码
- 用户不存在：validateUserList 校验时抛出
- 用户被禁用：validateUserList 校验时抛出
全局异常处理
- GlobalExceptionHandler 统一捕获并返回标准错误响应
排查步骤
- 确认请求参数：id/ids/deptIds/postIds 是否为空或格式错误
- 确认用户状态：被禁用的用户不会通过有效性校验
- 检查RPC调用链：AdminUserApiImpl -> AdminUserServiceImpl -> Mapper/Service

章节来源

结论

本文档梳理了用户管理API的核心接口、数据结构与业务逻辑，明确了RPC层与业务层的职责边界，并提供了错误处理与性能优化建议。在实际集成中，建议优先使用批量查询与有效性校验接口，确保调用链稳定与高效。

目录​

简介​

项目结构​

核心组件​

架构总览​

详细组件分析​

接口：按ID查询用户​

接口：批量查询用户​

接口：按部门查询用户​

接口：按岗位查询用户​

接口：查询用户下属​

接口：用户有效性校验​

数据传输对象：AdminUserRespDTO​

管理后台HTTP接口（参考）​

依赖关系分析​

性能考量​

故障排查指南​

结论​

目录

简介

项目结构

核心组件

架构总览

详细组件分析

接口：按ID查询用户

接口：批量查询用户

接口：按部门查询用户

接口：按岗位查询用户

接口：查询用户下属

接口：用户有效性校验

数据传输对象：AdminUserRespDTO

管理后台HTTP接口（参考）

依赖关系分析

性能考量

故障排查指南

结论