Pinxian Li上个月跟一个做HR系统的朋友吃饭，他吐槽了一件事：公司三十多个部门、两千多号人，花名册至今靠Excel在钉钉群里传来传去。离职的员工还在表格里占着一行，新员工的入职时间经常被手滑改错，更别说组织架构调整后部门归属全乱套。我当时就说，这种规模的企业，与其反复去买SaaS账号、跟供应商反复拉锯需求，不如基于Spring Boot从零搭一个内部员工管理系统，顺手还能把权限、导入导出、数据统计都管起来。
这篇内容就把完整的设计和实现过程拆开讲。项目代号里的_8rxd27hj只是平台生成的归档ID，不影响功能。你真正拿到的是一套完整可运行的员工管理后台，核心覆盖了登录鉴权、部门树、员工信息维护、Excel批量导入导出、文件上传、操作日志等模块。适合正在做毕设或课设的学生，也适合刚入职想用Spring Boot练手的中级开发者——整体代码量不大，但链路完整，是理解企业级后台开发套路的一个很好的切入点。
1. 为什么还要自研员工管理系统：Excel、Outlook与现代企业的撕裂
很多人在看到“企业员工管理”这几个字时，第一反应是市面上不是有飞书、钉钉、企业微信吗？为什么还要自己写一套。这个疑问很正常，但实际情况远比想象中复杂。
1.1 一个典型业务场景：HR月底的Excel灾难
我见过一家做连锁零售的企业，员工分布在四十多家门店，总部HR每个月要做三件事：汇总各门店发来的考勤表、核对入职离职名单、给财务提供工资核算底表。三个表格式各不相同，有的门店用Excel 2003的.xls格式，有的用WPS导出的.et，有的直接在邮件正文里贴一段表格。结果是什么？每个月至少有两天，HR部门的两个小姑娘什么正事都不干，就拿着手机在群里一个个核对哪份表是最新版本。
这种痛苦的本质是：员工数据不是一条记录，而是一个持续变化的状态流。入职、转正、调岗、离职、重新入职，每一个动作都会影响数据的准确性。Excel是个好工具，但它没有“主数据”的概念，同一个员工在A表叫“张三”,在B表叫“张 三”，在C表里手机号是隐藏的，系统根本没法自动关联。
1.2 项目边界：哪些功能必须做，哪些可以留到二期
如果你去问业务方，他们会说出二十个功能需求，甚至包括“HR想给员工发生日祝福短信”。但作为设计者，你要做的第一件事是划定MVP边界。基于Spring Boot的这套员工管理系统，我最终圈定的核心功能就五块：
- 组织架构管理：部门的增删改查、层级关系、状态启用停用。
- 员工信息管理：基本资料、联系方式、学历、工作经历、入职离职状态。
- 用户与权限：登录认证、角色区分（管理员、HR、普通员工）、菜单权限控制。
- 批量数据操作：Excel模板下载、批量导入、批量导出，这是HR最刚需的功能。
- 统一检索与操作留痕：按姓名/部门/状态检索，所有增删改操作写入日志。
这五块逻辑上闭环：先有部门，再往部门里塞员工，员工登录系统后再看自己的信息，管理员维护一切。至于考勤打卡、薪资计算、绩效考核这类重型业务，坚决不碰——它们技术上不复杂，但业务规则千差万别，硬塞进来只会拖垮主流程。
1.3 给同类项目的一句话定位
这套系统的定位是“企业内部主数据管理平台”，它的核心不是炫技，而是把一摊散落在各处的员工数据收拢成一份真相。Spring Boot在这里的价值不是魔法，而是一个成熟的、约定优于配置的底座，把Web开发里最繁琐的配置工作替你干掉了大半，让开发者能把精力集中在业务逻辑本身。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 技术选型的底层逻辑：Spring Boot 3.x、MyBatis-Plus与鉴权方案的权衡
技术选型这部分，我最想强调的是：不要为了用新技术而用新技术，每一项选择都应该有明确的理由。下面把这些理由一条条说清楚。
2.1 为什么是Spring Boot而非SSH或SSM
十年前做这种系统，主流方案是Spring MVC + Spring + MyBatis（SSM），再早一点是SSH（Spring + Struts2 + Hibernate）。SSM的问题不在框架本身，而在配置地狱：web.xml、spring-mvc.xml、mybatis-config.xml、数据源配置、事务配置、扫描配置，光配置文件就有七八个，任何一个写错都能消耗半天时间。
Spring Boot把这一切压缩成“一个启动类 + 一个application.yml”。它做的事情本质上是自动配置：你引入了spring-boot-starter-web，它自动帮你装配好DispatcherServlet、内嵌Tomcat、JSON序列化器；你引入了mybatis-plus-boot-starter，它自动帮你扫描Mapper接口。你不需要理解每一个自动配置的细节，但你要知道去哪看：spring-boot-autoconfigure包下的META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports文件里列出了所有自动配置类的清单。
提示：Spring Boot 4.0之后，自动配置的注册方式又有调整，
DataSourceAutoConfiguration等核心类的包路径也发生了变化。如果将来升级版本时发现数据源配置不生效，优先检查这个imports文件里的实际配置类路径，别在application.yml里死磕。
2.2 版本选择的坑：直接用3.x还是继续用2.x
做这个项目时，我面临一个现实选择：是选成熟的Spring Boot 2.7还是直接上3.x。我的结论是：新项目直接上3.x。
原因有三个。第一，Spring Boot 2.x在2023年之后社区维护力度明显下降，很多依赖的版本开始不兼容。第二，3.x基于Jakarta EE 9+规范，包名从javax.*改为jakarta.*，虽然迁移时有点疼，但这已经是Java生态的既定方向。第三，3.x内置的Spring Framework 6.0对AOT编译、虚拟线程等新特性支持更好。
但3.x也有坑，最典型的就是jdk版本要求——必须JDK 17以上。如果你们的开发环境还在用JDK 8，那不用犹豫，老老实实用2.7.x。我见过太多人项目代码写得挺漂亮，结果公司统一打包环境还是JDK 8，部署时直接编译失败。
另外，3.x里如果遇到Jackson的JsonMapper$Builder相关报错，不要慌，这通常是因为Spring Boot 3.x内置的Jackson版本与项目中手动引入的jackson-databind版本冲突。解决办法是统一依赖版本，或者干脆删除手动引入的Jackson依赖，交给Spring Boot的BOM管理。
2.3 ORM选型：MyBatis-Plus还是Spring Data JPA
这是网上争论最多的话题之一。我个人的选择是MyBatis-Plus，理由非常务实：
- 项目里有大量的多表查询、复杂SQL，MyBatis的XML写法让我对最终执行的SQL有完全控制权。
- 单表CRUD由MyBatis-Plus的
BaseMapper和IService直接提供，代码量能减少一半以上。比如分页查询，一个Page对象传进去就完事。 - 团队里如果有人不熟悉Hibernate的缓存机制，用JPA很容易写出性能很差的查询而不自知。
当然，Spring Data JPA也有它的优势：领域驱动设计友好、方法名推导查询非常简洁、实体生命周期管理完善。如果你的项目是全新的、表结构相对简单、团队对JPA有经验，选JPA完全没问题。怕就怕在“一半MyBatis一半JPA”的混搭系统，那才是真正的维护灾难。
2.4 鉴权方案：JWT轻量方案与Sa-Token的取舍
员工管理系统的鉴权需求不算复杂：登录后签发凭证，后续请求带上凭证，后端校验身份和角色。最经典的方案是Spring Security + JWT，但说实话，Spring Security默认自带的那套登录页、Session管理，对前后端分离的系统来说反而多余，配置起来也比较绕。
我最后选了Sa-Token。这不是广告，Sa-Token的学习成本比Spring Security低一个量级，登录就是一行StpUtil.login(userId)，登出就是一行StpUtil.logout()，想要踢人下线、记住我、同端互斥登录，都有现成API。底层用的也是Token机制，可以自定义Token风格，前后端分离场景下非常顺手。
具体链路是这样的：
- 前端登录，后端校验用户名密码（密码用BCrypt加密存储）。
- 校验成功后
StpUtil.login(userId)，框架自动生成Token返回给前端。 - 前端把Token存在请求头（如
satoken）里，每次请求带上。 - 后端配置Sa-Token拦截器，解析Token并填充当前登录用户上下文（用
StpUtil.getLoginId()读取）。 - 角色权限控制用注解
@SaCheckPermission("employee:add")，在Controller方法上加注解即可。
这套方案的优点是完全无状态，不依赖Session，方便未来横向扩展。缺点大家也都知道：Token无法在服务端主动失效（除非引入Redis存黑名单），所以如果对安全性有极苛刻要求，可以考虑Sa-Token的集成Redis方案，把Token状态同步到Redis统一管理。
3. 数据库设计：员工、部门、账号三张核心表如何建模
数据库设计是这类管理系统的地基。很多新手一上来就建一张大宽表，把员工的所有字段都塞进去，结果业务一跑起来就发现问题不断。这里讲讲建模时要考虑的点和最终落地的表结构。
3.1 表结构设计的四个前提
设计之前，想清楚四个问题：
第一，员工和组织架构是什么关系？一个员工只能属于一个部门吗？实际上员工可能兼职多个部门，但MVP阶段可以先做单归属，用“所属部门ID”字段表示，后续要扩展多归属再建关联表。
第二，员工和用户是什么关系？员工是企业内的人，用户是能登录系统的人。理论上每个员工都能登录，但实际可能只有部分人需要登录后台。所以我单独抽了一张用户表，通过employee_id关联，这样员工就算离职，账号可以停用但数据不丢。
第三，部门层级怎么存？经典的方案是“parent_id”邻接表，简单直观，查询子部门时用递归（或者一次性查出全量后在内存中构建树）。如果部门层级深、数据量大，可以考虑“左右值编码”或“路径枚举”，但对员工管理系统来说邻接表完全够用。
第四，状态字段怎么设计？员工状态我定义为：在职、试用期、离职、停薪留职，用一个status字段存储，0/1/2/3分别对应。这样后续做统计报表时，一个GROUP BY status就能出来分布状况。
3.2 核心表DDL：从organizations到employee_info
建表SQL我简化一下，去掉工程里那些字段注释模板，保留核心结构：
sql复制CREATE TABLE sys_dept (
id BIGINT PRIMARY KEY AUTO_INCREMENT COMMENT '部门ID',
parent_id BIGINT DEFAULT 0 COMMENT '上级部门ID，0表示根部门',
dept_name VARCHAR(100) NOT NULL COMMENT '部门名称',
leader VARCHAR(50) DEFAULT NULL COMMENT '负责人',
phone VARCHAR(20) DEFAULT NULL COMMENT '联系电话',
sort_order INT DEFAULT 0 COMMENT '排序号',
status TINYINT DEFAULT 1 COMMENT '状态：1启用 0停用',
create_time DATETIME DEFAULT CURRENT_TIMESTAMP,
update_time DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='部门表';
sql复制CREATE TABLE emp_employee (
id BIGINT PRIMARY KEY AUTO_INCREMENT COMMENT '员工ID',
emp_no VARCHAR(30) NOT NULL UNIQUE COMMENT '工号',
name VARCHAR(50) NOT NULL COMMENT '姓名',
gender TINYINT COMMENT '性别：1男 2女 0保密',
dept_id BIGINT COMMENT '所属部门ID',
position VARCHAR(50) COMMENT '岗位',
phone VARCHAR(20) COMMENT '手机号',
email VARCHAR(100) COMMENT '邮箱',
id_card VARCHAR(18) COMMENT '身份证号',
hire_date DATE COMMENT '入职日期',
leave_date DATE DEFAULT NULL COMMENT '离职日期',
status TINYINT DEFAULT 1 COMMENT '状态：1在职 2试用 3离职 4停薪留职',
education VARCHAR(20) COMMENT '学历',
avatar_url VARCHAR(255) COMMENT '头像URL',
create_time DATETIME DEFAULT CURRENT_TIMESTAMP,
update_time DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
KEY idx_dept (dept_id),
KEY idx_status (status),
KEY idx_emp_no (emp_no)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='员工信息表';
sql复制CREATE TABLE sys_user (
id BIGINT PRIMARY KEY AUTO_INCREMENT COMMENT '用户ID',
employee_id BIGINT COMMENT '关联员工ID',
username VARCHAR(50) NOT NULL UNIQUE COMMENT '登录名',
password VARCHAR(100) NOT NULL COMMENT '密码(BCrypt加密)',
role_code VARCHAR(30) DEFAULT 'employee' COMMENT '角色编码：admin/hr/employee',
status TINYINT DEFAULT 1 COMMENT '账号状态：1启用 0禁用',
last_login_time DATETIME DEFAULT NULL COMMENT '最后登录时间',
create_time DATETIME DEFAULT CURRENT_TIMESTAMP
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='系统用户表';
3.3 关键字段设计背后的考虑
这里有几个不写SQL你注意不到的细节：
emp_no（工号）设置为唯一索引，这是一个业务强约束。工号一旦生成，原则上不允许修改，因为很多下游系统都用工号作为关联键。如果未来要做员工自助查询，这个字段就是天然的业务主键。
hire_date用的是DATE类型而不是DATETIME。入职日期精确到天就够了，用DATETIME反而在时区、格式化上徒增麻烦，Spring Boot里映射成LocalDate也很干净。
所有的表都加了create_time和update_time，并且在数据库层用DEFAULT CURRENT_TIMESTAMP和ON UPDATE CURRENT_TIMESTAMP维护。这样即使应用层代码忘了更新操作时间，数据库也会自动处理。如果你用的是MyBatis-Plus，也可以依赖它的MetaObjectHandler来实现自动填充，但数据库层兜底永远是最稳的。
部门表里的parent_id默认值为0，表示顶层节点。这个设计允许根部门存在多个，比如总公司下按区域划分的华东区、华北区，都可以是顶层节点。树形查询时，从所有parent_id = 0的记录开始递归即可。
注意：身份证号属于敏感个人信息，如果系统后续要上生产环境，请务必对
id_card字段做加密存储或脱敏展示。我在这个项目里是做了AES加密处理的，界面上只显示后四位，避免明文泄露风险。
4. 核心功能拆解：从登录鉴权到Excel批量导入的实现细节
这一节是系统实现的主干部分。我按调用链顺序把每个核心功能的实现细节、关键代码和注意事项逐步展开。
4.1 登录认证与拦截器：别把请求放错了层
先看登录接口。Sa-Token的集成非常清爽，Controller里只需要几行：
java复制@PostMapping("/login")
public Result login(@RequestBody LoginDTO dto) {
// 1. 查询用户
LambdaQueryWrapper<SysUser> wrapper = Wrappers.lambdaQuery();
wrapper.eq(SysUser::getUsername, dto.getUsername());
SysUser user = userMapper.selectOne(wrapper);
if (user == null) {
return Result.error("用户不存在");
}
// 2. 校验密码
if (!BCrypt.checkpw(dto.getPassword(), user.getPassword())) {
return Result.error("密码错误");
}
// 3. 校验账号状态
if (user.getStatus() != 1) {
return Result.error("账号已被禁用");
}
// 4. 登录，签发Token
StpUtil.login(user.getId());
// 5. 记录登录时间（异步）
user.setLastLoginTime(LocalDateTime.now());
userService.updateById(user);
return Result.success(StpUtil.getTokenInfo());
}
这段代码有一个容易被忽视的点：BCrypt.checkpw这一步。密码在数据库里存的是BCrypt哈希，不是明文。BCrypt的最大特点是自动加盐，每次哈希结果都不一样，所以校验时必须用checkpw方法，而不能把数据库里的值拿出来比较。
拦截器配置要特别注意，否则会出现“登录了还是401”或者“未登录也能访问”两个极端。Sa-Token提供一个SaInterceptor：
java复制@Configuration
public class SaTokenConfig implements WebMvcConfigurer {
@Override
public void addInterceptors(InterceptorRegistry registry) {
registry.addInterceptor(new SaInterceptor(handle -> {
StpUtil.checkLogin();
}))
.addPathPatterns("/**")
.excludePathPatterns(
"/api/auth/login",
"/api/auth/captcha",
"/error",
"/doc.html",
"/webjars/**",
"/v3/api-docs/**",
"/favicon.ico"
);
}
}
这一段踩过坑的人不少。我见过有同事把拦截器配成addPathPatterns("/api/**")，但Controller的路径写的是/api/v1/employee/list，恰好匹配没问题；后来有个接口路径没有/api前缀，直接请求不通，排查了半天才发现是拦截器路径不匹配。建议所有业务接口统一带/api前缀，把排除列表想清楚再写。
4.2 员工CRUD与部门树：如何优雅地处理递归
员工管理最核心的页面就是员工列表。列表需要支持按姓名模糊搜索、按部门筛选、按状态筛选，外加分页。用MyBatis-Plus实现：
java复制public PageResult<EmployeeVO> pageQuery(EmployeeQueryDTO dto) {
Page<EmpEmployee> page = new Page<>(dto.getPageNum(), dto.getPageSize());
LambdaQueryWrapper<EmpEmployee> wrapper = Wrappers.lambdaQuery();
wrapper.like(StringUtils.hasText(dto.getName()), EmpEmployee::getName, dto.getName())
.eq(dto.getDeptId() != null, EmpEmployee::getDeptId, dto.getDeptId())
.eq(dto.getStatus() != null, EmpEmployee::getStatus, dto.getStatus())
.orderByDesc(EmpEmployee::getCreateTime);
Page<EmpEmployee> result = employeeMapper.selectPage(page, wrapper);
// 把实体转VO，补充部门名称
List<EmployeeVO> voList = result.getRecords().stream()
.map(emp -> {
EmployeeVO vo = BeanUtil.copyProperties(emp, EmployeeVO.class);
vo.setDeptName(deptService.getDeptNameById(emp.getDeptId()));
return vo;
})
.collect(Collectors.toList());
PageResult<EmployeeVO> pageResult = new PageResult<>();
pageResult.setList(voList);
pageResult.setTotal(result.getTotal());
return pageResult;
}
部门树的构建稍微讲究一点。我常用的一种方案：一次性查出所有部门，然后在内存中用Map构建树。
java复制public List<DeptTreeNode> buildTree() {
List<SysDept> allDepts = deptMapper.selectList(null);
Map<Long, List<SysDept>> groupByParent = allDepts.stream()
.collect(Collectors.groupingBy(SysDept::getParentId));
return buildChildren(0L, groupByParent);
}
private List<DeptTreeNode> buildChildren(Long parentId, Map<Long, List<SysDept>> groupByParent) {
List<DeptTreeNode> treeNodes = new ArrayList<>();
List<SysDept> depts = groupByParent.getOrDefault(parentId, Collections.emptyList());
depts.sort(Comparator.comparingInt(SysDept::getSortOrder));
for (SysDept dept : depts) {
DeptTreeNode node = BeanUtil.copyProperties(dept, DeptTreeNode.class);
node.setChildren(buildChildren(dept.getId(), groupByParent));
treeNodes.add(node);
}
return treeNodes;
}
这个实现有个性能前提：部门数量级在几百个以内，一次全查出来没问题。如果部门上万，就要改成懒加载：点击父节点才查子节点。员工管理系统的部门数量基本是几十到几百，内存构建树是最清晰的方案。
4.3 Excel批量导入导出：HR最离不开的功能
员工信息录入如果靠手敲，一百个人能录一整天。Excel导入导出是刚需。POI直接用很痛苦，内存占用大且API冗长，我换成了阿里开源的EasyExcel。
导入的流程是这样的：
- 前端把Excel文件用
multipart/form-data格式POST到后端，同时带上一个deptId参数——表示这批员工默认归属哪个部门。 - 后端用
EasyExcel.read()读取第一个sheet，逐行转成EmployeeImportDTO。 - 对每一行做校验：姓名不能为空、手机号格式是否正确、工号是否已存在。
- 校验通过后批量插入数据库；校验失败的行记录下来，返回给前端一个“失败原因”。
这里有一个非常实用的细节：EasyExcel的AnalysisEventListener是逐行回调的，如果你在监听器里逐行插入数据库，一万条数据可能要跑几分钟，性能很差。正确做法是在监听器里累加到一个List，每攒够1000条就saveBatch一次，最后清空剩余数据。
java复制public class EmployeeImportListener extends AnalysisEventListener<EmployeeImportDTO> {
private final List<EmployeeImportDTO> cache = new ArrayList<>();
private static final int BATCH_SIZE = 1000;
@Override
public void invoke(EmployeeImportDTO data, AnalysisContext context) {
cache.add(data);
if (cache.size() >= BATCH_SIZE) {
saveToDb(cache);
cache.clear();
}
}
@Override
public void doAfterAllAnalysed(AnalysisContext context) {
if (!cache.isEmpty()) {
saveToDb(cache);
cache.clear();
}
}
}
导出就相对简单，查询出数据后直接用EasyExcel.write().sheet("员工信息").doWrite(list)写到一个临时文件，然后通过ResponseEntity<byte[]>返回给前端，设置好Content-Disposition为附件下载即可。
值得注意的坑：导出大数据量时不要一次性把全量数据加载进内存。哪怕只有几万条，也建议用流式查询或者分批查询。EasyExcel的写操作本身是流式的，但如果你传入的是一个已经加载了全量数据的List，前面做的优化就白费了。
4.4 文件上传与参数混合：Separated的取舍
员工头像上传是另一个高频功能。相关网络搜索里也能看到“spring boot 上传文件并有其他参数”这类问题。其实Spring Boot处理“文件+文本参数”非常直接：
java复制@PostMapping("/upload")
public Result upload(@RequestParam("file") MultipartFile file,
@RequestParam("userId") Long userId,
@RequestParam(value = "remark", required = false) String remark) {
if (file.isEmpty()) {
return Result.error("文件不能为空");
}
String originalFilename = file.getOriginalFilename();
String ext = StringUtils.getFilenameExtension(originalFilename);
// 校验扩展名
if (!Arrays.asList("jpg", "jpeg", "png", "gif", "webp").contains(ext.toLowerCase())) {
return Result.error("不支持的图片格式");
}
// 按日期分目录存储，避免单目录文件过多
String datePath = LocalDate.now().format(DateTimeFormatter.ofPattern("yyyyMMdd"));
String storePath = "/data/uploads/avatar/" + datePath + "/";
File dir = new File(storePath);
if (!dir.exists()) {
dir.mkdirs();
}
String fileName = UUID.randomUUID().toString().replace("-", "") + "." + ext;
file.transferTo(new File(storePath + fileName));
String url = "/api/file/avatar/" + datePath + "/" + fileName;
return Result.success(url);
}
这里有三类问题最容易踩：
第一，MultipartFile.transferTo()在某些情况下会报IllegalStateException，原因是Tomcat对上传文件的临时目录无写权限。建议指定绝对路径存储，别用相对路径。
第二，application.yml里默认上传大小限制只有1MB。如果头像照片稍微大一点就会报MaxUploadSizeExceededException，要调大：
yaml复制spring:
servlet:
multipart:
max-file-size: 10MB
max-request-size: 20MB
第三，如果系统前面挂了Nginx，还得检查Nginx的client_max_body_size配置，否则你在Spring层调大了限制，请求还是在Nginx那一层被拒。
4.5 操作日志：用AOP一件事都不漏
最后一块核心功能是操作日志。我采用Spring AOP + 自定义注解的方式实现，不侵入业务代码。
java复制@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface OpLog {
String module() default "";
String action() default "";
}
在需要记录日志的Controller方法上打上注解，然后写一个切面：
java复制@Aspect
@Component
public class OpLogAspect {
@Around("@annotation(opLog)")
public Object around(ProceedingJoinPoint joinPoint, OpLog opLog) throws Throwable {
long start = System.currentTimeMillis();
try {
Object result = joinPoint.proceed();
saveLog(opLog.module(), opLog.action(), "成功", System.currentTimeMillis() - start);
return result;
} catch (Exception e) {
saveLog(opLog.module(), opLog.action(), "失败：" + e.getMessage(), System.currentTimeMillis() - start);
throw e;
}
}
}
这个方案的优点是业务代码里不需要手动写日志逻辑，以后想扩展记录请求参数、IP地址也很方便。需要注意一点：切面函数里joinPoint.proceed()如果抛出异常，日志记录完成后必须throw e把异常继续抛给上层，否则会导致事务回滚失效——这是AOP切面里特别容易踩的坑。
5. 真实开发中踩过的坑：分页失效、时区错乱与文件上传三大问题的完整排查链路
这一节我把自己在开发过程中真实遇到、并且花了较长时间排查的三个问题写出来。每个问题都按“现象 → 排查思路 → 根因 → 修复”的链路完整还原，而不是直接甩结论。
5.1 MyBatis-Plus分页失效：为什么查出来的数据永远是第一页
现象：前端翻页，pageNum传了2、3，但后端返回的数据始终是第一页的内容，total总数倒是对的。
排查过程：一开始怀疑是前端参数传递错误，看了Network面板，发现请求参数确实带了pageNum=2。然后怀疑Controller参数绑定问题，打印日志发现Page对象接收到的current确实是2。最后才想到MyBatis-Plus的分页插件需要显式配置，否则selectPage不会真正拼接LIMIT语句。
根因：MyBatis-Plus 3.4.0之后移除了内置的分页拦截器，必须手动添加MybatisPlusInterceptor：
java复制@Configuration
public class MybatisPlusConfig {
@Bean
public MybatisPlusInterceptor mybatisPlusInterceptor() {
MybatisPlusInterceptor interceptor = new MybatisPlusInterceptor();
PaginationInnerInterceptor pagination = new PaginationInnerInterceptor(DbType.MYSQL);
pagination.setMaxLimit(500L);
interceptor.addInnerInterceptor(pagination);
return interceptor;
}
}
修复之后分页恢复正常。这个问题的隐蔽点在于：不配置分页插件时，selectPage不会报错，而是默默地返回全量数据，所以很多人根本没意识到自己少了配置。
5.2 数据库时区错乱：为什么时间字段少了8小时
现象：插入一条员工记录，页面显示创建时间是2025-06-01 00:00:00，但数据库里实际存的是2025-05-31 16:00:00，正好少了8小时。反过来，从数据库查询出的时间显示又多了8小时。
排查过程：先检查了JVM时区，TimeZone.getDefault()打印出来是Asia/Shanghai，Java层的时区没问题。然后检查JDBC连接串，发现数据源配置里没有指定serverTimezone。MySQL的DATETIME类型本身不存储时区信息，但JDBC驱动在读取和写入时会使用JVM默认时区与数据库会话时区进行转换，两边不一致就会出偏差。
根因：连接串里的serverTimezone没有显式指定，或者指定成了UTC。
yaml复制spring:
datasource:
url: jdbc:mysql://localhost:3306/employee_db?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai&useSSL=false&allowPublicKeyRetrieval=true
修复后问题解决。这个问题的教训是：凡是涉及时间字段，一定要在数据源连接串里显式指定时区，不要依赖默认值。同时推荐所有时间字段在应用层统一用LocalDateTime，避免使用java.util.Date在不同时区下的隐式转换。
5.3 文件上传偶发报错：transferTo目标目录不存在是表象，权限才是痛点
现象：上传头像时，偶尔报java.io.IOException: No such file or directory，但有时候又能成功。
排查过程：首先怀疑目录不存在，于是在File dir = new File(storePath)之后添加了dir.mkdirs()，发现还是间歇性报错。后来仔细看异常栈，发现报错发生在transferTo内部，它先把临时文件用Files.move()移动到目标位置。mkdirs()只是创建了目录，但是应用运行用户对目标目录没有写权限时，mkdirs()不会报错（因为目录可能已被创建，或者exists()校验没做），真正的写入动作却失败了。
根因：服务器上应用以普通用户运行，目标目录/data/uploads/avatar/的属主是root，并且权限是755，普通用户没有写权限。
修复办法是先把权限调对：
bash复制sudo mkdir -p /data/uploads/avatar
sudo chown -R appuser:appuser /data/uploads
sudo chmod -R 755 /data/uploads
5.4 三层防护排查法：从表象到根因的通用套路
以上三个问题虽然不是同一类，但排查方法论是通用的，总结成三步：
第一步，分层定位：先判断是前端问题（网络面板看请求参数）、网关问题（Nginx日志）、控制器问题（打印入参）、还是数据层问题（打印SQL）。
第二步，复现与消除变量：把问题缩小到最小复现集。比如分页问题，用Postman直接调接口，排除前端变量，再逐步缩小到配置缺失。
第三步，查看官方文档或源码：很多框架问题是配置缺失导致的，App不至于报错，但表现很隐蔽。遇到这类问题，优先翻官方文档里“快速开始”一节，比对配置差异，往往比在搜索引擎大海捞针高效得多。
6. 打包部署与后续扩展：Docker镜像、配置外置与多环境适配
开发完只是第一步，真正能交到对方手里、能在服务器上跑起来、能长期维护，才算完整。
6.1 用一个基础Dockerfile跑通后端
Spring Boot应用的部署最省心的是打一个可执行jar包，配合Docker。
dockerfile复制# 构建阶段
FROM maven:3.9-eclipse-temurin-17 AS build
WORKDIR /app
COPY pom.xml .
RUN mvn dependency:go-offline
COPY src ./src
RUN mvn package -DskipTests
# 运行阶段
FROM eclipse-temurin:17-jre
WORKDIR /app
COPY --from=build /app/target/employee-server.jar app.jar
EXPOSE 8080
ENV TZ=Asia/Shanghai
ENTRYPOINT ["java", "-jar", "app.jar"]
这里有两个细节值得注意。
第一，分阶段构建的好处是最终镜像只包含JRE和jar包，不含Maven和源码，镜像体积能小三分之一以上。第二，ENV TZ=Asia/Shanghai必须设置，否则容器默认时区是UTC，你在代码里再怎么指定serverTimezone都白搭，时间显示会全部错乱。
启动命令简单直接：
bash复制docker build -t employee-server:1.0 .
docker run -d --name employee-server -p 8080:8080 \
-e SPRING_PROFILES_ACTIVE=prod \
-v /data/config:/app/config \
-v /data/uploads:/data/uploads \
employee-server:1.0
6.2 配置文件外置：换环境不用重新打镜像
一个常见需求是：同一份代码部署到开发、测试、生产三个环境。如果配置写死在jar包里，每次部署都要重新构建镜像，太痛苦了。
我的做法是：application.yml里只保留通用的配置，环境相关配置用application-{profile}.yml分离，启动时用SPRING_PROFILES_ACTIVE指定。
yaml复制# application.yml
spring:
profiles:
active: dev
# application-prod.yml
spring:
datasource:
url: jdbc:mysql://10.0.0.8:3306/employee_db?serverTimezone=Asia/Shanghai
username: prod_user
password: xxxxxx
files:
upload-path: /data/uploads
更进一步，可以把配置文件挂载到容器外，用--spring.config.additional-location=/app/config/加载外部配置，这样改配置甚至不用重新部署，重启容器即可。
提示：数据库密码这类敏感信息别直接写在
application-prod.yml里。生产环境建议用环境变量注入，比如password: ${DB_PASSWORD}，在Docker启动时通过-e DB_PASSWORD=xxx传入。这样配置仓库里不会出现明文密码。
6.3 数据初始化：让系统拿到就能跑
一个完整的项目交付，数据初始化不能省。我在src/main/resources下放了db/init.sql，里面包含建库建表和初始数据：
sql复制INSERT INTO sys_dept (id, parent_id, dept_name, sort_order, status) VALUES
(1, 0, '总公司', 1, 1),
(2, 1, '技术部', 1, 1),
(3, 1, '人事部', 2, 1);
-- 初始管理员账号，密码统一为 admin123
INSERT INTO sys_user (employee_id, username, password, role_code, status) VALUES
(NULL, 'admin', '$2a$10$xxxxxxxxxxxxxxxxxxxxxxxxxx', 'admin', 1);
然后用Spring Boot的spring.sql.init机制在启动时自动执行，或者手动通过Navicat/命令行执行。这样拿到项目的人不需要去问你要账号密码，直接按README里的说明初始化数据库，启动项目，用admin/admin123就能登录。
6.4 后续扩展方向：从能用走向好用
这套系统跑通后，距离真正的生产级还有一段距离。几条可落地的扩展方向供参考：
数据权限控制：当前的权限是角色级别的，所有HR都能查所有员工数据。更细的需求是部门数据隔离——HR只能看自己负责部门的员工。实现方案是在查询条件里追加dept_id IN (自己有权限的部门ID列表)。
报表统计：按部门统计在职人数、按学历分布统计、按入职月份统计流失率。这些在现有表结构下用几个GROUP BY就能实现，页面端引入一个ECharts就能出图，投入产出比非常高。
登录审计与风控：记录登录IP、登录时间、登录失败次数，连续失败5次锁定账号15分钟。这块逻辑不复杂，但对系统安全性的提升很明显。
WebSocket消息通知：如果要做员工生日提醒、入职周年提醒，可以利用Spring Boot内置的WebSocket做推送。相关搜索词里提到“spring boot好用的websocket后端框架，可以广播、群组、设置属性等”，这是真实存在的高频需求，Netty或Spring自带WebSocket都能做，关键是设计好消息类型和频道模型。
全文检索：当员工数据量过万后，模糊查询性能会明显下降，尤其LIKE '%关键字%'这种查询用不上索引。可以引入Lucene或Elasticsearch，在员工姓名、岗位、技能标签上建立全文索引，搜索体验会快一个数量级。
日志采集方面，如果部署在Kubernetes环境，可以考虑用Filebeat把Spring Boot日志统一收集到Elasticsearch再展示到Kibana，排查线上问题会方便得多。
7. 写在最后：这套系统的几个使用心得
项目交付后，我把自己放在“使用这套系统的人”的位置上重新审视了一遍，有几个感受记录下来，也算是一些实践经验。
第一个体会是，前端表单校验不能省。员工管理后端接口是面向HR系统的，但前端页面上该做的前端校验还是必须做。手机号格式、身份证格式、入职日期不能大于当前日期，这些校验如果只靠后端拦截，HR录入时体验会很差，一个错误弹窗就要重新填整张表单。前中后端各做一遍校验，看起来有重复劳动，实际是各司其职。
第二个体会是，工号这个字段要设计好生成规则。最省事的方式是数据库自增ID，但自增ID会被猜出员工总数，而且换数据库迁移时容易出问题。我的建议是用时间戳加随机数生成业务工号，比如EMP20250601001，既体现入职时间，又不暴露总人数。
第三个体会是，不要在业务代码里写死上传文件路径和数据库连接。把这些全部外置到配置文件中，将来即便不是你自己部署，接手的人也能快速上手。配置外置的成本极低，但收益是长期持续的。
第四个体会是，保持模块划分清晰。Controller只做参数接收和响应封装，Service层处理业务逻辑，Mapper只做数据访问，Entity和VO分开。这套分层方式虽然老生常谈，但在员工管理系统这种业务密集、字段繁多的场景下，是防止代码腐烂最有效的手段。
如果你正打算做类似的Spring Boot项目，或者接手了一个员工管理系统的毕设/课设，希望这篇内容能帮你省掉一部分填坑时间。从数据库设计到核心模块实现，再到部署交付，整套链路已经跑通，你可以站在这个基础上继续打磨出更完整的版本。