宠物领养小程序全栈实战：SpringBoot+微信小程序设计与部署

这个项目我有发言权。做校园实训和外包项目这几年，宠物领养类小程序被点名的频率非常高，基本算 SpringBoot 后端 + 微信小程序前端这个组合里最典型的“全家桶”式练手项目。它麻雀虽小，但五脏俱全：小程序端要处理微信登录、列表分页、表单提交、图片上传；后端要管用户体系、宠物信息、领养申请、审核状态流转、公告管理；中间还绕不开文件存储、接口鉴权、跨域、部署环境这些破事。你拿到的这套“源码+文档+运行视频+讲解视频”的宠物领养平台系统，本质上就是围绕“领养流程闭环”和“前后端分离协作”这两个核心点展开的。

这篇文章我会从项目拆解、技术选型、数据库设计、核心实现、部署排错这几个维度，把整个系统的技术脉络和实操细节完整过一遍。不管你是准备答辩、写简历、还是打算二次开发接外包，都可以直接拿这篇文章当作项目说明书来看。

1. 项目概述与核心需求拆解

1.1 宠物领养平台到底解决了什么问题

先聊点实际的。传统的宠物领养信息散落在贴吧、微信群、朋友圈，信息不透明、审核机制缺失、领养流程无法追踪，导致两个后果：一是流浪动物救助机构发布的信息很难触达有领养意愿的人；二是领养人没法判断宠物来源是否正规、领养条件是否合理。

这个宠物领养平台系统的核心价值，就是把整个流程搬到线上，形成“宠物发布—浏览筛选—提交领养申请—后台审核—领养结果反馈”的业务闭环。项目里的小程序端给普通用户用，后端管理界面给平台运营方用，两端通过接口对接数据，实现了对领养环节的可控管理。

这类系统的业务模型其实非常稳定，换汤不换药。核心角色就三类：普通用户、宠物发布者（可能是机构也可能是个人）、平台管理员。需要的核心功能点也高度相似：宠物信息的增删改查、领养申请提交与审核、公告通知、个人中心。

1.2 这套源码适合哪些人学习和使用

结合我做过的类似项目经验，这套源码的目标用户可以分成几类。

如果你是在校学生，准备 Java 方向的毕业设计或课程项目，这个项目是很好的参考模板。它的技术栈足够主流——SpringBoot + MyBatis Plus + MySQL + 微信小程序原生开发，全是面试里高频出现的技术名词。而且业务复杂度适中，既能展现水平，又不至于深到写不完。

如果你是刚入行的 Java 开发，想了解一个小程序前后端分离项目从零到一长什么样，这套源码加文档加视频的组合能帮你省不少搜资料的时间。尤其是运行视频和讲解视频，解决了“源码能跑但看不懂结构”的尴尬——文档告诉你代码在干什么，视频告诉你作者为什么这么设计。

如果你是接外包或者打算做私活儿的开发者，这类小程序的通用性极强。把宠物领养换成闲置转让、二手交易、志愿服务、校园互助，换一套业务字段和界面文案，就是一个新项目。骨架是完全通用的。

2. 技术架构与方案选型解析

2.1 后端技术栈：SpringBoot 为什么是稳妥的选择

后端基于 Java SpringBoot 开发，这是目前 Java 领域做中小型 Web 服务的事实标准。SpringBoot 的核心价值是“约定优于配置”，它通过自动装配机制把 Spring MVC、事务管理、连接池、JSON 序列化这些基础能力全部整合好，开发者只需要引入对应场景的 starter 依赖，写业务代码就行，不需要像早期 SSM 框架那样手动拼 XML 配置。

具体到这套系统，核心技术点主要集中在三层：

• 控制层（Controller）：接收小程序端发来的 HTTP 请求，做参数校验，调用业务层方法，返回统一格式的 JSON 数据。
• 业务层（Service）：封装核心业务逻辑。比如提交领养申请时要校验用户是否登录、该宠物是否已被领养、用户是否重复申请，这些判断都写在 Service 层。
• 数据层（Mapper）：基于 MyBatis Plus 操作数据库，单表 CRUD 基本不用写 SQL，复杂查询配合分页插件解决。

做单体项目选 SpringBoot 的核心原因是生态成熟、资料多、排错容易。你在部署和运行时遇到的坑，几乎都能在社区找到解决方案，这对学习者和开发者来说太重要了。

2.2 小程序端技术选型：原生开发的双刃剑

小程序端选用的是微信小程序原生框架。理由很直接：微信小程序的开发文档和社区资料是最全的，原生框架虽然写起来比 UniApp 这类跨端框架繁琐一些，但它没有中间层转换损耗，调试体验最直接，对学习小程序开发规范最友好。

原生小程序的核心文件结构是这样的：

• app.js：小程序入口文件，初始化全局数据、调用登录接口。
• app.json：全局配置，包括页面路由、窗口样式、tabBar 导航栏。
• pages/ 目录：每个页面一个文件夹，内部包含 .wxml（相当于 HTML）、.wxss（相当于 CSS）、.js（页面逻辑）、.json（页面配置）四个文件。
• utils/ 目录：封装公共方法，比如请求库、时间格式化函数。

我见过很多人纠结要不要直接上 UniApp，省得以后多端复用。但说句实在话，对于这种单体管理类项目，原生开发完全够用，而且代码可读性更高。真要换跨端框架，项目结构和生命周期方法差异不小，反而增加学习成本。

2.3 前后端交互协议与数据格式约定

前后端分离架构下，接口设计规范直接决定开发效率和调试成本。这套项目采用的是一套标准的 RESTful 风格接口 + JSON 数据交互。

后端统一封装了返回结果类，结构大致如下：

java复制public class Result<T> {
    private Integer code;      // 状态码，200 表示成功，500 表示业务异常
    private String message;    // 提示信息
    private T data;            // 业务数据

    public static <T> Result<T> success(T data) {
        Result<T> result = new Result<>();
        result.setCode(200);
        result.setMessage("操作成功");
        result.setData(data);
        return result;
    }

    public static <T> Result<T> error(String message) {
        Result<T> result = new Result<>();
        result.setCode(500);
        result.setMessage(message);
        return result;
    }
}

所有 Controller 接口的返回值都通过这个统一包装类返回，小程序端在请求封装里统一做一层拦截。这样做的最大好处是：前端不用每个接口单独处理异常状态，只要在封装的请求方法里判断一次 code 字段即可。

javascript复制const request = (url, method, data) => {
  return new Promise((resolve, reject) => {
    wx.request({
      url: BASE_URL + url,
      method: method,
      data: data,
      header: {
        'Content-Type': 'application/json',
        'Authorization': wx.getStorageSync('token')
      },
      success: (res) => {
        if (res.data.code === 200) {
          resolve(res.data.data);
        } else {
          wx.showToast({ title: res.data.message, icon: 'none' });
          reject(res.data);
        }
      },
      fail: (err) => {
        wx.showToast({ title: '网络异常', icon: 'none' });
        reject(err);
      }
    });
  });
};

注意我把 token 放到了请求头里，这个在后续登录鉴权部分会细讲，这里是整个小程序端请求层的核心。

3. 核心功能模块与数据库设计

3.1 业务功能全景图与角色权限

这类宠物领养平台通常包含三种角色，每种角色看到的功能入口和操作权限完全不同。

普通用户（微信用户）：

• 浏览宠物列表，支持按类型（猫/狗）、品种、性别等条件筛选。
• 查看宠物详情，包括图片、性格描述、健康状况、领养要求。
• 提交领养申请，填写申请理由、居住情况、养宠经验等信息。
• 收藏宠物，在个人中心查看收藏列表。
• 发布宠物信息（通常是待领养的动物信息）。
• 查看平台公告和领养反馈。

管理员（后端管理端）：

• 用户管理：查看用户列表、禁用异常账号。
• 宠物信息审核：用户发布的宠物信息需要审核通过后才会在小程序端展示。
• 领养申请审核：查看领养申请详情，操作“通过”或“拒绝”，填写审核备注。
• 公告管理：发布、编辑、下线平台公告。
• 数据统计：统计宠物发布量、领养完成量等基础数据（看具体实现程度）。

从权限角度看，小程序端接口和后台管理端接口要做区分。最简单的做法是两套登录体系：小程序端用微信登录换取 token，管理端用账号密码登录。如果项目只提供一个小程序端管理界面，那权限控制就通过用户表的 role 字段区分。

3.2 数据库表设计思路与字段说明

数据库设计是整个系统的地基，表结构是否合理直接影响代码写起来顺不顺手。这个项目的核心表大致有六张，我逐个拆开讲。

用户表（user）

openid 是用户表的关键字段，它由微信开放平台根据用户和公众号/小程序的关系生成，同一用户在同一小程序下的 openid 是唯一的，跨小程序不通用。这也是为什么 code2Session 接口必须用本小程序的 AppID 和 AppSecret 去调。

宠物表（pet）

images 字段用逗号分隔存储多张图片，是一种偷懒但实用的做法。如果要规范，可以拆一张宠物图片表，但单体项目里用分隔符存储完全没问题，读取时拆一下字符串就行。

领养申请表（adopt_apply）

这条表是核心，因为整个项目的“领养闭环”就是围绕申请状态流转展开的。用户提交申请后，管理员在后台看到待审核记录，操作通过或拒绝，用户在小程序端看到审核结果。

收藏表（favorite）、公告表（notice）、轮播图表（banner） 这三张就比较常规了，分别记录用户收藏关系、平台公告内容和首页轮播图配置。

3.3 为什么状态字段比逻辑删除更重要

在设计业务表时，我吃过亏也总结出经验：像宠物表这种数据，一定不要用“物理删除”的思路去实现“下架”操作。用户发布了一条宠物信息，运营方下架或审核不通过，这条记录不应该从数据库里消失，而是应该把状态字段切到一个不可展示的状态。

这样设计有几个好处：第一，数据可追溯，万一有纠纷可以查到原始记录；第二，抗并发，用户在浏览时管理员正好下架这条宠物，状态字段变更不会导致数据错乱；第三，业务扩展方便，比如“已领养”的宠物还可以回滚成“可领养”，如果领养失败还能重新上架。

这个项目的状态字段就做得比较完整，pet 表用一个 status 字段串联了从发布到领养完成的全生命周期。这块在视频讲解和文档里如果没细化，你需要自己在答辩或项目说明时重点阐述，它是一个非常好的“业务思考”加分点。

4. 关键功能实现与技术难点突破

4.1 微信小程序登录与 token 鉴权体系

小程序登录是整个项目的入口环节，也是新手最容易卡壳的地方。微信小程序登录的标准流程是 wx.login 获取临时 code，然后后端拿 code 去调微信的 jscode2session 接口换取 openid 和 session_key。

具体流程分四步：

javascript复制// 第一步：小程序端获取 code
wx.login({
  success: async (res) => {
    const code = res.code;
    // 第二步：把 code 发送到后端
    const data = await request('/user/login', 'POST', { code: code });
    // 第四步：保存后端返回的 token
    wx.setStorageSync('token', data.token);
  }
});

后端收到 code 后做如下处理：

java复制@PostMapping("/login")
public Result<Map<String, Object>> login(@RequestBody LoginRequest request) {
    // 调用微信接口，用 code 换取 openid
    String url = String.format(
        "https://api.weixin.qq.com/sns/jscode2session?appid=%s&secret=%s&js_code=%s&grant_type=authorization_code",
        appId, appSecret, request.getCode()
    );
    RestTemplate restTemplate = new RestTemplate();
    String response = restTemplate.getForObject(url, String.class);
    JSONObject json = JSON.parseObject(response);
    String openid = json.getString("openid");

    // 根据 openid 查用户，不存在则自动注册
    User user = userMapper.selectByOpenid(openid);
    if (user == null) {
        user = new User();
        user.setOpenid(openid);
        user.setNickname("微信用户" + openid.substring(openid.length() - 6));
        user.setCreateTime(new Date());
        userMapper.insert(user);
    }

    // 生成 token 返回给前端
    String token = JwtUtil.createToken(user.getId());
    Map<String, Object> result = new HashMap<>();
    result.put("token", token);
    result.put("userInfo", user);
    return Result.success(result);
}

这个环节有几个关键点你必须搞清楚，也是面试官最爱问的：

• 为什么登录要加 token 校验，而不是每次请求都拿 openid 查库？ 因为 openid 是敏感信息，不能暴露给前端。token 相当于服务端颁发给客户端的一张临时通行证，服务端通过解析 token 知道这个请求来自谁，不用每次都查微信接口。
• token 为什么用 JWT？ 因为 JWT 是无状态的，服务端不用存储会话信息，适合分布式部署和单体应用。校验逻辑就是验签加解析，性能高。
• session_key 为什么不存？ 大部分业务用不到 session_key，它是用来解密手机号和 wx.getUserInfo 加密数据的。如果项目没做手机号快速验证，可以不管它。

我还发现很多同学在配置 AppSecret 时把密钥写死在前端包里，这是非常危险的。小程序端代码是可以被反编译的，AppSecret 一旦泄露，任何人都能冒充这个小程序的身份去调用微信接口。正确的做法是 AppSecret 只保存在后端配置文件里。

4.2 领养申请的状态流转与并发防重

领养申请是整个系统最核心的业务操作，涉及多条数据的同时变更，必须保证数据一致性。

一次完整的提交领养申请操作，包含以下几个动作：

• 校验宠物是否存在且处于“可领养”状态（status=1）。
• 校验当前用户是否已经申请过该宠物，避免重复提交。
• 插入领养申请表，状态设为待审核。
• 更新宠物表的 status 为 2（已被申请），避免其他用户继续申请。

这些操作不能简单地在 Controller 里顺序调用，而应该在 Service 层开启事务保证原子性。Spring 的 @Transactional 注解就是干这个的，任何一步抛出异常，前面所有的写操作都会回滚。

java复制@Transactional(rollbackFor = Exception.class)
public void submitApply(ApplyRequest request, Long userId) {
    Pet pet = petMapper.selectById(request.getPetId());
    if (pet == null || pet.getStatus() != 1) {
        throw new BizException("该宠物暂不可领养");
    }

    Integer count = applyMapper.countByPetIdAndUserId(request.getPetId(), userId, 0);
    if (count > 0) {
        throw new BizException("您已申请过该宠物，请勿重复提交");
    }

    Apply apply = new Apply();
    apply.setPetId(request.getPetId());
    apply.setUserId(userId);
    apply.setReason(request.getReason());
    apply.setStatus(0);
    applyMapper.insert(apply);

    pet.setStatus(2);
    petMapper.updateById(pet);
}

这里有一个高并发场景需要留意：如果两个人同时提交对同一只宠物的领养申请，可能会出现都通过校验、都插入申请记录的情况，也就是所谓的超卖问题。最简单的解决方案是给 pet 表的 status 更新语句加上条件：

sql复制UPDATE pet SET status = 2 WHERE id = #{petId} AND status = 1;

如果受影响行数为 0，说明宠物已经被申请了，直接回滚。这是典型的乐观锁思路，在单体项目里完全够用。

4.3 图片上传与文件存储方案

宠物信息里的图片是一个不可忽视的功能点。微信小程序端通过 wx.chooseMedia 选择图片，然后用 wx.uploadFile 上传到后端，后端接收 MultipartFile 文件后保存到服务器磁盘或云存储，并返回可访问的 URL。

服务器本地存储是最简单的方案，适合学习和小规模部署。保存路径可以按日期分目录，避免一个目录下文件过多。我在一些项目里也会把图片存到 Nginx 代理的静态目录，这样图片访问不经过 Java 应用，性能更好。

上传接口核心代码如下：

java复制@PostMapping("/upload")
public Result<String> upload(@RequestParam("file") MultipartFile file) {
    String originalFilename = file.getOriginalFilename();
    String suffix = originalFilename.substring(originalFilename.lastIndexOf("."));
    String fileName = UUID.randomUUID().toString().replaceAll("-", "") + suffix;

    // 按日期建目录
    String datePath = new SimpleDateFormat("yyyyMMdd").format(new Date());
    File dir = new File(UPLOAD_PATH + "/" + datePath);
    if (!dir.exists()) {
        dir.mkdirs();
    }

    File dest = new File(dir, fileName);
    file.transferTo(dest);

    String url = "/files/" + datePath + "/" + fileName;
    return Result.success(url);
}

上传路径要搞成可配置的，不要写死在代码里。yml 配置文件里定义好本地上传路径和访问前缀，以后换服务器或换云存储都不用改代码。

4.4 管理端公告发布与首页轮播展示

管理端的公告管理和轮播图配置本质上都是对单张表的 CRUD。公告表存标题、内容、发布时间、状态，轮播图表存图片 URL、跳转链接、排序、状态。

这里有一个技术上值得注意的点：轮播图和公告都会在小程序首页展示，但每次打开小程序都实时查库的话，如果数据量大、并发高，压力会比较大。实际项目中一般会给首页数据加上 Redis 缓存。不过这套系统的定位是学习型项目，不做缓存也完全合理，你可以在答辩时提一句“如果未来用户量增长，可以引入 Redis 缓存首页数据”，反而显得你考虑了扩展性。

5. 项目运行与部署实操全流程

5.1 环境准备与版本匹配问题

运行这套项目前，先把环境装齐，版本匹配是新手最容易踩坑的地方。

后端运行环境：

• JDK 1.8 或者 JDK 8+（看项目 pom 文件指定的版本，强烈建议用 JDK 8，兼容性最好）
• Maven 3.6+（管理项目依赖）
• MySQL 5.7 或 8.0（注意数据库编码要设成 utf8mb4，否则 emoji 表情和中文特殊字符会乱码）
• IDE 推荐 IntelliJ IDEA（社区版就够用，但 Ultimate 对 Spring 项目的支持更好）

小程序端运行环境：

• 微信开发者工具（稳定版即可）
• 一个小程序 AppID（没有的话可以用测试号，但测试号无法使用部分能力如手机号验证）

这里特别提醒：如果你用的是 JDK 17 甚至更高版本，而项目本身是基于 JDK 8 的写法，编译时大概率会报“源发行版 8 需要目标发行版 8”或 “java: 警告: 源发行版 17 需要目标发行版 17”的错误。解决办法有两个：一是把 IDE 和 Maven 的编译版本全局改成 JDK 8；二是把项目升级到 Spring Boot 2.7+ 并适配 JDK 17 的语法。对于学习型项目，建议直接用 JDK 8，省心。

5.2 后端项目导入与启动步骤

第一步：创建数据库。在 MySQL 里执行项目提供的 sql 脚本，会创建数据库和全部表结构，同时插入一些初始数据，比如管理员账号、测试用户、几条宠物样例数据。

第二步：修改配置文件。打开 application.yml，改成你本机的数据库用户名和密码。如果 Redis 集成进来了，还要改 Redis 地址和密码。

第三步：启动项目。在 IDEA 里找到带有 @SpringBootApplication 注解的主启动类，右键 Run。控制台出现 Spring Boot 的启动日志，看到 Started Application in x seconds 就说明后端起来了。默认端口通常是 8080，可以在配置文件里改。

第四步：验证接口。浏览器直接访问 http://localhost:8080/pet/list，如果返回 JSON 数据，说明基础链路通。

启动后需要特别留意日志中的报错信息，比如数据库连接失败、端口被占用、依赖下载失败等，大多数问题都能从控制台日志直接定位。

5.3 微信开发者工具配置与小程序端启动

导入小程序项目很简单，打开微信开发者工具，选择“导入项目”，选择小程序端源码目录，填上自己的 AppID，就能看到代码了。但要让小程序连通本地后端，必须解决一个问题：本地网络访问。

在 utils/config.js 或 app.js 里找到 API 基础地址的配置，默认可能是线上地址或 localhost。如果后端跑在你自己的电脑上，手机上预览小程序时要改成电脑的局域网 IP，比如 http://192.168.1.100:8080。电脑上模拟器调试时可以用 http://localhost:8080，但真机预览必须用局域网 IP 或已备案的 HTTPS 域名。

还要注意，微信开发者工具默认开启了域名校验，在本地开发阶段可以这样关闭：工具栏点击“详情”，勾选“不校验合法域名、web-view（业务域名）、TLS 版本以及 HTTPS 证书”。如果不关，所有请求都会被拦截，报 errno: 600001 或 “url not in domain list” 之类的错误。

一个小程序端常见问题：真机预览时接口请求失败，报 net::ERR_CONNECTION_RESET 或 tunnel connection failed。这大概率是网络不通，检查电脑防火墙是否放行了 8080 端口，或者直接把防火墙关了再试。另外确保手机和电脑在同一个 Wi-Fi 下。

5.4 常见运行报错与解决方案速查表

整理一个我实际在项目中遇到过的报错清单，分门别类列出，方便你排错。

后端类错误

小程序端错误

6. 项目优化方向与二次开发建议

6.1 从学习项目到落地项目的升级路径

如果你不止满足于跑通项目，而是希望把它写到简历里、或者真正上线运营，有几个方向值得投入精力升级。

第一，引入 Redis 缓存。宠物列表页和详情页的访问频率最高，可以把热点数据缓存到 Redis，降低数据库压力。同时用 Redis 实现 token 的黑名单机制，用户退出登录时把 token 加入黑名单，提升安全性。

第二，图片存储从本地迁移到云存储或 MinIO 对象存储。本地存储的缺陷是扩容困难、单点故障、访问性能差。对象存储可以配合 CDN 加速图片访问，真实项目基本都会这么干。

第三，增加消息通知机制。宠物审核通过、领养申请有结果时，通过微信小程序订阅消息推送给用户。这块需要在小程序后台申请订阅消息模板，前端调用 wx.requestSubscribeMessage 授权，后端通过 HTTP 接口调用微信订阅消息发送接口。

6.2 代码规范与工程化意识

这个项目如果是多人协作或者要在简历里展示，代码规范就得重视。我翻过不少同学的毕设项目，最常见的问题是：Controller 里堆了太多业务逻辑、SQL 语句裸写在 Mapper 层、异常没有统一处理、日志打印夹杂着大量的 System.out.println。

建议你花半天时间做一轮重构，收益会很大：

• 引入全局异常处理器 @RestControllerAdvice，统一捕获并返回业务异常和系统异常。
• 把常量抽到枚举类或常量类，比如宠物状态、审核状态，不要散落在各处。
• 给复杂业务方法加上 @Slf4j 日志，关键流程打点记录。
• 接口返回类统一使用前面说的 Result 泛型结构。

这些调整不会改变功能，但代码的可维护性和可读性会明显提升。面试官看项目时，代码整洁程度是除业务逻辑外印象分最高的环节。

6.3 基于 SpringBoot 生态的扩展玩法

这个项目如果你想玩出点差异化，可以往这些方向扩展：

• 引入定时任务：对超过一定时间未处理的领养申请自动提醒，或定期清理无效宠物信息。Spring Schedule 就能实现，非常轻量。
• 引入 Workflow 概念：把领养申请的状态流转抽象成一个轻量级状态机，让代码更清爽。
• 做一个小程序管理端：很多情况下管理员不想开电脑，可以套一套现成的 UI 组件库（如 Vant Weapp），实现一个简版管理小程序。
• 增加数据统计图表：后端统计领养转化率、宠物类型分布、每月新增领养数量，小程序端用 ECharts 的可视化组件展示。

这些扩展点无论从学习深度还是面试加分角度来看，都很有价值，而且都有成熟的实现方案可以参考。

做这个项目时，我自己印象最深的一个坑是图片上传后的 URL 配置。小程序端如果直接访问 http://localhost:8080/files/xxx.jpg，在模拟器上没事，真机一测就挂——因为手机访问 localhost 访问的是手机自己。这个问题当时卡了我将近半天，改配置就 3 秒钟，希望你能避开。总之，这套宠物领养平台系统的技术覆盖面和学习价值在于，你跟着跑一遍，相当于把 Java 后端开发、小程序开发、数据库设计、接口联调、部署排错整个流程都过了一遍。拿着源码把每个模块跑通、看明白、再改一改，这个项目的价值才能真正变成你自己的东西。