大学校园里其实有大量零散的生活服务需求丢了东西要发失物招领毕业季要处理二手书和闲置物品社团要在线上组织活动报名课程表、校历、公告这些信息大家每天都得看。这些需求单独做一个App太重用网页又不够方便微信小程序反而是最合适的载体——用户不用下载安装扫一下就能用传播也方便。后端我选了 SpringBoot 2.7.x MyBatis-Plus MySQL 这套组合前端就是微信原生小程序。整个项目前后端分离小程序端负责展示和交互SpringBoot 提供 RESTful API。这个选型在今天来看不算新奇但胜在成熟、稳定、资料多遇到问题随便一搜都有答案特别适合校园场景这种典型的CRUD密集型业务。下面我把整个项目的设计思路、核心实现和踩坑记录整理出来给正在做类似项目的同学一个参考。1. 项目整体设计与技术选型1.1 为什么是 SpringBoot 微信小程序先讲讲我为什么没有用更新的方案。像 uniapp、Taro 这种跨端框架我也试过但考虑到这个项目的使用场景基本锁定在微信生态内——用户都是在校学生手机里肯定装了微信不存在需要同时发 App 的需求那用微信原生小程序反而是最省事的组件直接可用调试工具完善预览和真机调试都方便。如果用了 uniapp虽然以后能多端复用但引入的抽象层会让部分功能比如 canvas 绘图、蓝牙、扫码变得绕排查问题也多一层阻碍。后端选 SpringBoot 的理由更直接。校园综合服务的核心就是一堆增删改查SpringBoot 提供自动配置和起步依赖几分钟就能拉起一个能跑的项目。配合 MyBatis-Plus单表操作基本不用写 SQL代码量少一大截。当时我对比过 SSM 和 SpringBootSSM 那一套 XML 配置放在今天确实显得繁琐了SpringBoot 用注解和默认配置就把项目结构简化了对新手也更友好。全套技术栈大概是这样的后端SpringBoot 2.7.x MyBatis-Plus MySQL 8.0 Redis做缓存和频率限制前端微信原生小程序 自定义组件库鉴权微信登录 code2session 自定义 JWT token部署后端打成 jar 用 Docker 部署小程序通过微信开发者工具上传1.2 核心功能模块怎么划分校园综合服务听起来很大但拆开来看其实就几个高频场景。我当时和学生用户聊了一圈最后把功能收敛成四大模块失物招领发布丢失或捡到的物品信息带上图片、地点、联系方式支持按状态筛选待认领/已找回。二手交易毕业生处理教材、电动车、生活用品发布商品、联系卖家、标记已售。校园活动社团和学生会发布活动学生在线报名支持查看报名记录。信息服务课程表查询、校历、校区公告这类静态加半动态信息。为什么这样分因为这几个模块的用户群体和操作模式都不同。失物招领是强时效性、地理位置相关的要求发布流程极简二手交易需要图片多、信息完整但交易本身我们不做线上下单只是提供一个信息撮合平台避免涉及支付等复杂问题活动报名有明确的截止时间和人数限制信息服务则是纯读取几乎不涉及用户操作。按这个维度拆模块数据库设计和接口设计都会清晰很多。每个模块我都单独设计了 controller、service、mapper 包模块之间互不依赖。这里有个经验不要为了省事把所有功能塞进一个综合服务的 service 里后期每加一个需求都要动同一个类改出 bug 的概率直线上升。模块化虽然刚开始多写几个类但维护期的幸福感完全不一样。2. 后端核心细节与接口设计2.1 微信登录与用户体系搭建微信小程序有一个特点没有传统的用户名密码注册登录而是通过 wx.login 拿到临时 code后端拿 code 去微信服务器换 openid 和 session_key。整个流程是这样小程序端调用 wx.login() 拿到 code。小程序把 code 发给后端接口。后端用 code appid secret 请求微信的 jscode2session 接口拿到 openid 和 session_key。后端用 openid 查数据库如果不存在就创建用户然后签发一个自己的登录凭证JWT返回给小程序。小程序把 token 存到 storage后续所有请求都带上。这里有个关键点后端绝对不能把 openid 直接返回给前端当成登录凭证用。一是 openid 是用户的唯一标识泄露出去等于暴露身份二是微信的 session_key 有时效性直接透传给前端会导致后续无法控制会话有效期。我选择的是 JWT把 userId 放进去设置 7 天有效期配合拦截器统一校验。核心登录逻辑大概是这样的PostMapping(/login) public Result login(RequestBody LoginRequest req) { // 1. 用 code 换 openid String url https://api.weixin.qq.com/sns/jscode2session?appid appid secret secret js_code req.getCode() grant_typeauthorization_code; String resp restTemplate.getForObject(url, String.class); JSONObject obj JSON.parseObject(resp); String openid obj.getString(openid); // 2. 查用户不存在则注册 User user userService.getByOpenid(openid); if (user null) { user new User(); user.setOpenid(openid); user.setNickname(微信用户 openid.substring(openid.length() - 6)); userService.save(user); } // 3. 签发 JWT7 天有效期 String token JwtUtil.createToken(user.getId(), 7 * 24 * 3600 * 1000L); return Result.ok(new LoginVO(token, user)); }2.2 数据表设计要点数据表的设计直接决定后面开发顺不顺利。我踩过设计太简单后来频繁改表的坑所以这次把核心字段一次性想清楚。用户表 usersid、openid、nickname、avatar、phone、student_no学号选填、create_time。openid 加唯一索引这是登录查询的入口。失物招领表 lost_foundid、user_id、type丢失/捡到、title、description、imagesJSON 数组存图片路径、location、contact、status0待认领 1已找回 2已撤销、create_time。这里 images 我用 JSON 字符串存因为一个帖子图片数量不固定单独建一张图片表又有点重。如果后续需要按图片检索再拆表也不迟。二手交易表 goodsid、user_id、title、description、price、images、category、status0在售 1已售 2下架、create_time。活动表 activityid、title、description、location、start_time、end_time、max_people、current_people、status、create_time。活动报名表 activity_registerid、activity_id、user_id、create_time、unique(activity_id, user_id)。这对唯一索引很重要防止同一用户重复报名。公告表 noticeid、title、content、create_time。关于时间字段我强烈建议用 datetime 而不是 timestamp。timestamp 有 2038 年的问题而且受时区影响前后端对接时容易出差 8 小时的幺蛾子。datetime 虽然存储上多占点空间但省心。还有一个经验所有表都加上 create_time 和 update_time 两个字段用 MyBatis-Plus 的自动填充功能统一维护不要在业务代码里手动塞时间。这样排查数据问题时能看到记录是什么时候创建的、最后什么时候改的非常有用。2.3 关键接口的实现思路接口设计遵循 RESTful 风格统一返回结构。我定义了一个 Result 类code 表示状态码msg 表示提示信息data 放业务数据。所有接口返回这个结构前端封装层只需要处理一种格式。几个核心接口POST /auth/login登录换 token。GET /user/info获取当前用户信息需要带 token。POST /lost-found发布失物招领。GET /lost-found/list?typelostpage1size10分页查询支持类型、状态过滤。POST /lost-found/found/{id}标记为已找回。POST /goods发布二手商品。GET /goods/list分页查询商品。POST /activity/{id}/register活动报名。GET /activity/{id}/register/status查询当前用户是否已报名。分页查询我用的是 MyBatis-Plus 的 Page 对象加上自定义的条件构造器。有一个细节列表接口一定要做参数校验page 不能小于 1size 要限长比如最多 20不然用户传一个 size10000 会把整个数据库都拉出来了。图片上传接口我单独说一下。POST /file/upload用 multipart 接收文件存储到服务器指定目录返回访问路径。存储路径要用日期分目录比如upload/2025/06/15/uuid.jpg避免所有文件堆在一个目录里文件多了系统会变慢。文件名一定要重写用 UUID不要用用户上传的原始文件名——原始文件名可能包含中文、特殊字符直接存储容易出乱码和路径问题更麻烦的是可能存在路径穿越风险。3. 小程序端实现要点3.1 请求封装与登录态管理小程序端最基础也最重要的就是请求封装。微信原生的 wx.request 功能比较裸需要我们自己统一处理 baseURL、请求头、错误码、token 注入和过期跳转。我封装了一个 request.js核心思路const BASE_URL https://api.example.com; function 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 if (res.data.code 401) { // token 过期重新登录 login().then(() request(url, method, data)).catch(reject); } else { wx.showToast({ title: res.data.msg, icon: none }); reject(res.data); } }, fail(err) { reject(err); } }); }); }这里有两个坑值得说。第一token 失效时的处理。如果用户 token 过期接口返回 401不能只是弹一个登录过期的提示然后让用户手动重新进入那样体验很差。我是在请求封装层自动重新调用 wx.login拿到新 token 后再重放原来的请求用户完全无感知。这个请求重放机制代码量不大但实际体验提升很明显。第二并发请求时的 token 刷新问题。如果同时有多个请求都返回 401会触发多次重新登录造成 token 互相覆盖。解决方法是加一个是否正在刷新 token的标记如果正在刷新其他请求进入等待队列刷新完成后再统一放行。这个并发控制平时不触发但一旦用户长时间不用小程序打开后首屏多个接口同时请求就会踩中。登录态存储我用的是 wx.setStorageSync 存 token同时存了 token 的过期时间。每次请求前检查本地过期时间如果只剩几分钟就提前走刷新逻辑避免请求到一半被 401 打断。3.2 页面与交互设计页面结构上我用了 TabBar 五级导航首页、广场、发布、消息、我的。首页聚合推荐内容广场是信息流列表发布是失物/二手/活动的统一入口消息放报名通知和交易咨询我的就是个人中心和我的发布记录。有个细节发布按钮放在 TabBar 中间位置视觉上突出。但微信原生 TabBar 每个项都是一个普通 tab做中间凸起效果需要自定义 TabBar 组件成本稍高。我当时图省事直接把发布也做成一个普通 tab 页面在页面上放一个大的发布按钮跳转到发布选择页效果也可以开发量小很多。列表页用 scroll-view 做触底加载配合后端的分页接口。这里注意触底加载要防重复请求我加了一个 loading 状态和 page.hasMore 判断列表最后一页时停止请求避免无效的网络请求。首页的信息展示我用了骨架屏组件数据未回来时先显示灰色占位块虽然是小细节但用户感知上会觉得加载快、不闪烁。小程序原生有 wx.showLoading但整页遮罩太生硬骨架屏体验更好。关于图片发布页的图片上传我用 wx.chooseMedia 选择图片压缩参数 sizeType: [compressed]然后通过 wx.uploadFile 传给后端。显示端用 image 组件的 lazy-load 属性做懒加载列表页图片多的时候滚动明显流畅很多。图片路径有个坑如果后端返回的是相对路径 /upload/xxx.jpg在小程序里不能直接用因为小程序没有域名概念必须拼接上后端的完整地址。建议后端直接返回完整 URL域名 路径前端不用做拼接逻辑。4. 部署联调与安全细节4.1 后端部署配置后端我用 Docker 部署到云服务器。Dockerfile 很简单基于 openjdk:8-jre-alpine 镜像把 jar 打进去暴露 8080 端口。这里有一个经验构建镜像时用多阶段构建先用 maven 镜像编译源码再把编译好的 jar 复制到运行镜像里这样最终镜像体积小很多。我见过不少新手直接把源码和构建工具都塞进运行镜像一个镜像好几个 G传一次都费劲。redis 和 mysql 也用 docker-compose 一起管理配置文件通过环境变量注入避免把密码写在代码里。小程序请求的域名必须是 HTTPS而且要从小程序后台配置 request 合法域名。当时我图省事在本地开发时把 request 的域名改成了本机 IP结果真机调试直接失败——微信要求 request 的域名必须在后台白名单里。后来我统一用了一台云服务器上的域名本地联调就走不校验合法域名的调试模式。这个配置在开发者工具的详情-本地设置里勾选不校验合法域名本地开发体验会顺畅很多但上线前一定要记得用真实域名。4.2 安全细节校园服务涉及的敏感信息主要是用户手机号、学号以及用户上传的照片。有几个安全点我特别做了处理第一手机号和学号在接口返回时做脱敏。比如手机号只返回前三位和后四位中间打码。用户信息接口也用 DTO 而不是直接返回实体避免把 openid、create_time 这些字段暴露出去。第二接口层的参数校验。所有接收前端参数的类都加 NotNull、NotBlank 这类校验注解统一用 Valid 触发。我踩过坑某个发布接口没做非空校验前端传空的 title 也能发出去结果列表页渲染时因为字段为空直接白屏。这种问题定位起来比写校验麻烦十倍。第三防止恶意请求。发布类接口要做频率限制我用了 Redis 的 INCR 命令加过期时间实现了一个简单的计数器同一个用户一分钟内最多发布 5 条。不用 Spring AOP 或者注解那么复杂直接在 service 里几行代码搞定。5. 常见问题与排查技巧5.1 登录态与 token 相关问题问题一真机调试能登录但过一会请求全部 401。这个大概率是 JWT 过期时间设置太短或者服务端和客户端的时间不一致。我用的是相对过期时间签发时加 7 天不受系统时间影响但要注意服务器时间如果和实际时间差太多也会导致判断错误。问题二wx.login 拿到的 code 只能使用一次用完即失效。联调时如果后端报invalid code先检查是不是同一个 code 被重复调用了。我在调试时遇到过一次原因是前端在请求封装层自动重放请求重放时又把原来的登录请求发了一遍第二次用同一个 code 自然就失败了。解决办法是在请求重放逻辑里排除登录接口本身。问题三搞清楚 openid 和 unionid 的区别。openid 是用户在小程序维度的唯一标识同一个用户在同一个小程序下 openid 固定不变但同一个用户在不同小程序下 openid 不同。如果要做跨小程序的数据打通要用 unionid需要用户在小程序后台绑定开放平台账号。校园场景一般不需要知道差别就行。5.2 图片上传与存储问题最常见的就是图片上传成功但无法显示。排查思路先用浏览器直接访问返回的 URL看能不能打开。打不开就看路径如果返回的是相对路径小程序端要拼接域名如果是绝对路径但访问 404检查文件是否真的存在、路径是否包含日期目录。还有一个坑上传大图超时。小程序端 wx.uploadFile 默认超时时间 60 秒但服务器的 nginx 也有超时设置如果图片太大、服务器带宽又小可能 nginx 先超时了。解决方法是限制图片大小比如前端压缩到 2MB 以内后端也做大小校验。我用的是前端压缩加后端限制 5MB 双保险。图片存储位置我当时直接存在了服务器本地磁盘简单够用。但要注意Docker 部署时要把上传目录挂载到宿主机用 volume 映射否则容器重建后图片全部丢失。这个坑我亲眼见过有同事的项目没挂载目录重启容器后用户上传的头像全没了。5.3 其他高频问题跨域问题SpringBoot 后端要配置 CORS允许小程序域名和本地开发地址访问。特别注意 allowedOriginPatterns 不要用*最好精确配置。我之前用*放过几天后来发现某些浏览器对裸通配符支持不好还容易带来安全隐患。时间差 8 小时如果接口返回的时间比实际时间晚 8 小时是时区问题。MySQL 连接串加上 serverTimezoneAsia/ShanghaiJava 端统一用 LocalDateTime基本不会出错。白屏问题小程序首次加载白屏很多时候是分包没配置好或者请求超时。首屏不要放太多接口我做了接口聚合首页一次请求返回所有板块数据减少多次网络往返。写在最后前面说的都是这个项目里比较具体的实现和踩坑记录。我个人最大的体会是像校园综合服务这种听起来范围很大的系统真正落地时靠的不是什么高深技术而是把每个模块的边界划清楚、把数据模型设计合理、把基础能力登录、请求封装、图片上传做扎实。技术选型上保守一点没关系稳定和可维护才是学生用户日常使用中真正在乎的东西。另外一个建议是如果在做类似的项目先把失物招领这种功能闭环做完整发布、浏览、联系、标记完成再横向扩展其他模块。一个完整跑通的小功能比十个半成品页面有价值得多。等到核心链路稳定了再考虑像是消息推送、积分系统这些加分项。最后分享一个小技巧小程序上线前一定要用体验版在校园里找几个真实用户用一周。你会发现很多在开发者工具里发现不了的问题——比如部分安卓机型日期显示异常、低端机列表滚动卡顿、某个人多时段接口响应变慢。这些反馈改起来都不难但能提前暴露就别等到正式上线后被学生在群里吐槽。
