Appearance
公共服务
**本文引用的文件** - [UserController.java](file://lemes-cloud/lemes-business-devicemate/lemes-service-dm-common/lemes-service-dm-common-server/src/main/java/com/lenovo/lemes/service/dm/common/controller/UserController.java) - [RoleController.java](file://lemes-cloud/lemes-business-devicemate/lemes-service-dm-common/lemes-service-dm-common-server/src/main/java/com/lenovo/lemes/service/dm/common/controller/RoleController.java) - [SysDictController.java](file://lemes-cloud/lemes-business-devicemate/lemes-service-dm-common/lemes-service-dm-common-server/src/main/java/com/lenovo/lemes/service/dm/common/controller/SysDictController.java) - [DepartmentController.java](file://lemes-cloud/lemes-business-devicemate/lemes-service-dm-common/lemes-service-dm-common-server/src/main/java/com/lenovo/lemes/service/dm/common/controller/DepartmentController.java) - [SysUserApi.java](file://lemes-cloud/lemes-business-devicemate/lemes-service-dm-common/lemes-service-dm-common-common/src/main/java/com/lenovo/lemes/service/dm/common/client/api/SysUserApi.java) - [SysDictApi.java](file://lemes-cloud/lemes-business-devicemate/lemes-service-dm-common/lemes-service-dm-common-common/src/main/java/com/lenovo/lemes/service/dm/common/client/api/SysDictApi.java) - [SysLoginController.java](file://lemes-cloud/lemes-auth/src/main/java/com/lenovo/lemes/auth/controller/SysLoginController.java) - [lemes-service-common-server/pom.xml](file://lemes-cloud/lemes-service-common/lemes-service-common-server/pom.xml) - [lemes-service-common/pom.xml](file://lemes-cloud/lemes-service-common/lemes-service-common/pom.xml)目录
简介
公共服务模块是微服务架构中的基础设施层，面向设备管理业务域提供统一的用户权限管理、组织架构管理、数据字典管理与配置能力。该模块通过标准化的API对外提供用户、角色、部门、字典等基础数据的增删改查与权限控制能力，并与认证网关协同完成登录、令牌刷新与注销等鉴权流程。同时，公共服务模块还承担了跨模块共享的通用配置、日志与工具能力，为上层业务服务提供稳定可靠的基础支撑。
项目结构
公共服务模块采用多模块聚合结构，核心由“公共服务服务端”和“公共服务公共API”两部分组成：
- lemes-service-common-server：对外提供REST接口、集成安全框架与数据源，承载用户、角色、部门、字典等控制器与业务服务。
- lemes-service-common-common：定义跨模块共享的API契约、实体模型与VO模型，确保各业务服务对公共服务的统一调用。
图表来源
章节来源
核心组件
- 用户管理控制器：提供用户新增、查询、更新、删除、导出、角色授权、权限码查询等接口。
- 角色管理控制器：提供角色新增、查询、更新、删除、角色授权用户、角色绑定资源等接口。
- 组织架构控制器：提供部门树形列表、按用户权限过滤、新增/更新/失效化、按编号/名称查询、当前用户部门树等接口。
- 数据字典控制器：提供字典类型分页、字典项查询、新增/修改/删除、批量获取、校验有效性、按名称与编码查询等接口。
- 认证控制器：提供密码登录、令牌刷新、注销、列出在线用户等接口，与OAuth2授权服务器协作完成令牌发放与回收。
章节来源
- UserController.java:24-214
- RoleController.java:23-117
- DepartmentController.java:25-158
- SysDictController.java:25-157
- SysLoginController.java:35-143
架构总览
公共服务在微服务架构中的定位如下：
- 作为基础设施层，向上游业务服务提供统一的用户、角色、部门、字典等基础能力。
- 与认证中心协作，完成登录、令牌发放、刷新与注销，保障跨服务的安全访问。
- 通过公共API模块沉淀接口契约与数据模型，降低耦合度，提升复用性。
图表来源
详细组件分析
用户管理组件
- 职责边界：负责用户生命周期管理、用户与角色关系维护、用户权限码查询、用户信息批量查询与报表权限判定等。
- 关键接口路径：
- 新增用户：POST /user/add
- 用户列表（分页）：POST /user/list
- 用户列表（全量）：POST /user/listAll
- 删除用户：POST /user/delete
- 更新用户：POST /user/update
- 用户授权（添加多角色）：POST /user/addUserRole
- 更新用户授权信息：POST /user/updateUserRole
- 导出用户Excel：POST /user/exportExcel
- 用户详情：POST /user/details
- 根据账号获取用户：GET /user/getUserByAccount
- 根据用户获取角色列表：POST /user/getRoleByUser
- 获取用户权限码：GET /user/getUserPermissionCode
- 批量按用户代号/账号查询：GET /user/getUserByNoOrAccount
- 查询用户信息：POST /user/queryUserInfo
- 根据姓名查询用户：GET /user/queryByName
- 根据姓名批量查询用户：GET /user/queryByNameList
- 报表查询权限判定：GET /user/queryUserReportFlag
- 当前登录用户所在部门（含子部门）用户列表：GET /user/current/deptUser
图表来源
章节来源
角色管理组件
- 职责边界：负责角色的增删改查、角色与用户的关联维护、角色与资源（菜单/权限）的绑定。
- 关键接口路径：
- 新增角色：POST /role/add
- 角色列表（分页）：POST /role/list
- 删除角色：POST /role/delete
- 更新角色：POST /role/update
- 角色授权用户（添加多用户）：POST /role/addRoleUser
- 角色绑定菜单（授权资源）：POST /role/addRoleResource
- 获取角色列表：POST /role/getRole
- 根据角色获取用户列表：POST /role/getUserByRole
- 更新角色用户（批量）：POST /role/updateRoleUser
- 角色详情：POST /role/detail
- 导出角色Excel：POST /role/exportExcel
图表来源
章节来源
组织架构管理组件
- 职责边界：负责部门树形结构的构建与查询、按用户权限过滤部门树、部门信息的新增/更新/失效化、按编号/名称查询部门、当前用户及其下级部门查询等。
- 关键接口路径：
- 部门树形列表：POST /dept/list
- 按用户权限过滤部门树：POST /dept/listByUser
- 新增部门：POST /dept/add
- 更新部门：POST /dept/update
- 部门失效化：POST /dept/delDept
- 校验部门名称重复：POST /dept/checkDeptName
- 部门详情：POST /dept/details
- 根据部门代号查询：GET /dept/deptNo
- 根据部门代号查询（路径变量）：GET /dept/
- 根据部门名称查询：GET /dept/deptName
- 当前登录人部门及下级部门：GET /dept/current/user
- 部门及下级部门：GET /dept/by/deptNo
- 当前工厂部门列表：POST /dept/queryMyCurrentFactoryDepart
图表来源
章节来源
数据字典管理组件
- 职责边界：负责字典类型与字典项的管理、字典缓存与批量查询、字典有效性校验、按名称与编码查询字典等。
- 关键接口路径：
- 分页获取字典类型目录：POST /sysDict/getCatalogListByPage
- 根据字典编码获取字典项列表：GET /sysDict/getItemList/
- 新增/修改字典：POST /sysDict/saveDict
- 获取字典详情：GET /sysDict/getDictInfo/
- 批量逻辑删除字典：POST /sysDict/deleteDictByIds
- 单个字典编码查询字典值：GET /sysDict/getDictList
- 批量获取字典：POST /sysDict/getDictLists
- 根据字典值与编码查询字典名称：POST /sysDict/getDictNameByDictValue
- 根据字典名称与编码查询字典：GET /sysDict/getDictByDictNameAndCode
图表来源
章节来源
认证与授权组件
- 职责边界：负责密码登录、令牌刷新、注销、列出在线用户等，与OAuth2授权服务器协作完成令牌发放与回收。
- 关键接口路径：
- 密码登录：POST /auth/pwdLogin
- 刷新令牌：POST /auth/refreshToken
- 注销：DELETE /auth/logoff
- 列出在线用户：GET /auth/listLoginUser
图表来源
章节来源
依赖分析
公共服务服务端依赖关系如下：
- 依赖公共服务公共模块：用于共享API契约与模型。
- 依赖框架模块：服务通用配置、容器、过滤器、安全框架、数据源等。
- 可选依赖：XML解析、SAML相关组件等。
图表来源
章节来源
性能考虑
- 接口分页与批量查询：优先使用分页接口与批量查询接口，避免一次性加载全量数据。
- 缓存利用：字典模块提供缓存字典列表查询，减少数据库压力；建议在业务侧合理利用缓存。
- 并发控制：登录与令牌刷新接口需注意幂等与并发场景，避免重复发放令牌。
- 日志与审计：控制器层普遍使用系统日志注解，建议结合链路追踪与日志聚合进行性能分析。
- 依赖外部系统：认证中心与授权服务器的可用性直接影响登录与刷新性能，应做好降级与超时配置。
故障排查指南
- 登录失败
- 检查终端标识与客户端配置是否匹配。
- 核对用户名大小写与客户端共享配置。
- 查看授权服务器返回状态与错误信息。
- 令牌刷新失败
- 确认刷新令牌是否有效且未被回收。
- 校验客户端密钥与授权头格式。
- 注销异常
- 确认请求头中携带的访问令牌是否正确。
- 检查授权服务器中是否存在对应授权记录。
- 字典查询为空
- 校验字典编码是否正确。
- 确认缓存是否命中，必要时清理缓存后重试。
- 部门查询范围异常
- 确认当前用户所属工厂与部门层级关系。
- 检查部门是否已被失效化。
章节来源
结论
公共服务模块通过清晰的职责划分与标准化的API契约，为设备管理业务域提供了稳定可靠的用户权限、组织架构与数据字典能力。配合认证中心的OAuth2集成，实现了统一的登录、令牌管理与注销流程。建议在实际集成中遵循分页与批量查询原则，充分利用缓存与日志能力，确保系统的高性能与可维护性。
附录
- 在其他服务中集成公共服务的建议
- 通过公共API模块引入SysUserApi与SysDictApi等接口契约。
- 使用Feign客户端调用公共服务提供的REST接口。
- 在业务服务中统一处理ResultData响应与异常转换。
- 对高频查询接口（如字典）建立本地缓存，降低远程调用开销。
- 对关键操作（用户授权、角色绑定、部门变更）增加审计日志与事务一致性保障。