部门岗位API

引用文件

本文档引用的文件

简介

本文件面向开发与运维人员，系统化梳理部门与岗位管理API的设计与实现，覆盖以下能力：

部门管理：部门树查询、部门详情、部门列表、部门层级关系校验与维护
岗位管理：岗位查询、岗位分页、岗位导出、岗位分配（通过用户-岗位关联表）
组织架构数据结构：部门树、岗位与用户的多对多关联
最佳实践：部门树构建示例、岗位权限配置、组织架构维护策略

项目结构

围绕部门与岗位的模块化组织遵循“控制层-服务层-持久层-数据对象-VO/DTO”的分层设计，关键路径如下：

控制层：DeptController、PostController 提供REST接口
服务层：DeptServiceImpl、PostServiceImpl 实现业务逻辑
持久层：DeptMapper、PostMapper、UserPostMapper 执行数据库操作
数据对象：DeptDO、PostDO、UserPostDO 描述表结构
视图对象：DeptRespVO、PostRespVO、PostPageReqVO 等封装请求/响应

Mermaid Diagram Code:

graph TB
subgraph "控制层"
DC["DeptController<br/>部门控制器"]
PC["PostController<br/>岗位控制器"]
end
subgraph "服务层"
DS["DeptServiceImpl<br/>部门服务实现"]
PS["PostServiceImpl<br/>岗位服务实现"]
end
subgraph "持久层"
DM["DeptMapper<br/>部门Mapper"]
PM["PostMapper<br/>岗位Mapper"]
UPM["UserPostMapper<br/>用户岗位Mapper"]
end
subgraph "数据对象"
DDO["DeptDO<br/>部门DO"]
PDO["PostDO<br/>岗位DO"]
UPDO["UserPostDO<br/>用户岗位DO"]
end
subgraph "视图对象"
DVR["DeptRespVO<br/>部门响应VO"]
DPR["DeptListReqVO<br/>部门查询VO"]
PVR["PostRespVO<br/>岗位响应VO"]
PPP["PostPageReqVO<br/>岗位分页VO"]
end
DC --> DS
PC --> PS
DS --> DM
PS --> PM
PS --> UPM
DM --> DDO
PM --> PDO
UPM --> UPDO
DC --> DVR
DC --> DPR
PC --> PVR
PC --> PPP

图表来源

章节来源

核心组件

部门控制器：提供创建、更新、删除、列表、精简列表、详情等接口
岗位控制器：提供创建、更新、删除、详情、精简列表、分页、导出等接口
部门服务：负责部门树构建、父子关系校验、部门有效性校验
岗位服务：负责岗位唯一性校验、分页查询、批量校验
Mapper层：基于MyBatis-Plus封装通用查询与分页
数据对象：映射数据库表结构，包含基础字段与枚举状态
视图对象：封装请求/响应参数，支持导出与前端展示

章节来源

架构总览

部门与岗位API采用标准的分层架构，控制层暴露REST接口，服务层编排业务规则，持久层执行数据访问，数据对象承载领域模型。

Mermaid Diagram Code:

sequenceDiagram
participant C as "客户端"
participant DC as "DeptController"
participant DS as "DeptServiceImpl"
participant DM as "DeptMapper"
participant DB as "数据库"
C->>DC : GET /system/dept/get?id=1
DC->>DS : getDept(id)
DS->>DM : selectById(id)
DM->>DB : SELECT ...
DB-->>DM : DeptDO
DM-->>DS : DeptDO
DS-->>DC : DeptDO
DC-->>C : DeptRespVO

图表来源

详细组件分析

部门管理API

接口清单
- 创建部门：POST /system/dept/create
- 更新部门：PUT /system/dept/update
- 删除部门：DELETE /system/dept/delete?id={id}
- 获取部门列表：GET /system/dept/list
- 获取部门精简列表：GET /system/dept/simple-list
- 获取部门详情：GET /system/dept/get?id={id}
核心逻辑
- 父部门有效性校验：禁止将自己设为父部门；父部门必须存在且不形成环路
- 部门名称唯一性：同级父部门下名称不可重复
- 子部门遍历：支持按层级递归查询所有子部门
- 部门有效性校验：批量校验部门存在性与启用状态
数据模型
- DeptDO：包含id、name、parentId、sort、leaderUserId、phone、email、status等字段
- VO：DeptRespVO用于响应，DeptListReqVO用于查询条件

Mermaid Diagram Code:

classDiagram
class DeptController {
+createDept(createReqVO)
+updateDept(updateReqVO)
+deleteDept(id)
+getDeptList(reqVO)
+getSimpleDeptList()
+getDept(id)
}
class DeptServiceImpl {
+createDept(createReqVO)
+updateDept(updateReqVO)
+deleteDept(id)
+getDept(id)
+getDeptList(reqVO)
+getChildDeptList(ids)
+validateDeptList(ids)
}
class DeptMapper {
+selectList(reqVO)
+selectByParentIdAndName(parentId,name)
+selectCountByParentId(parentId)
+selectListByParentId(parentIds)
+selectListByLeaderUserId(id)
}
class DeptDO
class DeptRespVO
class DeptListReqVO
DeptController --> DeptServiceImpl : "调用"
DeptServiceImpl --> DeptMapper : "查询"
DeptMapper --> DeptDO : "返回"
DeptController --> DeptRespVO : "转换"
DeptController --> DeptListReqVO : "参数"

图表来源

章节来源

岗位管理API

接口清单
- 创建岗位：POST /system/post/create
- 更新岗位：PUT /system/post/update
- 删除岗位：DELETE /system/post/delete?id={id}
- 获取岗位详情：GET /system/post/get?id={id}
- 获取岗位精简列表：GET /system/post/simple-list
- 获取岗位分页列表：GET /system/post/page
- 导出岗位数据：GET /system/post/export
核心逻辑
- 岗位唯一性校验：名称与编码均需唯一
- 分页查询：支持按编码、名称、状态过滤
- 精简列表：按sort排序，仅返回启用状态
- 批量校验：校验岗位存在性与启用状态
数据模型
- PostDO：包含id、name、code、sort、status、remark等字段
- VO：PostRespVO、PostPageReqVO、PostSimpleRespVO
- RPC接口：PostApi、PostApiImpl、PostRespDTO

Mermaid Diagram Code:

classDiagram
class PostController {
+createPost(createReqVO)
+updatePost(updateReqVO)
+deletePost(id)
+getPost(id)
+getSimplePostList()
+getPostPage(pageReqVO)
+export(response,reqVO)
}
class PostServiceImpl {
+createPost(createReqVO)
+updatePost(updateReqVO)
+deletePost(id)
+getPost(id)
+getPostList(ids,statuses)
+getPostPage(pageReqVO)
+validatePostList(ids)
}
class PostMapper {
+selectList(ids,statuses)
+selectPage(reqVO)
+selectByName(name)
+selectByCode(code)
}
class PostDO
class PostRespVO
class PostPageReqVO
class PostSimpleRespVO
class PostApi {
+validPostList(ids)
+getPostList(ids)
}
class PostApiImpl
class PostRespDTO
PostController --> PostServiceImpl : "调用"
PostServiceImpl --> PostMapper : "查询"
PostMapper --> PostDO : "返回"
PostController --> PostRespVO : "转换"
PostController --> PostPageReqVO : "参数"
PostApiImpl ..|> PostApi : "实现"
PostApiImpl --> PostRespDTO : "转换"

图表来源

章节来源

组织架构数据结构与关系

部门树结构
- DeptDO.parentId 指向父节点，根节点parentId为0
- 支持递归查询子部门，构建完整部门树
岗位与用户关联
- system_user_post 用户岗位关联表，多对多关系
- UserPostDO.userId、UserPostDO.postId 关联用户与岗位
数据模型ER图

Mermaid Diagram Code:

erDiagram
DEPT {
bigint id PK
bigint parent_id
string name
int sort
bigint leader_user_id
string phone
string email
int status
}
POST {
bigint id PK
string name
string code
int sort
int status
string remark
}
USER_POST {
bigint id PK
bigint user_id
bigint post_id
}
DEPT ||--o{ DEPT : "父子关系"
USER_POST }o--|| POST : "关联"
USER_POST }o--|| DEPT : "间接关联(通过用户)"

图表来源

章节来源

部门树构建示例

步骤
1. 以传入的父部门ID集合为起点
2. 循环查询所有直接子部门，直到某层无子部门为止
3. 将每层结果合并，得到完整的子部门集合
复杂度
- 时间复杂度：O(k×h)，k为每层平均子部门数量，h为最大层级深度
- 空间复杂度：O(n)，n为最终子部门总数

Mermaid Diagram Code:

flowchart TD
Start(["开始"]) --> Init["初始化 parentIds = 输入ID集合"]
Init --> Loop{"是否存在子部门?"}
Loop --> |否| End(["结束"])
Loop --> |是| Query["查询当前层所有子部门"]
Query --> Append["追加到结果集"]
Append --> Update["更新 parentIds = 当前层子部门ID集合"]
Update --> Loop

图表来源

DeptServiceImpl.java

章节来源

DeptServiceImpl.java

岗位权限配置与最佳实践

岗位校验
- 通过PostApi.validPostList或PostServiceImpl.validatePostList进行批量校验
- 校验内容：存在性与启用状态
岗位导出
- PostController.export支持导出全部岗位数据，便于审计与备份
岗位分配
- 通过UserPostMapper提供的方法实现用户与岗位的绑定/解绑
- 典型流程：先清理旧关联，再插入新关联，确保一致性

Mermaid Diagram Code:

sequenceDiagram
participant C as "客户端"
participant PC as "PostController"
participant PS as "PostServiceImpl"
participant PM as "PostMapper"
participant DB as "数据库"
C->>PC : GET /system/post/page
PC->>PS : getPostPage(pageReqVO)
PS->>PM : selectPage(pageReqVO)
PM->>DB : SELECT ... ORDER BY id DESC
DB-->>PM : PageResult<PostDO>
PM-->>PS : PageResult<PostDO>
PS-->>PC : PageResult<PostDO>
PC-->>C : PageResult<PostRespVO>

图表来源

章节来源

依赖关系分析

控制器依赖服务接口，服务实现依赖Mapper接口
Mapper依赖MyBatis-Plus的BaseMapperX，统一提供分页、批量查询等能力
数据对象与表结构一一对应，VO/DTO用于接口参数与返回值封装

Mermaid Diagram Code:

graph LR
DC["DeptController"] --> DS["DeptServiceImpl"]
PC["PostController"] --> PS["PostServiceImpl"]
DS --> DM["DeptMapper"]
PS --> PM["PostMapper"]
PS --> UPM["UserPostMapper"]
DM --> DDO["DeptDO"]
PM --> PDO["PostDO"]
UPM --> UPDO["UserPostDO"]

图表来源

章节来源

性能考量

分页查询：PostController.export在导出场景使用无分页常量，建议在大数据量时谨慎使用，优先走分页接口
子部门遍历：DeptServiceImpl.getChildDeptList采用逐层查询，层级过深可能带来多次数据库往返，建议结合缓存或物化路径
唯一性校验：PostServiceImpl.validatePostForCreateOrUpdate在创建/更新时进行名称与编码双重校验，避免重复
数据权限：DeptServiceImpl在计算子部门ID集合时禁用数据权限，避免缓存污染

故障排查指南

常见错误码
- 部门相关：DEPT_NOT_FOUND、DEPT_PARENT_ERROR、DEPT_PARENT_IS_CHILD、DEPT_NAME_DUPLICATE、DEPT_EXITS_CHILDREN
- 岗位相关：POST_NOT_FOUND、POST_NAME_DUPLICATE、POST_CODE_DUPLICATE
排查步骤
- 确认请求参数：父部门ID、名称、编码、状态
- 检查数据库约束：名称/编码唯一性、父子关系合法性
- 核对权限：接口访问权限与数据权限
- 查看服务日志：定位异常抛出位置与上下文

章节来源

结论

本API体系以清晰的分层设计实现了部门与岗位的全生命周期管理，配合完善的校验与导出能力，满足企业组织架构的日常维护需求。建议在生产环境中结合缓存与分页策略优化性能，并严格遵循唯一性与父子关系校验规则，确保组织架构数据的准确性与一致性。

附录

接口权限
- 部门：system:dept:create、system:dept:update、system:dept:delete、system:dept:query
- 岗位：system:post:create、system:post:update、system:post:delete、system:post:query、system:post:export
建议的组织架构维护流程
- 新建岗位：先创建岗位，再进行用户分配
- 调整部门层级：先检查是否存在子部门，再调整父子关系
- 用户岗位变更：批量清理旧关联，再插入新关联，确保原子性

目录​

简介​

项目结构​

核心组件​

架构总览​

详细组件分析​

部门管理API​

岗位管理API​

组织架构数据结构与关系​

部门树构建示例​

岗位权限配置与最佳实践​

依赖关系分析​

性能考量​

故障排查指南​

结论​

附录​

目录

简介

项目结构

核心组件

架构总览

详细组件分析

部门管理API

岗位管理API

组织架构数据结构与关系

部门树构建示例

岗位权限配置与最佳实践

依赖关系分析

性能考量

故障排查指南

结论

附录