今年接了个校园服务平台的项目用 SpringBoot Java 做后端从需求梳理到部署上线差不多奔走了两个月。做这类系统的人不少但大多停留在能跑就行的层面真正把设计逻辑讲清楚的少。这篇就把我自己的完整过程写出来——为什么这么选型、表怎么设计、接口怎么落、上线踩了哪些坑一条线讲透适合正在做类似校园系统的学生朋友也适合刚入行 SpringBoot 想找个完整项目练手的人。1. 项目定位先从校园里的真实痛点反推系统边界很多同学做校园系统一上来就列功能清单今天想到一个加一个最后做成一个大杂烩。我这个项目的第一周完全没写代码一直在做件事情搞清楚校园里到底有什么需求值得用系统解决。1.1 校园信息需求的特殊性校园是个很典型的高密度小社会几万人挤在一个园区里信息流动却极其低效。失物招领靠公告栏和表白墙二手交易靠QQ群聊天记录教室借用在各个学院秘书处之间来回找人勤工俭学岗位信息散落在一堆微信群里。这些场景有几个共同特点第一信息时效性极强。一张学生卡丢在食堂早晨发的消息晚上还没被看到可能就别想找回来了。第二信任半径明确。交易、互助基本发生在校园内部圈子用户身份天然可信不需要像闲鱼那样做复杂的芝麻信用体系。第三人群结构稳定。账号体系、院系班级关系都是现成的导入数据很容易。第四低频但有刚需。单个功能也许一天只有几百次访问但整体加起来校园日常运转确实离不开。所以这个平台的核心价值不是做社交而是把分散在QQ群、公告栏、微信群里的高频刚需信息集中到一处做标准化流转。失物招领、二手集市、校园活动报名、教室预约、勤工助学、校内通知这六块是当时从调研里筛出来的MVP核心功能。1.2 单体架构是我拍板决策的首要方向团队里有人提过要不要上微服务说以后扩展方便。我直接否了。做技术选型最忌讳的就是拿着锤子看什么都是钉子。一个峰值并发可能只有几百的校园平台用微服务纯粹自找麻烦。单体应用在这个场景下有三个压倒性优势一是开发效率一个人或者两三个人协作单体模式下业务之间的调用就是函数级别的不需要搞远程通信和链路追踪二是部署成本一个jar包丢到服务器上就行微服务光配置注册中心、网关、配置中心就要多搭好几个组件三是数据一致性校园系统里有很多跨模块事务比如发帖同时要更新用户积分、报名同时要扣减名额单体下用一个数据库事务就能解决拆开之后反而要引入分布式事务复杂度立刻翻倍。1.3 功能清单先做减法再做加法最终MVP只保留了六个模块用户体系学生、教职工、管理员三种角色支持学号/工号认证登录。失物招领发布、认领、匹配、完成闭环。二手集市发布闲置、浏览、留言、线下成交。校园活动活动发布、在线报名、名额管理。教室报修提交工单、流转处理、完结评价。通知公告分类发布、定向推送。砍掉的有论坛闲聊、交友匹配、线上支付这类听起来很美的功能。原因很简单线上支付要资质交友匹配有合规风险闲聊论坛需要大量人工运营。做项目要有边界感一个系统能深度解决六个问题已经比浅尝辄止挂二十个功能有价值得多。2. 技术选型与工程骨架为什么是SpringBoot 2.7 JDK 8 这个看似过时的组合技术栈选定为 Java SpringBoot MyBatis-Plus MySQL Redis Vue这在校园项目里非常主流。但有个决定我特别想解释一下就是版本问题——现在SpringBoot 3都出了为什么反而用2.7搭配JDK 82.1 关于版本选择的真实考量SpringBoot 3.x 基线是JDK 17很多老项目里的依赖要跟着升级兼容成本很高。校园系统通常还要对接学校的统一身份认证、一卡通接口这些老系统用的技术栈非常保守提供的SDK往往还是JDK 8时代的产物。我们实测过一个学校提供的CAS认证库在JDK 17下直接编译报错逼着你改源码或者换实现方案纯属浪费时间。SpringBoot 2.7 是目前2.x系列的最终版本意味着它已经过完全部维护期内的功能更新bug修复到位社区里踩坑资料也最全。出了任何问题搜索引擎一查基本都有现成答案。这个红利对于写毕业设计或者中小型项目的人来说比那点性能提升实在得多。另一个重要理由是MyBatis-Plus。这个框架在校园系统、后台管理类项目里太好用了内置通用Mapper、分页插件、代码生成器配合SpringBoot 2.7的自动配置机制几乎不用写XML就能完成90%的单表操作。3.x环境下虽然也能用但总有些版本兼容的暗坑比如2.x版本里的page插件在3.x下要手动注册很多人搞到半夜都定位不到原因。2.2 项目分层与目录规划工程结构我用了最标准的四层分包外加两个公共模块。src/main/java下先按业务域划分顶层包auth、user、lost、market、activity、repair、notice每个业务包内部再按controller、service、mapper、entity展开。这样分的好处是按业务域组织代码找文件时直觉就能定位。新手容易犯的毛病是先按技术分包建个controller包把所有控制层堆一起时间长了控制层几百个类挤在一起想改个失物招领的接口要翻半天。common包里放的是全局统一响应体、统一异常处理、基础工具类。这几乎是SpringBoot项目的命根子。public class ResultT implements Serializable { private Integer code; private String message; private T data; public static T ResultT ok(T data) { ResultT r new Result(); r.code 200; r.message success; r.data data; return r; } public static T ResultT fail(Integer code, String message) { ResultT r new Result(); r.code code; r.message message; return r; } }所有接口统一返回这个结构前端处理数据时不需要每写一个接口就猜一次返回格式。全局异常处理器里捕获业务异常、参数校验异常、未知异常保证任何情况下前端拿到的都是结构化JSON而不是一堆堆栈信息。2.3 依赖清单里不该省的那几个starterpom.xml里的核心依赖除了基础的spring-boot-starter-web和starter-validation有几个是踩过坑后确定必须保留的mybatis-plus-boot-starter单表CRUD零SQL分页一条语句搞定。spring-boot-starter-data-redistoken存储、热点数据缓存、接口防刷必须依赖。jjwtJWT生成与解析0.9.1版本最后兼容JDK8。hutool虽然是工具包但它的加密、日期、文件处理能力帮我省了大量重复代码。knife4j国产的API文档增强包比原生Swagger好看更重要的是支持Token调试联调效率提升明显。有人会问为什么不用Spring Data JPA在校园平台这类以查询为主、检索条件复杂的系统里JPA的自动SQL生成会让排查问题难度加倍你需要时刻关心它到底生成了什么语句。MyBatis-Plus则非常直白SQL都以XML或者注解形式摆在明面上出了问题一眼能看到。3. 数据模型设计用这几张表撑起整个业务流程数据库设计我前后改了四版第一版上来就想抽象一个通用内容模型把所有帖子、失物、商品全塞进一张表结果后期业务扩展时字段越来越臃肿。第二版彻底摊开了按业务建表虽然表多但每张都职责清晰。做用户端项目宁可表多一点也不要追求过度抽象。3.1 用户、角色、权限三张基础表的设计逻辑用户表design上尽量对齐学校的数据结构。CREATE TABLE user ( id BIGINT PRIMARY KEY AUTO_INCREMENT COMMENT 主键, userId VARCHAR(32) NOT NULL COMMENT 学号/工号, password VARCHAR(64) NOT NULL COMMENT BCrypt加密密码, realName VARCHAR(32) DEFAULT NULL COMMENT 真实姓名, nickName VARCHAR(32) DEFAULT NULL COMMENT 昵称, type TINYINT NOT NULL DEFAULT 1 COMMENT 1学生 2教职工 3管理员, college VARCHAR(64) DEFAULT NULL COMMENT 所属学院, className VARCHAR(64) DEFAULT NULL COMMENT 专业班级, phone VARCHAR(16) DEFAULT NULL COMMENT 手机号, avatar VARCHAR(255) DEFAULT NULL COMMENT 头像URL, status TINYINT NOT NULL DEFAULT 1 COMMENT 1正常 0禁用, createTime DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP, updateTime DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP ) ENGINEInnoDB DEFAULT CHARSETutf8mb4 COMMENT用户表;注意几个细节密码字段要存BCrypt哈希绝对不能明文逻辑删除用status字段而不是物理删除保留历史数据对后续审计和统计都有价值userId这里用的是业务工号而不是数据库自增id因为登录时用户输入学号索引要建立在业务编号上。角色权限我只做了type字段加简单RBAC没有引入完整五表权限模型。因为校园平台的角色就那么几种权限差异也不细过重的权限模型会拖慢开发进度。管理员操作记录单独建了一张表到时候真有纠纷可以追溯。3.2 内容域帖子、物品、图片的分工合作失物招领和二手集市都是内容平台底层表结构有共性。我设计了一张内容主表和一张图片表统一承载。表记录的是某件事——丢了东西、捡到东西、出售商品。必要的核心字段包括content_id主键type1失物、2招领、3二手classify二级分类如电子产品、书籍、证件等title标题description详细描述location地点contact_way联系方式imgUrlsJSON数组存储图片路径status状态回见后面的状态机publisher_id发布者IDview_count浏览量冗余字段图片路径用JSON字符串存避免为图片单独建大对象表、然后又要写一堆连表查询。需要拼URL时前端直接从JSON里读就可以。图片本身走本地上传目录生产环境可以用对象存储替换但接口抽象上保持一致。3.3 业务域工单系统与状态机的设计报修工单是最能体现系统设计水平的一块。工单从提交到完结状态变化是线性的非常适合用状态机约束。我定义了五个状态public enum RepairStatus { WAIT_ACCEPT(0, 待接单), PROCESSING(1, 处理中), PENDING_VERIFY(2, 待验收), FINISHED(3, 已完结), CANCELED(4, 已取消); }状态流转用一张配置表维护避免service里到处嵌套if-else判断。当前状态允许操作目标状态待接单接单处理中待接单用户取消已取消处理中申请验收待验收处理中用户取消已取消待验收用户确认已完结已完结重新打开待接单业务代码里用一个校验方法保证所有状态变更都走合法路径非法流转直接抛业务异常。这块不能省否则后期状态就乱了。3.4 互动域评论、点赞、收藏的三张辅助表这三张表结构高度相似但我不建议合并成一张互动表。因为查询维度完全不同——评论要按内容一次性拉出点赞要统计数量加查重收藏要查询用户收藏列表。物理分离后每条查询路径都很清晰索引设计也简单。每个互动表都必须加一个唯一索引防止重复操作比如点赞表加unique(content_id, user_id)。这个索引既能保证业务正确性又能在重复点击时直接查出重复数据让接口走幂等返回避免高并发下的脏数据。4. 核心接口落地认证、发帖流程和各种状态流转的实操目录分层确定后就开始写接口。这里不讲那些谁都会的简单CRUD重点讲几个容易出问题、又影响整个项目质量的关键点。4.1 登录认证JWT Redis的双层校验校园平台登录方案我选了JWT搭配Redis缓存而不是单纯的JWT无状态方案。原因很简单遇到用户被禁用、修改密码、强制下线这类场景纯JWT没办法立刻让token失效。实现思路用户登录成功后生成JWT写入Rediskey为固定前缀加userIdvalue为token并设置过期时间。JWT本身设置一个较长的有效期比如2小时Redis里的有效期略短比如1小时每次请求通过拦截器检查时先看Redis里这个用户的token和当前请求带的token是否一致一致就顺延续期。这样用户连续操作不会突然掉线长时间不操作又能自动退出。Override public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception { // 放行登录、注册、验证码等白名单接口 if (request.getRequestURI().contains(/auth/)) { return true; } String token request.getHeader(Authorization); if (token null) { return reject(response, 未携带登录凭证); } try { Claims claims JwtUtil.parseToken(token); String userId claims.get(userId, String.class); String redisToken stringRedisTemplate.opsForValue().get(login:token: userId); if (!token.equals(redisToken)) { return reject(response, 登录已过期请重新登录); } request.setAttribute(userId, userId); stringRedisTemplate.expire(login:token: userId, 1, TimeUnit.HOURS); return true; } catch (Exception e) { return reject(response, 非法Token); } }这个设计还有个额外好处管理员把某个用户Redis里的token删掉该用户就被强制下线了处理违规账号特别方便不需要等token自然过期。注意Redis和JWT不要全部放在一个key里不同业务模块的缓存分开特别是token缓存和应用业务缓存必须隔离否则一个FlushDB就全员掉线。4.2 发帖与图片上传MultipartFile到URL的完整链路图片上传是论坛类项目的第一道坎。处理流程是前端通过element-upload组件携带token上传文件后端接收MultipartFile校验文件大小和类型生成存储文件名写入本地静态目录返回访问URL。存储文件名不能直接用原始文件名原因有二一是安全防止路径穿越和非法后缀二是避免同名文件覆盖。我用UUID加扩展名重新拼String originalFilename file.getOriginalFilename(); String ext originalFilename.substring(originalFilename.lastIndexOf(.)); String fileName UUID.randomUUID().toString().replace(-, ) ext; File targetFile new File(uploadDir, fileName); file.transferTo(targetFile); String url /upload/ fileName;这里有个必须处理的问题上传目录和Spring Boot的静态资源映射要打通。在application.yml里配置spring: servlet: multipart: max-file-size: 10MB max-request-size: 50MB resources: static-locations: classpath:/static/,file:${file.upload-dir} file: upload-dir: /data/upload/spring.resources.static-locations的配置要把classpath和file路径都加上否则如果你同时还需要classpath下的静态资源比如后面讲的Vue打包文件就会直接被file路径遮蔽掉。这个组合配置我在不少项目里见过踩坑尤其把Vue的dist文件丢到resources下之后如果漏了classpath路径入口页面直接404。4.3 业务状态机失物招领的寻获—匹配—领取闭环失物招领的流程比普通帖子复杂因为涉及双方交互。整个生命周期发布丢失/拾取 → 认领申请 → 审核匹配 → 线下交接 → 完成。在这个流程里有个最常见的并发问题——同一件失物被多人同时申请认领。设计逻辑上先到先得但如果在service里用先查询再更新的写法并发请求下会重复派发。解决方式就用数据库行锁Transactional public Long applyClaim(Long lostId, Long userId) { // 悲观锁锁定记录直到事务结束 LostItem item lostItemMapper.selectByIdForUpdate(lostId); if (item null) { throw new BusinessException(失物信息不存在); } if (item.getStatus() ! LostStatus.WAIT_CLAIM) { throw new BusinessException(该物品已有认领流程进行中); } if (Objects.equals(item.getPublisherId(), userId)) { throw new BusinessException(不能认领自己发布的失物); } item.setStatus(LostStatus.CLAIMING); item.setClaimerId(userId); lostItemMapper.updateById(item); return item.getId(); }selectByIdForUpdate对应的SQL是SELECT * FROM lost_item WHERE id #{id} FOR UPDATE事务提交后锁自动释放第二个请求进来时看到的状态已经是CLAIMING直接抛出业务异常。这个方案理解成本低、实现简洁在校园平台这种并发量下完全够用。顺便提一下如果能接受丢弃不严重的请求也可以在前端用Redis分布式锁做同一用户重复点击拦截但作为兜底方案数据库行锁是最可靠的。4.4 权限控制一个自定义注解解决90%的接口拦截校园平台虽然角色少但接口权限还是分层的普通用户能操作自己的发帖和申请管理员能处理工单和发布公告超级管理员能管理用户。我用了自定义注解加AOP的方式比在Controller里逐个写if判断干净很多。Target({ElementType.METHOD, ElementType.TYPE}) Retention(RetentionPolicy.RUNTIME) public interface RequireRole { int[] value() default {}; }然后写个AOP切面Aspect Component public class RoleAspect { Before(annotation(requireRole)) public void checkRole(JoinPoint joinPoint, RequireRole requireRole) throws Throwable { RequestAttributes attributes RequestContextHolder.getRequestAttributes(); HttpServletRequest request ((ServletRequestAttributes) attributes).getRequest(); int userType (int) request.getAttribute(userType); int[] roles requireRole.value(); boolean passed Arrays.stream(roles).anyMatch(r - r userType); if (!passed) { throw new BusinessException(403, 权限不足); } } }Controller上直接标注可读性极高RequireRole({1, 2}) GetMapping(/my/posts) public ResultListPostVO myPosts() { return Result.ok(...); } RequireRole({3}) PostMapping(/repair/accept) public ResultVoid accept(RequestParam Long orderId) { return Result.ok(...); }对整个项目而言这种做法让权限逻辑显式化新成员接手代码时翻注解就能理解接口权限设计不需要在几百个Controller方法里来回找授权逻辑。5. 部署上线Vue打包进SpringBoot的全过程记录前后端分离开发阶段前端跑在8080端口后端跑在8081端口跨域问题靠CORS配置解决。但上线部署时我选择把Vue的构建产物直接丢进SpringBoot一个jar启动全部服务。这样运维成本最低也不用在服务器上额外架设Nginx。5.1 前端打包放进去前的关键配置Vue项目使用打包命令构建后默认输出一个dist目录。后端要把这个目录复制到SpringBoot的src/main/resources/static下注意必须是static而不是public或者其他目录因为SpringBoot默认静态资源目录是classpath:/static/。唯一要处理的坑是前端路由模式。如果Vue用了history模式打包成静态文件后刷新某个子路由页面比如/admin/users时后端找不到对应的Controller会返回404。解决方法有两个要么前端改成hash模式要么后端加一个路径转发器把所有非api路径请求转发到index.html。我推荐hash模式改动最小一个配置搞定const router new VueRouter({ mode: hash, // 上线部署时用hash routes });如果非要用history模式就要在后端写一个Controller兜底把所有没有匹配到的非接口路径转发到index.htmlController public class ForwardController { RequestMapping(value {/{path:[^\\.]*}, /{path:^(?!api$).*}/**/{path2:[^\\.]*}}) public String forward() { return forward:/index.html; } }这个正则要写好不然会误伤静态资源请求图片、js、css全被转发到index.html页面就彻底白屏了。选hash模式是给多数人的稳妥建议。5.2 生产环境的配置分离开发时项目里配置的是本机地址上线前我把application.yml改成多环境结构application.yml公共配置application-dev.yml开发环境application-prod.yml生产环境prod环境里的数据库密码、Redis密码不写入文件用环境变量注入这样配置文件即使泄露也不会导致敏感信息暴露。启动命令java -jar campus-platform.jar \ --spring.profiles.activeprod \ --MYSQL_HOST127.0.0.1 \ --MYSQL_PASSWORDxxxxSpringBoot的YAML里可以用占位符${MYSQL_PASSWORD}引用系统环境变量。这种方式比直接改配置文件省心因为换了服务器只要重新设置环境变量jar包本身不动。5.3 服务器部署的运维笔记服务器配置不用高2核4G完全能扛住校园平台初期流量。部署时我用生产服务器软件比如用systemd守护Java进程保证崩溃自动重启并设置软链接最后配置完使用screen或者关闭窗口时用nohup模式启动进程防止SSH断开导致服务中断。生产启动时还有一个关键参数要设java -Xms512m -Xmx1024m -jar campus-platform.jar不设置最大堆内存的话JVM默认取物理内存的四分之一4G内存的机器被数据库和Redis分走后可能不足导致频繁FullGC。设置后能稳一点。数据库和Redis装在同一台机器时要限制它们的内存占用特别要防Redis的缓存无限增长设置maxmemory策略是必须的否则内存溢出让整个服务器卡死。6. 实际测试结果与复盘里最有价值的几个坑系统上线试运行一个月整体平稳但也出现了几类典型问题。这些问题的排查过程我觉得比项目本身更值得分享。6.1 并发场景下的手慢无问题校园活动报名上线第一天就出了事故。某个热门讲座开放50个名额开放瞬间进来300个请求使用count查询剩余名额加update扣减的方案结果报名人数超过50。原因很简单多个线程同时读到剩余名额是50都通过了校验然后一起执行update把总数打到了80多。修复方案是前面提到的数据库行锁把查剩余和扣名额放进同一个事务用SELECT FOR UPDATE锁住活动记录再更新。实测1000并发下不再超卖。类似问题也发生在二手商品预定、教室借用的时间冲突校验上统一改成行锁或者乐观锁机制解决。这里要提醒的是update语句里最好带上条件防止覆盖UPDATE activity SET remain remain - 1 WHERE id #{id} AND remain 0这条语句本身就是乐观锁思路哪怕业务层判断失误数据库层也能兜底拦住超卖。6.2 上传图片目录的权限和路径问题试运行期间出现过一个诡异的现象开发环境图片显示正常生产环境上传成功但访问图片返回404。排查了很久最后发现是生产服务器上传目录的权限问题——Java进程没有写那个目录的权限。上传用的目录/data/upload是root创建的Java进程以普通用户运行虽然transferTo方法没报错因为先写到临时目录再剪切但最终文件根本没落地到目标位置。这个问题非常隐蔽一直要到浏览器访问的时候才发现图片不存在。后续改成在上传接口里增加目录权限检查和创建逻辑File dir new File(uploadDir); if (!dir.exists()) { dir.mkdirs(); } if (!dir.canWrite()) { throw new BusinessException(上传目录不可写请检查服务器权限); }启动时把目录owner直接交给Java进程用户省去一堆权限麻烦。6.3 事务失效的经典案例this调用代码评审时抓出一个典型的Spring事务失效问题。在ReportService里有个方法内部调用了另一个带Transactional的方法但调用方式是this.otherMethod()这样自己调用自己事务注解完全不生效。原因是Spring的事务通过AOP动态代理实现代理对象才有开启事务的能力而this调用直接走目标对象本身绕过了代理。修复方式有两种把需要事务的方法拆分到另一个Service类通过注入调用。自行获取代理对象再调用。第一种最推荐不仅解决了事务失效问题职责也更清晰。这属于Spring Boot实践里特别容易踩、但一踩就很隐蔽的坑。6.4 慢SQL排查一次深夜修复试运行期间某些页面打开要三四秒初步怀疑是网络问题。查看SQL日志后发现某个查询教室报修列表的接口关联了五张表查询条件里还有两个函数运算DATE_FORMAT(create_time,%Y-%m-%d)和IFNULL(contact_way,)全表扫描的情况下慢得吓人。优化方案相当直白去掉SELECT里的函数运算把格式化交给前端处理。在create_time、status等查询条件列上建立联合索引。把必填条件从查询所有关联表改成先主表分页再逐行补全关联信息。优化后接口从3秒降到200毫秒以内。这个案例再次印证一个道理慢SQL优化始终要遵循最朴素的数据库优化原则——先减扫描行数再减关联表数量最后才是换服务器。总结整个项目走下来最深的体会就是做技术选型和做需求一样要敢于做减法。SpringBoot Java这套组合确实不算新潮但它在校园系统这个场景下的稳定性、开发效率、运维成本决定了它就是最合适的方案。项目上线后每天稳定处理失物招领、二手交易、活动报名这些实际校园需求这就是技术方案最好的验收。如果正准备做类似项目我的建议是不要一上来就盯着代码写页面先在纸上把用户角色、核心流程、数据状态变化理清楚数据库表和状态机设计好了后面的Controller和Service基本就是体力活。另一个建议是上线前一定要做并发测试。校园系统虽然整体流量不大但活动报名、抢课这类场景的瞬时流量非常集中不做并发控制生产环境出问题往往就是最尴尬的那一次。最后再分享一个小技巧开发过程中给每个接口都加上统一响应结构日志里把请求路径、参数、耗时全打出来。校园系统涉及多个角色和状态变更出了问题对着日志链路走一遍比在代码里瞎猜快十倍。这套方法不仅适用于SpringBoot项目任何一个Java后端项目都值得沿用。