Spring Boot宠物领养管理系统实战：从需求拆解到Docker部署全记录-代码聚汇网

1. 为什么折腾这个项目：流浪动物管理的真实痛点

做宠物领养管理系统之前，我在本地动物救助站蹲过两周。那儿的日常是这样的：志愿者用Excel登记宠物信息，领养人填纸质申请表，审核靠微信群来回问，回访记录散落在个人手机里。一只猫从救助到被领养，中间经手四五个人，信息断档是常态。最要命的是，有些宠物被领养后失联，救助站根本没法追溯。

这个系统的核心价值不是做个CRUD交差，而是把“救助-领养-回访”的全生命周期串起来。对于正在做Java后端学习、或者准备用Spring Boot搞毕业设计的同学来说，它覆盖了权限管理、文件上传、流程审核、消息通知、数据统计这些后端开发的常见场景，比单纯做个图书管理系统有挑战得多，因为业务状态多、角色多、流转复杂。

这个项目我采用的是Spring Boot 2.7 + Vue 3 + MySQL 8 + Redis的组合，前后端完全分离。后端负责提供RESTful API，前端用Vue管理界面。为什么选Spring Boot而不是Spring Cloud？原因很简单——单体架构在这样一个规模的项目里足够用，微服务拆分带来的分布式事务、服务注册发现等问题，对这个场景来说是纯负担。等将来访客量真的大到需要拆了，再按业务边界拆也不迟。

我见过太多人一上来就堆技术栈：Spring Cloud Alibaba全家桶、RabbitMQ、Elasticsearch，最后项目跑起来都费劲。技术选型的逻辑应该是“先想清楚业务规模，再定架构”，而不是反着来。关于这一点，后面选型部分会细说。

需要模型API调用？免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。

2. 业务需求拆解：从现场流程整理出系统边界

在写第一行代码之前，我把救助站的流程画成了流程图，这个过程是整个项目里收获最大的一步。

2.1 角色定义与权限边界

系统里有四类角色：普通访客、领养申请人、救助站管理员、系统超级管理员。每类角色的权限边界一开始就要划清楚。

救助站管理员是日常使用频率最高的角色，他们负责宠物信息录入、领养申请初审、安排线下见面、决定是否通过。超级管理员则管管理员账号分配、基础数据字典、系统公告这类运维向的事情。普通访客只需要浏览宠物信息、收藏、提交领养意向，不需要登录也能看宠物列表——这是为了让更多人方便地浏览，而不是一上来就被登录墙挡住。

权限这块我用的是Spring Security + JWT的方案。JWT无状态，适合前后端分离的部署方式。但这里有个坑：宠物图片这种静态资源如果也走JWT鉴权，前端<img>标签没法在header里带token，会很麻烦。后面专门有一节讲我怎么处理的。

2.2 核心业务状态：宠物和申请的变化过程

宠物状态是整个系统里最容易设计错的点。救助站的真实流程是这样的：流浪动物进入救助站，做完体检驱虫疫苗，状态才算“可领养”；有人提交申请并通过初审后，宠物要标记为“待见面”；见面成功，进入“待领养”阶段（交押金、办手续）；办完手续才是“已领养”。如果退回或者领养人放弃，又重新回到“可领养”。

领养申请的状态更复杂：待初审、初审通过(待见面)、见面完成、待终审、已通过、已拒绝、已取消、已过期。不同状态的申请对宠物状态有不同的联动关系。比如申请进入“待见面”，宠物状态就必须是“待见面”，防止同一只宠物被多个人同时申请见面——这种并发场景在宠物热门的时候真实会发生，领养人可能同时看上同一只猫。

2.3 为什么字段冗余在这里是合理的

宠物表里除了基本信息（品种、年龄、性别、毛色、健康状态），我还存了救助时间、救助地点、疫苗记录、绝育状态这些救助站每天都在记录的字段。有些信息（比如救助地点经纬度）本来可以单独建表，但考虑救助站实际录入习惯，救助地点直接存文本更顺手，管理员不需要每次去地图上选坐标。

从“三范式”的角度看这不符合规范，但实际业务里，字段冗余换来的往往是录入效率和查询性能。只要冗余字段的更新时机可控、没有一致性风险，就可以接受。我在自己工位上贴了一句话：数据表是为业务流转设计的，不是为了让ER图好看的。

3. 数据库设计：从领养流程反推表结构

数据库是这类管理系统最见功夫的部分。我前后改了四版，第一版只有六张表，越设计越多，最后稳定在十几张表。

3.1 基础表设计：用户、角色、权限

用户表存的是username、password（BCrypt加密后的）、phone、email、avatar、status。注意这里不要只设计一张user表完事——虽然可以硬编码角色字段，但后续扩展（比如志愿者也算一种特殊用户）会异常痛苦。我用了标准的五张表方案：sys_user、sys_role、sys_menu、sys_user_role、sys_role_menu。

角色和菜单的关联，让“救助站管理员”能看审核菜单但看不到系统管理菜单这种需求，一个配置就能搞定。Spring Security里我用@PreAuthorize注解在Controller层做细粒度控制。

3.2 宠物信息表：单表还是分表

宠物信息字段多但不算复杂，核心字段有：

sql复制CREATE TABLE `pet_info` (
  `id` bigint NOT NULL AUTO_INCREMENT,
  `name` varchar(50) DEFAULT NULL COMMENT '宠物名字',
  `category` varchar(20) DEFAULT NULL COMMENT '猫/狗',
  `breed` varchar(50) DEFAULT NULL COMMENT '品种',
  `sex` tinyint DEFAULT NULL COMMENT '公母',
  `age_months` int DEFAULT NULL COMMENT '月龄',
  `sterilized` tinyint DEFAULT '0' COMMENT '是否绝育',
  `vaccinated` tinyint DEFAULT '0' COMMENT '是否完成疫苗',
  `health_status` varchar(200) DEFAULT NULL COMMENT '健康状况描述',
  `rescue_address` varchar(200) DEFAULT NULL COMMENT '救助地点',
  `rescue_time` datetime DEFAULT NULL COMMENT '救助时间',
  `status` tinyint DEFAULT '0' COMMENT '0-待审核 1-可领养 2-待见面 3-已领养 4-下架',
  `cover_image` varchar(255) DEFAULT NULL COMMENT '封面图',
  `description` text COMMENT '详细描述',
  `create_time` datetime DEFAULT NULL,
  `update_time` datetime DEFAULT NULL,
  PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

这里我没有用age字段而是用age_months，因为救助站记录的很多是估计月龄，不是准确生日。而且以后做筛选——“三个月以下的小猫”这种查询，用整数比用日期好处理得多。

多张宠物图片我单独建了pet_image表，一张宠物对应多张图。为什么不直接把图片URL拼接成字符串存在一个字段里？因为将来要做图片轮播、主图切换、缩略图裁剪，拆分出来操作更灵活。

3.3 申请审核表与状态流转记录

申请主表记录的是：哪个用户、哪只宠物、申请类型、申请内容（自我介绍、养宠经验、居住情况）、当前状态、各级审核意见、审核人、审核时间。这个表保存的是“当前最新状态”。但有个很关键的问题：状态流转的历史怎么办？

我在第二版设计里忽视了这个问题，测试的时候发现管理员想查看“这个申请为什么被拒绝过”，数据根本找不回来。后来加了adoption_apply_log表，每次状态变更都插入一条日志，记录操作人、操作时间、原状态、新状态、备注。

这种“主表+流水表”的模式在很多业务系统里都很常见，比如订单表和订单状态变更表。看起来冗余，实际上是为了满足追溯审计的需求，做管理系统的都知道，能追溯操作记录太重要了。

4. 后端代码结构：为什么我坚持按业务模块分包

Spring Boot项目结构这件事，网上的争论能吵几百楼。我个人的习惯是：不按controller、service、mapper这样按技术层分包，而是按业务模块分包，在每个模块内部再分层。

4.1 模块划分的具体做法

项目里的包结构大致是：

code复制com.pet.adoption
├── common          // 通用类：统一返回结果、异常处理、工具类
├── config          // 配置类：Security、Redis、MyBatisPlus、Swagger
├── security        // Spring Security核心配置和JWT过滤器
├── module
│   ├── auth        // 登录认证
│   ├── user        // 用户管理
│   ├── pet         // 宠物信息管理
│   ├── apply       // 领养申请
│   ├── audit       // 审核流程
│   ├── followup    // 回访管理
│   ├── favorite    // 收藏
│   ├── file        // 文件上传
│   └── dashboard   // 首页数据统计
└── PetAdoptionApplication.java

这种分包方式的好处是：拿到一个需求时能快速定位到对应模块。比如“领养申请被拒了”这个问题，去apply包里找肯定没错。如果你按技术层分包，改一个领养申请的功能可能要同时动五六个不同层级的目录，协作效率很低。

4.2 几个核心注解的用法和误区

热搜词里有“springboot常用注解”，正好这里说一下我的用法：

@RestController：返回JSON数据，替代了@Controller加@ResponseBody的组合。
@Service：业务逻辑层，事务注解@Transactional一般加在Service层的方法上。
@Mapper：MyBatis的Mapper接口标记，也可以在启动类上加@MapperScan批量扫描。
@ConfigurationProperties：把application.yml里的配置项绑定到Java类。比如文件上传路径、JWT过期时间这类配置，我会单独建配置类接收。
@Validated + @NotNull：参数校验，避免在Controller里写一堆if判断。

有个容易踩坑的地方：@Transactional加在Controller上是无效的，因为Spring AOP是通过代理对象调用来拦截事务的，Controller的调用链经过的代理对象跟Service的代理对象不是同一个。

4.3 统一返回结果与全局异常处理

前后端联调时最怕各写各的返回格式。我定义了一个统一的Result<T>类：

java复制@Data
public class Result<T> {
    private Integer code;    // 200成功，500失败，401未登录
    private String message;  // 提示信息
    private T data;          // 数据
}

配合@RestControllerAdvice做全局异常处理。业务异常比如“该宠物已被领养”，抛一个自定义的BusinessException，全局异常处理器会捕获并转成统一的返回格式，前端拿到code != 200就提示message。这样Controller里的逻辑就干净很多，不用每个方法都包try-catch。

5. 宠物档案与文件上传：静态资源映射的坑

救助站的宠物照片通常是用手机拍的，每一张都好几MB。如果直接存数据库或者不做任何处理，前端页面加载会卡成幻灯片。这个模块踩了不少坑，值得单独写一节。

5.1 图片上传与压缩处理

我使用的方案是：上传原图 -> 生成缩略图 -> 原图存到磁盘，缩略图用于列表展示，原图用于详情页。压缩用的是Java自带的ImageIO，没有引入额外的图片处理库。

java复制public String compressImage(MultipartFile file, String targetPath) throws IOException {
    BufferedImage image = ImageIO.read(file.getInputStream());
    int width = image.getWidth();
    // 限制最长边为800px
    if (width > 800) {
        int height = image.getHeight();
        int newHeight = height * 800 / width;
        BufferedImage newImage = new BufferedImage(800, newHeight, image.getType());
        Graphics2D g = newImage.createGraphics();
        g.drawImage(image, 0, 0, 800, newHeight, null);
        g.dispose();
        // 按JPEG格式输出
        File target = new File(targetPath);
        ImageIO.write(newImage, "jpg", target);
        return targetPath;
    }
    // 原图已经很小的情况直接转存
    file.transferTo(new File(targetPath));
    return targetPath;
}

压缩完能控制到200KB左右，对Web展示完全够用。如果你需要更好的压缩效果，可以考虑引入Thumbnailator这个库，代码更简洁，压缩质量也更好。

5.2 Spring Boot资源映射：upload目录怎么访问

后端把文件存到了服务器磁盘的/data/pet-upload/目录（Windows就是D:/pet-upload/），前端的img标签怎么访问到这些文件呢？默认Spring Boot只映射classpath:/static/下的资源，磁盘上的路径它不管。

解决办法是配置WebMvcConfigurer，把URL和磁盘路径映射起来：

java复制@Configuration
public class WebMvcConfig implements WebMvcConfigurer {
    @Value("${file.upload-dir}")
    private String uploadDir;

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/upload/**")
                .addResourceLocations("file:" + uploadDir + "/");
    }
}

配置完之后，文件上传到/data/pet-upload/abc.jpg，浏览器访问http://localhost:8080/upload/abc.jpg就能直接打开。

这里有个容易踩的坑：addResourceHandler的映射路径/upload/**，末尾的两个星号不能省，它表示匹配任意层级的子路径。而addResourceLocations里的file:前缀不能丢，不然会被当成classpath路径去解析。我用Spring Boot 2.7实测这个配置是稳定的。

5.3 JWT拦截器要放行静态资源

这是我在联调阶段被卡了最久的一个问题。Spring Security配置里，我一直以为登录后所有请求都必须带token，结果前端页面上的宠物图片全部加载不出来。

排查后发现，<img src="/upload/xxx.jpg">这种浏览器发起的请求不会带Authorization头，所以被JWT过滤器拦截了。解决方案是在Security配置里放行/upload/**这个路径：

java复制@Override
protected void configure(HttpSecurity http) throws Exception {
    http.authorizeRequests()
        .antMatchers("/upload/**").permitAll()   // 静态资源放行
        .antMatchers("/api/auth/**").permitAll() // 登录注册接口
        .anyRequest().authenticated();
}

不只是图片路径，Swagger的接口文档路径也需要放行。如果你不想在线上环境暴露接口文档，可以只在开发环境开启Swagger。关于“springboot jwt 放开swagger”，这个热词搜得很多，很多人都是上线时才发现文档打不开。

6. 权限设计在代码里的落地：Spring Security与JWT

登录认证和权限这块，直接关系到系统是否安全，也关系到能不能放心把系统给救助站用。我推荐使用Spring Security而不是自己写拦截器——虽然Security学习曲线偏陡，但它的框架设计比较完善，密码加密、Session管理、CSRF防护都考虑到了。

6.1 认证流程：登录成功后返回什么

用户提交用户名密码，后端校验通过后，用JWT工具类生成token返回给前端：

java复制public String generateToken(Long userId, String username) {
    Map<String, Object> claims = new HashMap<>();
    claims.put("userId", userId);
    claims.put("username", username);
    // 用HS256签名，有效期设为7天
    return Jwts.builder()
            .setClaims(claims)
            .setSubject(username)
            .setIssuedAt(new Date())
            .setExpiration(new Date(System.currentTimeMillis() + 7 * 24 * 3600 * 1000L))
            .signWith(SignatureAlgorithm.HS256, secretKey)
            .compact();
}

密钥存在application.yml里。这里有一个安全细节：生产环境的JWT密钥绝对不能是明文写在代码里的简单字符串，应该用环境变量注入。比如jwt.secret=${JWT_SECRET}，部署时在服务器上配置环境变量，这样就算代码仓库泄露，密钥也不会泄露。

6.2 不用Redis存token行不行

很多系统把JWT存Redis的目的，是为了实现“退出登录立即失效”和“强制下线”功能。JWT本身是无状态的，签发之后在过期之前一直有效，除非后端存一份黑名单。

我这个项目里做了双重处理：Redis里存一份“有效token”的key，key是token本身，value是用户信息，并设置过期时间跟token有效期一致。用户退出时删除这个key；JWT过滤器里先查Redis，查不到就认为是无效token。

这样做的好处是管理员封禁用户时，直接删掉Redis里的key，就能让这个用户的token立刻失效。这是纯无状态JWT做不到的。

6.3 前端Vue怎么配合

Vue这边我用的是Axios请求拦截器，每次请求带上token：

javascript复制axios.interceptors.request.use(config => {
    const token = localStorage.getItem('token');
    if (token) {
        config.headers.Authorization = 'Bearer ' + token;
    }
    return config;
}, error => {
    return Promise.reject(error);
});

响应拦截器里，如果遇到401状态码，就跳转到登录页，并提示“登录已过期”。这里不要用alert弹窗，太丑了，用Element Plus的Message组件更统一。

6.4 异步请求的权限注解

管理员接口我在Controller方法上加了@PreAuthorize("hasRole('ADMIN')"),这样即使普通用户知道接口URL，也没法调用——因为他没有ADMIN角色，Spring Security会在调用前拦截。需要在启动类或配置类上加@EnableGlobalMethodSecurity(prePostEnabled = true)，这个注解很多人会漏掉，漏掉之后@PreAuthorize完全不生效，排查起来很浪费时间。

7. 领养申请里的状态机：Flowable有没有必要引入

领养申请的审核流程有多个节点：初审、见面、终审、通过。不少人在热词里搜“springboot使用flowable”，应该是想把工作流引擎引入项目。我的建议是：先想清楚你的流程复杂度，再决定要不要用工作流引擎。

7.1 这个项目到底要不要上Flowable

Flowable是一个成熟的工作流引擎，支持BPMN 2.0标准，能可视化设计审批流程。但对宠物领养这种固定四步审批的场景，用Flowable属于杀鸡用牛刀。它引入的复杂度是实实在在的：需要维护专门的流程表、流程部署、流程实例，排错时还要理解BPMN规范。我更倾向于手写一个状态机来管理审批流转，这样代码里就能看明白整个流程，出了问题也容易排查。

不过，如果你想学习Flowable的真正用法，可以把“领养审核”模拟成一个带条件的审批流来做练习：初审通过后如果宠物是猫走一个分支，是狗走另一个分支。这样能学到Flowable的条件表达式和网关用法。但生产项目里，我更推荐状态机方案。

7.2 状态机实现的核心思路

我的实现方式很简单：建一张audit_flow_config表，配置每个状态可以流转到哪些新状态，以及触发动作。然后在Service里做一个统一的transition方法：

java复制public void auditApply(Long applyId, Long auditorId, Integer targetStatus, String comment) {
    // 1. 查出当前申请
    AdoptionApply apply = applyMapper.selectById(applyId);
    // 2. 校验当前状态能否流转到目标状态
    List<Integer> allowedTargets = flowConfigMapper
            .selectTargetsBySource(apply.getStatus(), apply.getPetCategory());
    if (!allowedTargets.contains(targetStatus)) {
        throw new BusinessException("非法的状态流转: " + apply.getStatus() + " -> " + targetStatus);
    }
    // 3. 更新申请状态
    apply.setStatus(targetStatus);
    applyMapper.updateById(apply);
    // 4. 插入流转日志
    ApplyLog log = new ApplyLog();
    log.setApplyId(applyId);
    log.setOperatorId(auditorId);
    log.setFromStatus(apply.getStatus());
    log.setToStatus(targetStatus);
    log.setComment(comment);
    applyLogMapper.insert(log);
}

这个写法有几个好处：一是状态流转规则集中在一处，不会出现Service里到处都是一堆状态判断的逻辑；二是非法流转（比如从“待初审”直接跳到“已通过”）会被挡在入口处；三是每一步都有日志，审计友好。

7.3 并发场景：同一只宠物被重复申请

宠物热门时，可能同一天有好几个人申请领养同一只猫。如果不做控制，可能出现两个申请都进入“待见面”，然后宠物被领走了另一边还在流程中。

我在apply表上做了一个唯一索引约束，部分唯一索引使用的是生成列技巧：

sql复制ALTER TABLE adoption_apply 
ADD COLUMN active_flag tinyint DEFAULT 1 COMMENT '1-进行中 0-结束',
ADD UNIQUE KEY uk_pet_active (pet_id, active_flag);

如果申请结束（被拒绝或已领养），把active_flag置为0，然后重新插入新记录时active_flag仍是1。因为(pet_id, active_flag)联合唯一，同一只宠物只能有一条进行中的申请。MySQL的部分索引只适用于索引条件下过滤失效的场景，这个用生成列的办法虽然绕，但实测有效并且稳定。

7.4 申请过期未处理怎么办

救助站管理员不可能天天登录系统，有些申请两三天没审核。我加了一个定时任务，每分钟扫描一次，把超过三天没处理的“待初审”申请自动标记为“已过期”。用的是Spring Boot自带的@Scheduled注解，没有额外引入Quartz。配置如下：

java复制@Component
public class ApplyTimeoutTask {
    @Scheduled(cron = "0 0/30 * * * ?")  // 每半小时执行一次
    public void handleTimeout() {
        Date deadline = DateUtils.addDays(new Date(), -3);
        applyMapper.updateStatusByTimeout(deadline, "待初审", "已过期");
    }
}

如果你后续需要更灵活的定时任务管理（比如页面上直接修改执行时间），再考虑引入Quartz或XXL-Job。

8. 数据统计与可视化：首页看板让救助站一眼看全

管理员登录系统后，第一个看到的不应该是单调的菜单列表，而是Dashboard——今天救助站收了多少宠物，多少在等待领养，本月成功领养几只，哪些品种最受欢迎。这些数据看起来简单，但图表和指标的背后，是几个还比较讲究的统计思路。

8.1 首页指标卡片

看板顶部是四个大数字卡片：宠物总数、可领养数、待审核申请、本月领养成功。每个数字背后对应一个SQL，我直接写出几个常见统计的写法：

xml复制<!-- 本月领养成功数 -->
<select id="countAdoptedThisMonth" resultType="java.lang.Long">
    SELECT COUNT(*) FROM pet_info
    WHERE status = 3
    AND update_time >= DATE_FORMAT(CURDATE(), '%Y-%m-01')
</select>

这里有个小技巧：领养时间是pet_info.update_time，因为宠物状态变成“已领养”的时机就是更新这个时间。不需要额外加一个adopt_time字段，除非之后需要追溯历史——但状态流转日志表里已经有记录了，需要精确时间去日志里查就行。

8.2 领养趋势折线图

展示过去6个月每月领养成功数量，我用了ECharts前端渲染，后端提供近6个月的统计数据。关键的SQL是按月分组的写法：

sql复制SELECT DATE_FORMAT(update_time, '%Y-%m') as month, COUNT(*) as count
FROM pet_info
WHERE status = 3 AND update_time >= DATE_SUB(CURDATE(), INTERVAL 6 MONTH)
GROUP BY DATE_FORMAT(update_time, '%Y-%m')
ORDER BY month;

后端返回后，中间有月份的空档需要前端补零处理。比如某个月一只宠物都没领养出去，后端不会返回这个月的数据，前端如果直接把数据映射到坐标轴就会少一根柱子。处理方式是前端构建一个完整的近6个月月份数组，然后逐个从后端数据里查找，查不到就补0。

8.3 宠物分类占比

这个页面展示当前救助站里猫和狗的数量占比，以及品种Top10。品种Top10的统计有个细节：很多宠物是串串，品种填的“中华田园猫”“串串”，这类条目数量巨大但展示价值有限。我的处理是配置一个category_blacklist，把“串串”“混血”这些词排除出品种统计，只统计有明确品种的。

9. 前后端联调中的典型问题与排查记录

这个章节是我最想分享的，因为踩过的坑几乎都是文档里查不到的。写几个典型的排错过程，给大家一点参考。

9.1 前端请求跨域，浏览器弹出CORS错误

前后端分离开发时最常遇到。后端接口跑在http://localhost:8080，前端Vue跑在http://localhost:5173，端口不一样，跨域。浏览器会先发一个OPTIONS预检请求，如果后端没有正确响应CORS头，实际请求就发不出去。

解决方案有几种：

后端配置@CrossOrigin注解，写在Controller类上。
统一在WebMvcConfig里加CorsRegistry。

我用的后者，因为不用每个Controller都加注解：

java复制@Override
public void addCorsMappings(CorsRegistry registry) {
    registry.addMapping("/**")
            .allowedOriginPatterns("*")
            .allowedMethods("GET", "POST", "PUT", "DELETE", "OPTIONS")
            .allowedHeaders("*")
            .allowCredentials(true)
            .maxAge(3600);
}

更建议的方式是生产环境用Nginx反向代理，让前后端同源，这样CORS配置都不需要了。开发环境的CORS配置在生产环境同源的场景下不影响功能，唯一需要留意的是allowCredentials(true)和allowedOriginPatterns("*")必须同时使用，从Spring Boot 2.4开始allowedOrigins("*")与allowCredentials(true)不能共存，会启动报错。

9.2 LocalDateTime序列化出一串数字

后端返回LocalDateTime字段，前端收到的是一串数字，不是“2025-11-20 14:30:00”。原因是默认的Jackson序列化把LocalDateTime转成了时间戳。

解决方式，在application.yml里配置：

yaml复制spring:
  jackson:
    date-format: yyyy-MM-dd HH:mm:ss
    time-zone: GMT+8

但date-format只对java.util.Date生效，对Java 8的LocalDateTime不生效。需要单独加一个Jackson的自定义序列化器，或者直接在每个字段上加@JsonFormat注解：

java复制@JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss", timezone = "GMT+8")
private LocalDateTime createTime;

项目中我用了全局配置的方式，在配置类里注册JavaTimeModule并自定义LocalDateTime的序列化和反序列化格式。一次性搞定所有字段，省事。

9.3 MyBatis Plus分页查询不生效

这个坑几乎每个用MyBatis Plus的人都会踩一次。分页查询写好了，但返回的结果还是全量数据。原因是MyBatis Plus的分页插件必须手动添加到MyBatis的拦截器链中：

java复制@Configuration
public class MybatisPlusConfig {
    @Bean
    public MybatisPlusInterceptor mybatisPlusInterceptor() {
        MybatisPlusInterceptor interceptor = new MybatisPlusInterceptor();
        interceptor.addInnerInterceptor(new PaginationInnerInterceptor(DbType.MYSQL));
        return interceptor;
    }
}

少了这段配置，Page参数传进去会被当成普通参数，SQL不会被拼上LIMIT，查询自然返回全部数据。这种配置漏写的情况很常见，排查思路就是看SQL日志里有没有LIMIT语句。

9.4 文件上传大小超出限制

默认Spring Boot的文件上传大小限制是1MB。救助站志愿者用手机拍的图动辄2-3MB，一传就报错。需要在application.yml里调大：

yaml复制spring:
  servlet:
    multipart:
      max-file-size: 10MB
      max-request-size: 20MB

调整之后，上传5MB的原图配合后端压缩就没有问题了。

10. 部署实践：用Docker把项目打包上线

项目开发完，最终要给救助站用，不能在本地跑一个开发环境就交货。我用Docker部署了MySQL、Redis和应用容器，这里分享一套比较顺手的部署路线。

10.1 后端Dockerfile的编写要点

写Dockerfile时有几个容易踩的坑。第一个是JDK版本，如果你本机用的是JDK 1.8，Docker基础镜像也要对应选带JDK 8的镜像，不然编译出来的class版本不兼容。我项目用的Spring Boot 2.7 + JDK 1.8，对应的Dockerfile长这样：

dockerfile复制FROM openjdk:8-jdk-alpine
VOLUME /tmp
WORKDIR /app
COPY target/pet-adoption.jar app.jar
ENV TZ=Asia/Shanghai
RUN ln -snf /usr/share/zoneinfo/$TZ /etc/localtime && echo $TZ > /etc/timezone
EXPOSE 8080
ENTRYPOINT ["java","-Djava.security.egd=file:/dev/./urandom","-jar","app.jar","--spring.profiles.active=prod"]

这里做了两件事：一是设置了时区，确保容器里输出时间是北京时间而不是UTC；二是通过--spring.profiles.active=prod指定生产环境配置文件，应用启动时自动读取application-prod.yml里的数据库连接等配置。

第二个容易踩的坑是Docker宿主机和容器之间的网络连接。应用在容器里连接宿主机的MySQL，如果直接用localhost:3306，连的是容器自己，连不上宿主机的MySQL。需要把数据库连接地址改成host.docker.internal（Docker Desktop支持）或者直接用宿主机在局域网里的IP。如果是完整的docker-compose编排，用服务名比如mysql:3306更标准。

10.2 docker-compose编排数据库和应用

我把MySQL、Redis、后端应用、前端Nginx放在一个docker-compose.yml里，一键启动：

yaml复制version: '3'
services:
  mysql:
    image: mysql:8.0
    container_name: pet-mysql
    environment:
      MYSQL_ROOT_PASSWORD: root123456
      MYSQL_DATABASE: pet_adoption
    ports:
      - "3306:3306"
    volumes:
      - mysql-data:/var/lib/mysql
      - ./sql/init.sql:/docker-entrypoint-initdb.d/init.sql
    command: --character-set-server=utf8mb4 --collation-server=utf8mb4_unicode_ci

  redis:
    image: redis:7-alpine
    container_name: pet-redis
    ports:
      - "6379:6379"

  backend:
    build: ./backend
    container_name: pet-backend
    depends_on:
      - mysql
      - redis
    ports:
      - "8080:8080"
    environment:
      SPRING_DATASOURCE_URL: jdbc:mysql://mysql:3306/pet_adoption?useUnicode=true&characterEncoding=utf8&useSSL=false&serverTimezone=Asia/Shanghai
      SPRING_DATASOURCE_USERNAME: root
      SPRING_DATASOURCE_PASSWORD: root123456
      SPRING_REDIS_HOST: redis

  frontend:
    build: ./frontend
    container_name: pet-frontend
    ports:
      - "80:80"
    depends_on:
      - backend
volumes:
  mysql-data:

MySQL 8镜像首次启动会自动执行/docker-entrypoint-initdb.d/目录下的SQL脚本，建表和初始化数据就放在这个init.sql里。这个机制很实用，不然每次部署都要手动导入SQL。

10.3 前端构建后如何部署

前端的Vue项目打包后生成一堆静态文件，放在Nginx的html目录下。前端Dockerfile如下：

dockerfile复制FROM node:16-alpine AS builder
WORKDIR /app
COPY package.json .
RUN npm install
COPY . .
RUN npm run build

FROM nginx:alpine
COPY --from=builder /app/dist /usr/share/nginx/html
COPY nginx.conf /etc/nginx/conf.d/default.conf
EXPOSE 80

这里用的是多阶段构建——先用Node镜像编译前端，再把编译产物拷贝到Nginx镜像里。这样最终镜像里只有Nginx和静态文件，体积比带Node的镜像小很多。

Nginx配置里需要把API请求代理到后端：

nginx复制server {
    listen 80;
    server_name localhost;

    location / {
        root /usr/share/nginx/html;
        index index.html;
        try_files $uri $uri/ /index.html;  # 前端路由支持
    }

    location /api/ {
        proxy_pass http://backend:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }

    location /upload/ {
        proxy_pass http://backend:8080;
    }
}

配置里的try_files $uri $uri/ /index.html;这行很关键。Vue用的history路由模式（URL不带#号）时，直接刷新一个子页面比如说/pets/3，Nginx会返回404，因为它找不到/pets/3这个物理文件。try_files的回退到index.html让前端路由接管，刷新就不会白屏了。

11. 从开发到交付，还有哪些值得注意的细节

系统做完之后，我自己模拟救助站志愿者的日常角色跑了一遍完整流程，又趟出了不少问题。最后写下几个值得分享的体验。

11.1 宠物领养管理不要做成通用后台管理系统

很多毕设和练习项目，套用的是“通用后台管理系统”模板——用户管理、角色管理、菜单管理、字典管理一套齐全，然后硬塞进宠物领养的业务。结果是管理功能比业务功能还庞大，真实用户根本不需要那么多管理菜单。

救助站需要的核心功能其实很少：录宠物、管申请、做回访、看统计。我砍掉了字典管理、操作日志管理这些纯粹为了功能而做的模块，只保留了用户管理（给超级管理员用）和基础数据维护。做项目一定要舍得做减法，否则你的界面看起来像后台模板，真正用的时候每一步都别扭。

11.2 导入初始化数据，让演示和测试更高效

我在系统初始化时加入了演示数据：二十只不同品种的猫狗、三个不同角色的用户、若干条领养申请。用CommandLineRunner在应用启动时检测数据库为空就插入演示数据。这样做的好处有三层：一是开发联调时不用自己一个个造数据；二是给救助站演示时能直接展现出系统功能；三是测试时可以直接拿演示数据来验证流程。

初始化代码要注意幂等，不要每次启动都重复插入。我的做法是先查数据库SELECT COUNT(*) FROM pet_info，为0才执行插入。

11.3 回访记录别忘了设计

很多宠物领养系统做到“领养成功”就算结束，但救助站真实的核心需求恰恰在领养之后——定期回访，确认宠物在新家过得怎么样。救助站会要求领养人每个季度发一次宠物照片，这是确保宠物不被二次遗弃的保障机制。

我设计了一个follow_up_record表：领养人提交回访内容（文字+照片），管理员查看并确认，超过时间未回访的有提醒列表。这块逻辑不复杂，但对救助站来说是刚需，也体现了系统不是“表面管理”而是真正在关心动物。我在界面上把它放在“我的领养”里，不单独做菜单，减轻管理员的记忆负担。

11.4 一个人维护全栈项目的收益

这个项目从数据库到后端到前端到部署，一个人全包了。累是真的累，收获也大。走完一遍才知道为什么业界要区分前后端：Vue的状态管理、路由守卫和Element Plus组件库，跟Spring Security的过滤器链、MyBatis的SQL映射完全是两套思维方式。

更关键的是，当你一个人在开发时，你会被迫从“功能能跑就行”进阶到“怎么设计能少写代码”。比如领养申请和宠物状态联动的逻辑，我在第三版重构时把状态判断抽到了一个独立的PetStatusService，凡是修改宠物状态的地方都走这个服务，就再也不用担心改漏一个调用点导致状态不一致了。

11.5 给正在做类似项目的人一个建议

如果你正在用Spring Boot做类似的业务管理系统，我的建议很朴素：先跟着实际业务走一遍流程再动手，动手前把表结构设计到你能说服自己的程度，然后老老实实做状态管理上的记录和约束。系统从能跑到能用，中间差的就是这些细节。不要急着加新功能，先把一个核心流程跑得滴水不漏，比如从访客浏览宠物到领养人提交申请、管理员审核、然后回访，这一个闭环做好，整个系统就立住了一大半。

Spring Boot宠物领养管理系统实战：从需求拆解到Docker部署全记录