# 用户聚合查询设计规格 > **日期**: 2026-06-06 > **状态**: 已批准 > **作者**: AI Assistant > **相关模块**: rui-service-user --- ## 1. 背景与问题 ### 1.1 现状 当前用户数据分散在4张表中： | 表名 | 说明 | |------|------| | `uc_user` | 用户基础信息（用户名、密码、状态等） | | `uc_user_detail` | 用户详情（昵称、邮箱、手机号等） | | `uc_user_dept` | 用户部门关联（支持多部门，有主部门标记） | | `uc_user_post` | 用户岗位关联（支持多岗位） | ### 1.2 问题 - **前端请求过多**：获取完整用户信息需要3个独立请求 - **列表页性能差**：100条用户数据需要 1 + 100 + 100 = 201 个请求 - **数据一致性难保证**：多个请求可能部分失败 ### 1.3 约束条件 - 一个用户通常关联 **1个主部门 + 少量岗位** - 需要支持 **多租户**（tenantId） - 必须 **保持向后兼容** - 需要 **缓存优化** --- ## 2. 设计目标 1. **减少前端请求**：从3个减少到1个 2. **优化列表页性能**：批量查询，避免 N+1 3. **引入缓存**：Redis 缓存用户聚合数据 4. **保持兼容性**：现有接口不受影响 --- ## 3. 技术方案 ### 3.1 总体架构 ``` ┌─────────────┐ ┌──────────────────┐ ┌──────────────┐ │ 前端 │────▶│ UserController │────▶│ UserService │ └─────────────┘ └──────────────────┘ └──────┬───────┘ │ ┌────────────────────────────┼────────────────────────────┐ │ │ │ ▼ ▼ ▼ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ Redis Cache │ │ uc_user_dept │ │ uc_user_post │ │ user:agg:{id} │ │ (主部门+关联) │ │ (岗位关联) │ └─────────────────┘ └─────────────────┘ └─────────────────┘ ``` ### 3.2 核心策略 - **保留关联表**：不改表结构，保持多对多关系的灵活性 - **聚合查询**：后端做 JOIN 或批量 IN 查询，一次性返回 - **两级缓存**： - L1：单用户聚合数据缓存（Redis） - L2：批量查询结果不缓存（避免缓存过大） - **缓存失效**：数据变更时主动失效 --- ## 4. 数据模型 ### 4.1 新增 VO 对象 ```java package com.rui.service.user.vo; import com.rui.service.user.entity.User; import io.swagger.v3.oas.annotations.media.Schema; import lombok.Data; import lombok.EqualsAndHashCode; import java.util.List; /** * 用户聚合信息（包含部门、岗位） */ @Data @EqualsAndHashCode(callSuper = true) @Schema(description = "用户聚合信息") public class UserAggregateVO extends User { @Schema(description = "用户详情") private UserDetailVO detail; @Schema(description = "部门列表") private List depts; @Schema(description = "岗位列表") private List posts; @Schema(description = "主部门ID") private Long mainDeptId; @Schema(description = "主部门名称") private String mainDeptName; } ``` ### 4.2 部门/岗位 VO ```java @Data @Schema(description = "用户部门信息") public class UserDeptVO { @Schema(description = "部门ID") private Long deptId; @Schema(description = "部门名称") private String deptName; @Schema(description = "是否主部门") private Boolean main; } @Data @Schema(description = "用户岗位信息") public class UserPostVO { @Schema(description = "岗位ID") private Long postId; @Schema(description = "岗位名称") private String postName; } ``` --- ## 5. 接口设计 ### 5.1 新增接口 #### 5.1.1 获取用户聚合信息（单用户） ``` GET /user/admin/user/{id}/aggregate ``` **响应示例：** ```json { "code": 200, "msg": "success", "data": { "id": 1, "username": "admin", "userNo": "U001", "userType": 2, "status": 1, "detail": { "nickname": "管理员", "realName": "系统管理员", "email": "admin@example.com", "phone": "13800138000" }, "depts": [ { "deptId": 1, "deptName": "技术部", "main": true }, { "deptId": 2, "deptName": "产品部", "main": false } ], "posts": [ { "postId": 1, "postName": "Java开发工程师" } ], "mainDeptId": 1, "mainDeptName": "技术部" } } ``` #### 5.1.2 用户列表（增强版） 复用现有 `/user/admin/user` 列表接口，在响应中增加 `depts` 和 `posts` 字段。 **实现方式：** - 列表查询时，先查询用户基础数据 - 批量查询所有用户的部门和岗位 - 组装到响应中 ### 5.2 现有接口保持不变 以下接口继续保留，不受影响： - `GET /user/admin/user/{id}` — 用户基础信息 - `GET /user/admin/user-dept/user/{userId}` — 用户部门列表 - `GET /user/admin/user-post/user/{userId}` — 用户岗位列表 - `GET /user/admin/detail` — 用户详情（uc_user_detail） --- ## 6. 缓存设计 ### 6.1 缓存策略 | 缓存项 | Key 格式 | TTL | 说明 | |--------|---------|-----|------| | 用户聚合信息 | `user:agg:{tenantId}:{userId}` | 10分钟 | 单用户完整数据 | | 用户部门列表 | `user:dept:{tenantId}:{userId}` | 10分钟 | 部门ID列表 | | 用户岗位列表 | `user:post:{tenantId}:{userId}` | 10分钟 | 岗位ID列表 | ### 6.2 缓存失效 **触发时机：** - 用户部门变更（assignDepts、setMainDept） - 用户岗位变更（assignPosts） - 用户信息变更（update） - 用户删除 **失效逻辑：** ```java private void evictUserCache(Long userId) { Long tenantId = AuthUtil.getTenantId(); redisUtil.del(String.format("user:agg:%s:%s", tenantId, userId)); redisUtil.del(String.format("user:dept:%s:%s", tenantId, userId)); redisUtil.del(String.format("user:post:%s:%s", tenantId, userId)); } ``` ### 6.3 缓存穿透防护 - 查询不到数据时，缓存空值（TTL 1分钟） - 使用布隆过滤器（可选，初期可不用） --- ## 7. 查询逻辑 ### 7.1 单用户聚合查询 ```java @Cacheable(value = "user:agg", key = "#tenantId + ':' + #userId") public UserAggregateVO getUserAggregate(Long userId, Long tenantId) { // 1. 查询用户基础信息 User user = userMapper.selectById(userId); if (user == null) { return null; } // 2. 查询用户详情 UserDetail detail = userDetailMapper.selectOne( new LambdaQueryWrapper() .eq(UserDetail::getUserId, userId) ); // 3. 查询部门（带名称） List depts = userDeptMapper.selectDeptListByUserId(userId); // 4. 查询岗位（带名称） List posts = userPostMapper.selectPostListByUserId(userId); // 5. 组装 UserAggregateVO vo = new UserAggregateVO(); BeanUtils.copyProperties(user, vo); vo.setDetail(convertDetail(detail)); vo.setDepts(depts); vo.setPosts(posts); // 6. 提取主部门 depts.stream() .filter(UserDeptVO::getMain) .findFirst() .ifPresent(main -> { vo.setMainDeptId(main.getDeptId()); vo.setMainDeptName(main.getDeptName()); }); return vo; } ``` ### 7.2 批量列表查询优化 **问题：** 列表页有100条数据，不能每条都查一次数据库 **方案：** 批量 IN 查询 ```java public Page listUserAggregate(Page page, QueryWrapper query) { // 1. 查询用户基础数据 Page userPage = userMapper.selectPage(page, query); List users = userPage.getRecords(); if (users.isEmpty()) { return new Page<>(); } // 2. 提取所有用户ID List userIds = users.stream() .map(User::getId) .collect(Collectors.toList()); // 3. 批量查询部门（一次查询） Map> deptMap = userDeptMapper .selectDeptListByUserIds(userIds) .stream() .collect(Collectors.groupingBy(UserDeptVO::getUserId)); // 4. 批量查询岗位（一次查询） Map> postMap = userPostMapper .selectPostListByUserIds(userIds) .stream() .collect(Collectors.groupingBy(UserPostVO::getUserId)); // 5. 批量查询详情（一次查询） Map detailMap = userDetailMapper .selectList( new LambdaQueryWrapper() .in(UserDetail::getUserId, userIds) ) .stream() .collect(Collectors.toMap(UserDetail::getUserId, Function.identity())); // 6. 组装 List records = users.stream().map(user -> { UserAggregateVO vo = new UserAggregateVO(); BeanUtils.copyProperties(user, vo); vo.setDepts(deptMap.getOrDefault(user.getId(), Collections.emptyList())); vo.setPosts(postMap.getOrDefault(user.getId(), Collections.emptyList())); vo.setDetail(convertDetail(detailMap.get(user.getId()))); // 提取主部门 vo.getDepts().stream() .filter(UserDeptVO::getMain) .findFirst() .ifPresent(main -> { vo.setMainDeptId(main.getDeptId()); vo.setMainDeptName(main.getDeptName()); }); return vo; }).collect(Collectors.toList()); // 7. 构建分页结果 Page result = new Page<>(); result.setCurrent(userPage.getCurrent()); result.setSize(userPage.getSize()); result.setTotal(userPage.getTotal()); result.setRecords(records); return result; } ``` **SQL 示例（批量查询部门）：** ```xml ``` --- ## 8. 性能优化点 ### 8.1 数据库层面 1. **索引优化**：确保 `uc_user_dept.user_id` 和 `uc_user_post.user_id` 有索引 2. **批量查询**：使用 IN 代替循环查询 3. **按需加载**：列表页只加载必要的字段 ### 8.2 缓存层面 1. **单用户缓存**：详情页使用缓存，10分钟TTL 2. **列表页不缓存**：列表数据变化频繁，直接查数据库 3. **缓存预热**：系统启动时可选择预热（可选） ### 8.3 代码层面 1. **并行查询**：单用户查询时，部门、岗位、详情可并行（CompletableFuture） 2. **懒加载**：如果前端不需要详情，可以不加载 `uc_user_detail` --- ## 9. 边界情况处理 ### 9.1 用户无部门/岗位 - `depts` 返回空列表 `[]` - `posts` 返回空列表 `[]` - `mainDeptId` 和 `mainDeptName` 为 `null` ### 9.2 缓存穿透 - 用户不存在时，缓存空值（TTL 1分钟） - 使用 `Optional` 包装返回 ### 9.3 缓存雪崩 - TTL 加随机偏移：`10分钟 + random(0, 60)秒` - 使用互斥锁（可选） ### 9.4 数据更新同步 - 所有更新操作后主动失效缓存 - 使用事务确保数据库和缓存一致性 --- ## 10. 兼容性 ### 10.1 向后兼容 - 现有接口完全保留 - 新增 `/aggregate` 接口，不影响旧接口 - 前端可以逐步迁移 ### 10.2 前端迁移路径 1. **第一阶段**：新增聚合接口，前端详情页切换到新接口 2. **第二阶段**：列表页切换到批量查询 3. **第三阶段**：废弃旧接口（可选） --- ## 11. 安全考虑 1. **权限校验**：复用现有 `@AutoPermission("uc:user")` 2. **数据隔离**：所有查询自动加上 `tenant_id` 条件 3. **敏感信息**：密码字段不返回 --- ## 12. 监控与日志 1. **缓存命中率**：监控 `user:agg:*` 的命中情况 2. **查询耗时**：记录批量查询的执行时间 3. **慢查询**：超过100ms的查询记录日志 --- ## 13. 风险评估 | 风险 | 概率 | 影响 | 缓解措施 | |------|------|------|----------| | 缓存数据不一致 | 中 | 中 | 更新时主动失效缓存 | | 批量查询性能差 | 低 | 高 | 索引优化 + 分页 | | 内存占用过高 | 低 | 中 | 控制缓存TTL + 分页大小 | --- ## 14. 附录 ### 14.1 涉及文件清单 - `rui-service-user/src/main/java/com/rui/service/user/vo/UserAggregateVO.java`（新增） - `rui-service-user/src/main/java/com/rui/service/user/vo/UserDeptVO.java`（新增） - `rui-service-user/src/main/java/com/rui/service/user/vo/UserPostVO.java`（新增） - `rui-service-user/src/main/java/com/rui/service/user/service/IUserService.java`（修改） - `rui-service-user/src/main/java/com/rui/service/user/service/impl/UserServiceImpl.java`（修改） - `rui-service-user/src/main/java/com/rui/service/user/controller/UserController.java`（修改） - `rui-service-user/src/main/java/com/rui/service/user/mapper/UserDeptMapper.java`（修改） - `rui-service-user/src/main/java/com/rui/service/user/mapper/UserPostMapper.java`（修改） - `rui-service-user/src/main/resources/mapper/UserDeptMapper.xml`（修改） - `rui-service-user/src/main/resources/mapper/UserPostMapper.xml`（修改） ### 14.2 数据库索引检查 确保以下索引存在： ```sql -- uc_user_dept 表 CREATE INDEX idx_user_dept_user_id ON uc_user_dept(user_id); CREATE INDEX idx_user_dept_dept_id ON uc_user_dept(dept_id); -- uc_user_post 表 CREATE INDEX idx_user_post_user_id ON uc_user_post(user_id); CREATE INDEX idx_user_post_post_id ON uc_user_post(post_id); -- uc_user_detail 表 CREATE INDEX idx_user_detail_user_id ON uc_user_detail(user_id); ``` --- ## 15. 决策记录 | 决策 | 选择 | 理由 | |------|------|------| | 是否改表结构 | 否 | 关联表设计合理，保持灵活性 | | 列表页是否缓存 | 否 | 数据变化频繁，直接查库更可靠 | | 单用户查询方式 | 并行查询 | 减少RT，提升用户体验 | | 缓存失效策略 | 主动失效 | 数据更新时立即失效，保证一致性 | | 是否返回密码 | 否 | 安全考虑，聚合数据不包含敏感字段 |