Spring Boot宠物领养管理系统：从数据库设计到部署全实践

做宠物领养管理系统这个项目，其实是我接的一个比较典型的校内实训类需求：要求用 Spring Boot 做一套能跑起来的宠物领养管理后台，既要有普通用户浏览宠物、提交领养申请的入口，也要有管理员维护宠物信息、审核领养申请的后台功能，最后还得交源码和配套文档。这类项目在毕业设计、课程设计和初级开发者的简历作品里出现频率极高，但网上能找到的大多数资源要么残缺不全，要么文档写得像流水账，真正能一键跑起来的不多。这篇就结合我实际开发和收拾这套源码的经验，把整个系统的设计思路、核心表结构、关键接口实现、部署文档怎么写，以及遇到的各种坑都梳理一遍，给你一份可以直接参考复现的完整方案。

1. 项目定位与整体设计思路拆解

1.1 这个管理系统到底解决什么问题

先说个现实背景。线下宠物领养的信息流通方式很原始——救助站有猫有狗但是没人知道，想领养的人找不到可靠渠道，中间还夹着审核、回访、免疫记录这些流程。信息靠朋友圈转发，申请靠打电话登记，审核结果靠人工通知。这套管理系统要做的其实就是三件事：把宠物信息放到线上展示，把领养申请流程搬到线上流转，把管理员的日常维护工作集中到一个后台界面里。

普通用户登录后可以浏览宠物列表、查看宠物详情（品种、年龄、性格、健康状况、疫苗情况）、收藏看中的宠物、提交领养申请、查看申请进度。管理员登录后台可以维护宠物信息上下架、管理用户、审核领养申请、发布领养公告。整个系统就是一个典型的单业务域管理平台，不需要处理复杂的并发交易，也不涉及多系统协作。想清楚这个定位很重要，因为它直接决定了技术选型的方向——这种场景用单体应用、单数据库、简单的权限控制就够了，完全没必要引入微服务和消息队列。

1.2 为什么用 Spring Boot 做单体应用

选型这件事，我见过太多人一上来就纠结“要不要搞个微服务”，最后把简单问题复杂化。这个宠物领养管理系统属于经典的“单体应用就够了”的类型。Spring Boot 合适的理由很直白：

• 自动化配置省掉大量 XML。SSM 时代要写数据源配置、MyBatis 配置、事务配置、组件扫描配置，Spring Boot 一个 application.yml 就能搞定大部分，启动类一写就能跑。
• 内嵌 Tomcat，部署只需要一个 jar 包。java -jar 就能启动，对新手和环境迁移极其友好。
• 生态成熟，社区资料多。遇到问题搜一下基本都有答案，这对做毕设或练手的人来说太重要了。
• 自带 Actuator、参数校验、统一异常处理等实用能力，提升开发效率。

要对比的话，传统 SSM 不是不能做，但配置成本高，调试麻烦；Spring Cloud 微服务体系又太重，服务拆分、注册中心、配置中心这些对这个项目来说完全是用不上的复杂度。单体 Spring Boot 恰好卡在“够用”和“省事”的平衡点上。

1.3 技术选型对照：MyBatis-Plus 还是 JPA

持久层框架选什么，我在这个项目里最终用了 MyBatis-Plus。先看一组对比：

选 MyBatis-Plus 还有个很现实的原因：国内开发岗和毕设的氛围里，用 MyBatis 系的比例远超 JPA，以后面试聊项目也更好对线。它的 BaseMapper 直接内置了增删改查，配合 LambdaQueryWrapper 可以免写大量 SQL；需要连表或复杂统计的场景，自己写 @Select 注解 SQL 也完全控制得住。代码生成器还能一键生成 entity、mapper、service 骨架，对于一个管理类系统来说效率提升非常明显。

2. 核心功能拆解与数据库建模

2.1 角色与权限体系怎么搭

宠物领养管理系统权限不用设计得太复杂，三种角色就够了：普通用户、管理员、机构用户（比如救助站或宠物店员工）。但为了毕设或简历里有的聊，我建议权限数据模型还是做成经典的 RBAC 简化版，不要直接用 is_admin 字段就完事。

简单说就是五张表：用户表、角色表、用户角色关联表、菜单权限表、角色菜单关联表。用户登录后查角色，角色查菜单，前端根据权限渲染按钮和菜单，后端在拦截器里做接口级别的权限校验。这种设计的好处是可扩展性——以后想加一个“审核员”角色，只往角色表里插一条记录，再给角色配菜单权限就行，代码逻辑完全不用动。

实际开发中，如果时间紧，可以把角色表直接写死成枚举，用户表加一个 role_id 字段就行。但做完整版还是推荐五张表，文档里画 ER 图也好看，答辩时也更有东西讲。用户和角色关联表里，一个用户可以有多个角色，虽然这个项目里不常用，但模型上保留多对多是正规做法。

2.2 数据库表设计实战

核心表我设计成七张：用户表、宠物信息表、领养申请表、收藏表、公告表、角色表、菜单权限表。下面把最重要的几张表拆开看关键字段。

用户表核心字段：

宠物信息表核心字段：

领养申请表核心字段：

这里有个细节要注意：applicant_name、applicant_phone 这些字段建议冗余在申请表里，不要通过 user_id 去联表查。理由很现实——用户可能中途改手机号，但申请记录需要保留申请当时的联系方式；而且列表页展示时少一次联表，SQL 简单很多。这就是典型的“空间换时间”设计思路。

2.3 领养申请状态机设计

领养申请是整个业务的核心流转对象，状态设计得好不好直接影响代码复杂度。我把状态定义成这样：

code复制待审核(0) -> 审核通过(1) -> 已完成(4)
待审核(0) -> 审核拒绝(2)
待审核(0) -> 用户取消(3)
审核通过(1) -> 已完成(4)

具体含义：用户提交申请后状态是待审核；管理员审核通过后进入审核通过状态，此时管理员可以联系申请人线下交接宠物，交接完成把状态改成已完成；如果管理员觉得申请人不合适，直接拒绝并填写审核意见；用户在待审核阶段也可以主动取消申请。

为什么咬定状态流转的路径要单一？因为在实现的时候会遇到并发问题。比如用户和管理员同时操作：管理员点击“审核通过”时，用户恰好点了“取消申请”，如果代码里只是简单 update ... set status = 1 where id = ?，就会出现状态覆盖，最终数据跟实际业务对应不上。

解决办法有两个层面。第一层是代码控制：更新时在 SQL 里带上 and status = 0，即只能从待审核状态流转，更新成功行数为 0 就说明状态已被其他操作修改，需要返回提示。第二层是乐观锁：业务表加一个 version 字段，更新时比对版本号，版本不一致则更新失败。对小项目来说，SQL 条件更新已经够用，乐观锁可以在文档里作为扩展方案提一句，显得你思考过并发问题。

3. 从零到一：核心功能实现与部署

3.1 项目结构怎么组织

一个清晰的项目结构能省掉后面大量的维护时间。我按常见的四层结构来组织，包名用 com.pet.adoption：

code复制com.pet.adoption
├── Application.java                  // 启动类
├── common                            // 通用模块
│   ├── result                        // 统一返回 Result 封装
│   ├── exception                     // 全局异常处理
│   └── utils                         // 工具类
├── config                            // 配置类
│   ├── WebMvcConfig.java             // 静态资源映射、拦截器注册
│   ├── MybatisPlusConfig.java        // 分页插件配置
│   └── Knife4jConfig.java            // 接口文档配置
├── controller                        // 控制层
│   ├── AdminPetController.java       // 后台宠物管理接口
│   ├── AdminAdoptionController.java  // 后台领养审核接口
│   └── PetController.java            // 前台宠物浏览接口
├── service                           // 业务层
│   ├── PetService.java
│   ├── AdoptionService.java
│   └── impl                          // 业务实现类
├── mapper                            // 数据访问层
│   ├── PetMapper.java
│   └── AdoptionMapper.java
├── entity                            // 实体类
├── dto                               // 入参/出参对象
│   ├── AdoptionApplyDTO.java         // 提交领养申请入参
│   └── PetQueryDTO.java              // 宠物查询条件
└── vo                                // 视图对象

有人会问 dto 和 vo 是不是重复造轮子，我的个人习惯是接口入参和出参必须跟实体类分离。实体类 Pet 有 description 这种大字段，但列表页接口根本不需要返回它；实体类里的 createTime 数据库格式是 datetime，前端期望的可能是格式化后的字符串。手动组装 VO 虽然多写几行代码，但接口数据可控，也避免把实体类直接暴露给前端带来的安全隐患。

3.2 后端接口实现要点

核心接口主要分三块：前台用户操作、后台管理操作、用户中心操作。我挑几个容易写错的接口重点讲。

宠物分页列表接口。这个接口要支持按类型筛选、按关键字搜索、按状态过滤：

java复制@GetMapping("/pet/list")
public Result<IPage<PetVO>> list(PetQueryDTO queryDTO,
                                 @RequestParam(defaultValue = "1") Integer pageNum,
                                 @RequestParam(defaultValue = "10") Integer pageSize) {
    Page<Pet> page = new Page<>(pageNum, pageSize);
    LambdaQueryWrapper<Pet> wrapper = new LambdaQueryWrapper<>();
    wrapper.eq(StringUtils.hasText(queryDTO.getCategory()), Pet::getCategory, queryDTO.getCategory())
           .like(StringUtils.hasText(queryDTO.getKeyword()), Pet::getName, queryDTO.getKeyword())
           .eq(Pet::getStatus, 1)
           .orderByDesc(Pet::getCreateTime);
    IPage<Pet> petPage = petService.page(page, wrapper);
    // 转 VO，去掉敏感字段、拼接图片完整地址
    return Result.success(convertToVO(petPage));
}

这段代码里有几个点值得说。StringUtils.hasText() 条件判断写在 Wrapper 里，参数为空就不拼接这个条件，这样就不用写一堆 if 分支；状态固定查 1 是保证用户只能看到“待领养”状态的宠物，后台的草稿、下架数据不会漏出去；orderByDesc 按录入时间倒序，最新收录的宠物排前面，这个排序逻辑虽然简单但对用户体验影响很大。

提交领养申请接口，这个要考虑幂等性和业务校验：

java复制@PostMapping("/adoption/apply")
public Result<?> apply(@RequestBody @Validated AdoptionApplyDTO dto) {
    Pet pet = petService.getById(dto.getPetId());
    if (pet == null || pet.getStatus() != 1) {
        return Result.error("该宠物暂不可领养");
    }
    // 检查用户是否已申请过该宠物（申请中状态）
    Long count = adoptionService.lambdaQuery()
            .eq(Adoption::getUserId, dto.getUserId())
            .eq(Adoption::getPetId, dto.getPetId())
            .in(Adoption::getStatus, 0, 1)
            .count();
    if (count > 0) {
        return Result.error("您已申请过该宠物，请勿重复申请");
    }
    Adoption adoption = new Adoption();
    BeanUtils.copyProperties(dto, adoption);
    adoption.setStatus(0);
    adoptionService.save(adoption);
    return Result.success();
}

重复申请校验是很容易被忽略的点。如果没有这层检查，用户可以无限提交申请，后台会收到大量重复数据，管理员根本没法判断到底该审核哪条。用 in(status, 0, 1) 是为了防止用户在“待审核”或“审核通过”阶段重复提交，但已经拒绝、取消、完成的申请不拦，用户可以重新申请。这个逻辑控制得很精确。

管理员审核接口：

java复制@PostMapping("/admin/adoption/audit")
public Result<?> audit(@RequestBody AuditDTO dto) {
    boolean updated = adoptionService.lambdaUpdate()
            .eq(Adoption::getId, dto.getId())
            .eq(Adoption::getStatus, 0)   // 关键：只在待审核状态下才能更新
            .set(Adoption::getStatus, dto.getStatus())
            .set(Adoption::getAuditRemark, dto.getRemark())
            .set(Adoption::getAuditTime, LocalDateTime.now())
            .update();
    if (!updated) {
        return Result.error("申请状态已变更，请刷新后重试");
    }
    if (dto.getStatus() == 1) {
        // 审核通过后，自动把宠物标记为已领养
        Adoption adoption = adoptionService.getById(dto.getId());
        petService.lambdaUpdate()
                .eq(Pet::getId, adoption.getPetId())
                .set(Pet::getStatus, 2)
                .update();
    }
    return Result.success();
}

这里最核心的就是 eq(Adoption::getStatus, 0) 这个条件。它配合 MyBatis-Plus 的 lambdaUpdate，生成的 SQL 是 update adoption set status=?, ... where id=? and status=0。如果这条记录状态已经不是 0，更新影响行数为 0，updated 为 false，返回错误提示。这就解决了前面说的并发状态覆盖问题。

还有一个业务细节：审核通过时要把对应宠物状态改成已领养。这个操作必须在同一个事务里，否则可能出现申请通过了但宠物还是待领养状态，别的用户还能继续申请这只宠物。事务的解决方式是在 service 方法上加 @Transactional 注解，让两个更新操作绑定在一起。

3.3 文件上传与图片处理

宠物图片上传是整个系统里很容易踩坑的点。先明确一个原则：图片文件不要直接存数据库，存数据库的是文件路径或 URL。实现方案有几种：

本地存储方案，适合毕设和演示环境。在配置文件中指定上传目录，比如 D:/pet-adoption/upload/，上传接口把 MultipartFile 保存到该目录，文件名用 UUID 重命名避免冲突，然后把 /upload/宠物图片UUID.jpg 这样的相对路径返回给前端。再通过 WebMvcConfig 做虚拟路径映射，访问 /upload/** 时映射到实际磁盘目录：

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

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

为什么用 UUID 重命名？因为用户上传的文件名可能是中文、带空格、带特殊字符，直接保存容易出路径解析问题，还可能有重名覆盖风险。UUID 生成文件名虽然不可读，但能确保唯一性和 URL 安全性，实际应用都是这种方案。

考虑将来要上线的场景，可以预留 OSS 方案。上传接口不变，只是把保存的实现从本地换成阿里云 OSS 或腾讯云 COS 的 SDK 调用。这个可以在文档的扩展章节里写，说明接口面向接口编程，后续可以无缝替换。

图片大小和类型校验也不能放松。后端接口里要做限制，文件大小不超过 5MB，类型只允许 jpg、png、jpeg、webp。前端虽然能限制，但接口层面不校验等于裸奔，用 Postman 直接调接口就能绕过前端限制，往服务器上传一堆非法文件。

3.4 打包部署全流程

这个项目部署相对简单，因为我选的是单体架构 + 内嵌 Tomcat，所以打一个 jar 包就够了。但实际部署过程中还是有不少细节要注意。

第一步是环境准备。服务器上装 JDK（版本要和项目对应，Spring Boot 2.7 用 JDK 8 或 11 都行，Spring Boot 3.x 必须 JDK 17）和 MySQL。数据库执行项目里的 init.sql 初始化表结构和基础数据。

第二步是配置多环境。在 application.yml 里拆分 application-dev.yml 和 application-prod.yml，开发环境连本地数据库，生产环境连服务器数据库。数据源配置里防止连库报错，URL 后面必须带参数：

yaml复制spring:
  datasource:
    url: jdbc:mysql://localhost:3306/pet_adoption?useUnicode=true&characterEncoding=utf8&useSSL=false&serverTimezone=Asia/Shanghai&allowPublicKeyRetrieval=true

serverTimezone=Asia/Shanghai 是必须的，否则 JDBC 连接 MySQL 8 时会报时区错误。allowPublicKeyRetrieval=true 是 MySQL 8 用空密码或 caching_sha2_password 插件时容易遇到的问题，加上能避免很多莫名其妙的连库失败。

第三步是打包测试。在项目根目录执行 mvn clean package -Dmaven.test.skip=true，跳过测试可以避免测试环境依赖问题，打包快很多。然后本地先用 java -jar target/pet-adoption.jar 跑一次，确认启动日志没有任何 ERROR。

第四步是上线部署。把 jar 包传到服务器，如果你有宝塔面板，操作很方便；没有就用命令行配合 systemd 服务管理。我建议用 systemd 而不是直接 nohup java -jar，因为 systemd 能管理开机自启和服务异常退出自动重启。一个最简单的 service 文件：

code复制[Unit]
Description=pet-adoption
After=network.target

[Service]
User=root
WorkingDirectory=/opt/pet-adoption
ExecStart=/usr/local/jdk/bin/java -Xms256m -Xmx512m -jar pet-adoption.jar
Restart=always

[Install]
WantedBy=multi-user.target

前端页面如果集成在 Spring Boot 的 static 目录里，直接一起打包就行；如果前端是 Vue 项目单独部署，就用 Nginx 做反向代理，把 /api/ 路径转发到后端 8080 端口，前端静态资源由 Nginx 直接托管。反向代理配置记得加上时间设置，因为图片上传接口在大文件时耗时较长：

code复制server {
    listen 80;
    server_name your-domain.com;

    location / {
        root /opt/pet-adoption/frontend;
        index index.html;
        try_files $uri $uri/ /index.html;
    }

    location /api/ {
        proxy_pass http://127.0.0.1:8080/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        client_max_body_size 10m;
        proxy_read_timeout 300s;
    }
}

client_max_body_size 10m 这个设置经常被忽略，默认 1m 会直接导致图片上传接口 413 报错。虽然后端限制了 5MB，但 Nginx 这层也要同步放宽，否则请求根本到不了后端就被拦截了。

4. 常见问题与排查技巧实录

4.1 接口 404 和静态资源无法访问

部署完发现访问 /pet/list 返回 404，但登录接口正常。这类问题通常是拦截器或路径映射的锅。排查顺序：先确认控制台有没有打印请求日志，再看 controller 的 @RequestMapping 路径是否拼写一致，最后检查是不是拦截器把所有 /pet/** 请求拦掉了。

静态资源进不去的问题，九成出在 application.yml 的 spring.mvc.static-path-pattern 配置。默认是 /**，如果你改成了 /static/**，页面里引用的 JS、CSS 路径也得跟着改成 /static/xxx。另一个常见原因是没有配置虚拟路径映射（addResourceHandlers），上传的图片在浏览器里访问不到，报 404，本质是 URL 路径没有映射到磁盘实际路径。

4.2 数据库中文乱码和时区问题

中文乱码是老生常谈但永远有人踩。一线排查步骤：第一看数据库表字符集，必须是 utf8mb4；第二看 JDBC URL 有没有 characterEncoding=utf8；第三看返回 JSON 时是不是用了 @RequestMapping(produces = "application/json;charset=UTF-8")；最后再看前端页面 meta 标签字符集。四层都对了基本不会乱码。MySQL 8 的时区问题前面说过，URL 写死 serverTimezone=Asia/Shanghai 就完事。

4.3 事务不生效的坑

我在这个项目里写过一段代码，在 service 里调另一个 service 的审核方法，审核通过后更新宠物状态，当时发现宠物状态经常不更新。排查半天发现是没加 @Transactional。事务不生效还要注意另一种情况：同一个类内部方法调用，比如 savePet 方法里调用自己的 updatePetStatus 方法，即使 updatePetStatus 上有 @Transactional，因为走的是 this 调用而非代理对象调用，事务也不会生效。解决方式是拆成两个 service，或者注入自身代理。

4.4 开发环境跨域问题

前端跑在 8080 端口，后端跑在 8081 端口，浏览器直接请求接口就报跨域错误。虽然前后端部署在同一个 Nginx 下时不存在跨域，但本地开发免不了。通用做法是加一个全局 CORS 配置类：

java复制@Configuration
public class CorsConfig {
    @Bean
    public CorsFilter corsFilter() {
        CorsConfiguration config = new CorsConfiguration();
        config.addAllowedOriginPattern("*");
        config.addAllowedMethod("*");
        config.addAllowedHeader("*");
        config.setAllowCredentials(true);
        UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource();
        source.registerCorsConfiguration("/**", config);
        return new CorsFilter(source);
    }
}

这里有个细节：允许跨域的来源用 addAllowedOriginPattern("*") 而不是 addAllowedOrigin("*")，因为后者在 AllowCredentials 为 true 时会被浏览器拒绝，但 Pattern 方式可以正常匹配。这个坑我当时踩了很久。

4.5 上传文件大小超限

本地测试小图片没问题，传一张 3MB 的照片就报错。Spring Boot 默认的单文件上传上限是 1MB，需要在配置里调大：

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

配套地，文件上传接口里再用注解做一层控制：

java复制@PostMapping("/admin/pet/upload")
public Result<String> upload(@RequestParam("file") @RequestParam(maxFileSize = "5MB") MultipartFile file)

Spring Boot 的 multipart 配置是全局的，接口注解是局部的，两层都要设置，缺一个都有问题。

5. 文档体系怎么搭才算完整

收尾说一句文档的事。很多人拿到源码就跑，文档这种“边角料”随便糊弄两页 Word。但既然是“源码+文档”作为交付物，文档的价值至少跟代码持平。我写这类项目文档有一个固定结构，直接照着套就行：

• 需求分析：项目背景、用户角色分析、功能需求列表（用表格列功能点和优先级）。
• 数据库设计：ER 图、数据字典（每张表的字段名、类型、含义、是否必填），这是最花时间但最值钱的部分。
• 接口文档：用 Knife4j（Spring Boot 2.x 配合 springfox 3.0.0）自动生成，但接口含义和业务逻辑说明要手动补，尤其是领养审核状态流转这种接口文档里看不出前后逻辑的地方。
• 部署文档：从 JDK 安装到数据库初始化到 jar 包启动的完整步骤，精确到每个命令。
• 测试报告：核心功能点测试用例和测试结果截图。这个在答辩和学习总结里都很有用。
• 扩展思路：能往哪个方向加功能（比如短信通知、消息推送、管理端数据统计图表），说明你的系统留有扩展空间。

我个人在做这类毕设级管理系统时有个习惯，先把 ER 图和状态流转图画清楚再动手写代码。因为这类系统业务不复杂，难点不在编码而在建模——表关系理清了，技术层的实现都像填空。你对着这套文档把表建好、把接口跑通、把流程状态梳理顺，这套宠物领养管理系统就彻底属于你了。就算后续要把它改成二手物品交换平台或者社区服务预约系统，底层的用户体系、后台管理、审核流模块都是能直接复用搬走的。