不到一百万用户的体量真不需要动不动就上微服务。做Java后端这些年我接触最多的源码项目就是“基于SpringBoot的小型社交网络平台”课程设计、毕业设计、个人练手十个Java初学者里有八九个都绕不开它。大部分项目功能长得差不多注册登录、发动态、关注取关、点赞评论、私信通知。真正把差距拉开的不是功能多少而是源码结构和部署文档能不能让别人照着就能跑起来。这篇文章我就以这个项目为样例把需求拆分、技术选型、源码结构、核心链路、部署文档、代码讲解这六块完整过一遍希望你能少走点弯路。1. 需求先行先搞清楚“小社交”到底该做什么1.1 别上来就建表先把功能边界钉死我见过太多人拿到题目就开写结果半个月后表关系乱了、接口对不上、前端页面也没法串起来。小型社交平台最大的坑不是复杂而是“什么都想做”。动手前花半天把需求边界定死后面省下的时间绝对不止半天。所谓“小型”意味着不需要推荐算法、不需要复杂好友链更不需要实时音视频。典型的功能边界长这样用户系统注册、登录、退出、修改资料、头像上传、密码修改这是地基。内容系统发布动态纯文本或带图、删除自己的动态、动态列表、动态详情。互动系统点赞、取消点赞、发表评论、删除评论这是社交感的主要来源。关系系统关注、取关、粉丝列表、关注列表决定信息流的内容来源。消息系统被点赞、评论、关注后的站内通知点开能看到“谁赞了我”。附加项按用户ID查主页、热门动态列表、关键词搜索能加则加不影响主线就别硬加。这里有个很重要的经验单机部署的小项目做“实时聊天”的成本非常高。很多队伍选了WebSocket做点对点聊天做着做着发现离线消息、历史记录、已读未读全都要处理最后做成一团浆糊。小型平台完全可以用“通知评论”代替聊天把核心链路跑通比堆积功能靠谱得多。1.2 技术选型的取舍以及为什么选它选型不需要花哨但你要能解释“为什么不用另一个”。我用的是这套组合Spring Boot 3.x JDK 17。当前主流版本资料好查很多新特性跟着用就行。MySQL 8.0 MyBatis-Plus。单表CRUD占大头MP的分页和条件构造器确实省事。Redis。存登录态、验证码、点赞计数、关注缓存基本是每套项目标配。WebSocket。做站内通知推送小项目自己写连接管理就够了不需要上MQ。JWT。无状态登录认证配合拦截器使用。为什么不用Spring Cloud单机部署根本用不上强行上只是给自己增加调试成本。为什么不用MongoDB动态数据量不大时MySQL的查询灵活性和事务能力反而更好团队里会MySQL的人也更多。为什么不用原生MyBatis小型项目大部分是单表操作用MyBatis-Plus能少写一半重复代码。注意Spring Boot 3.x 对第三方组件的兼容要求比较严格。MyBatis-Plus 必须使用mybatis-plus-spring-boot3-starter这个依赖坐标老版的mybatis-plus-boot-starter装上去启动直接报找不到类。这个坑几乎每个照着旧教程配置的人都会踩一次。2. 源码结构拆解项目该怎么组织别人才能看懂2.1 包结构设计与分层原则一套能讲得清楚的好源码包结构一定是“一看就知道去哪改代码”的。我推荐“分层为主、模块为辅”的混搭结构com.example.social ├── SocialApplication.java // 启动类 ├── config // 配置类 │ ├── CorsConfig.java // 跨域配置 │ ├── WebMvcConfig.java // 拦截器注册 │ ├── MybatisPlusConfig.java // 分页插件 │ └── WebSocketConfig.java // WebSocket 配置 ├── controller // 接口入口 │ ├── AuthController.java // 注册/登录 │ ├── UserController.java // 用户信息 │ ├── PostController.java // 动态 │ ├── FollowController.java // 关注 │ ├── LikeController.java // 点赞 │ └── MessageController.java // 通知 ├── service // 业务层 │ ├── UserService.java │ └── impl / UserServiceImpl.java ├── mapper // 数据访问 ├── entity // 数据库实体 ├── dto // 入参对象 ├── vo // 出参对象 ├── common // 统一返回、异常、常量 ├── security // JWT拦截器、工具类 └── utils // 上传、时间处理等这里有个容易被忽略的点dto和vo一定要分开。很多人图省事直接用entity作为接口入参和出参结果数据库字段暴露给前端不说后面改表结构还要连带改接口。小型项目哪怕多写两个类后面写部署文档、做代码讲解的时候会舒服很多。2.2 核心模块的职责边界用户模块controller只做参数接收和调用serviceservice处理注册逻辑、密码加密、token签发mapper就是最基本的insert和selectById。密码必须用BCryptPasswordEncoder加密绝对不要明文存储。注册接口要处理“用户名重复”这类业务异常给前端返回明确的中文提示而不是直接抛500。动态模块发动态要处理文字校验、图片上传、落库三件事。这里有一个隐藏的边界问题图片上传和数据库写入不一定在同一个事务里。我的做法是先传图拿到文件路径再insert记录如果insert失败要清理刚传的文件或者通过定时任务扫上传目录清孤儿文件。关注模块核心是一张关注关系表字段就id、user_id、follow_user_id三个加上联合唯一索引。关注和取关都要先查一遍关系再操作避免重复关注。计数方面可以先更新数据库再删除Redis里的缓存让下次请求重建缓存。注意不要先删缓存再写DB并发情况下很容易把脏数据写回缓存。消息模块一张通知表搞定字段包括类型1点赞、2评论、3关注、触发人、被通知人、关联动态ID、已读标记。实时推送用WebSocket未读数量存数据库字段在线状态可以维护在应用内存或Redis里。小项目不需要把通知拆成多个表一张表足够。2.3 拿到一套陌生源码应该按什么路径读我经常遇到学员说“源码发你了帮我看看怎么跑”然后发来一整个压缩包。拿到陌生项目我建议按这条路径走启动类 - 配置文件 - 拦截器 - 一个完整接口 - 一个完整业务链路。很多人喜欢从entity开始看一个表一个表地啃看半天基本是机械记忆。先看启动类能知道项目引入了哪些模块组件再看application.yml能知道中间件地址、端口、文件路径等关键配置然后挑一个登录接口从controller到service到mapper完整走一遍。这条链路走通这个项目的编码风格、分层习惯、异常处理方式你就拿捏了七成。3. 核心业务链路讲解从登录到发一条动态3.1 登录鉴权与JWT拦截器的完整链路新手最常问的问题就是“登录之后怎么知道是谁发的动态”。用JWT答案很简单用户登录成功后后端签发一个token里面带上用户id和过期时间。前端后续请求在请求头里带Authorization: Bearer token后端写一个拦截器统一解析token把用户id存入ThreadLocal业务层就能随时拿到“当前登录人”。登录接口的完整逻辑是接收用户名和密码 - 检查验证码如果有- 按用户名查询用户 - BCrypt检查密码 - 生成token - 返回用户基础信息加token。这里要强调查询用户时不能只查密码还要查状态字段如果账号被禁用应该在业务层就拦住而不是等到业务进行到一半才发现没权限。拦截器写得不好是重灾区。我总结过三个必踩的坑登录接口、注册接口、验证码接口、WebSocket握手地址必须放行不留白名单的话整个系统连登录都进不去。跨域OPTIONS预检请求要直接放行否则前端联调时请求卡在拦截器控制台报CORS错误。JWT解析失败要返回401而不是让异常一路抛到全局异常处理器变成500否则前端不知道是“没登录”还是“系统崩了”。3.2 发布动态的事务边界与文件上传发动态接口的重点不在insert那一行而在“怎样才算一个完整发布流程”。一个标准的流程如下参数校验。动态内容不能为空长度限制在500字以内图片最多9张。处理图片。检查扩展名和文件大小按时间戳加随机数重命名保存到本地磁盘或云存储。写入动态表。动态内容、图片URL列表、发布人id、发布时间一并落库。清理缓存。如果有首页动态缓存发布成功后要删除否则用户刷新半天看不到自己的新动态。事务要包住的是第3步操作第2步文件系统操作不推荐放进事务里。原因很简单数据库回滚不会让磁盘上的文件消失事务回滚后留下孤儿文件后面清理起来很麻烦。更稳的做法是图片上传成功后如果数据库写入失败代码里捕获异常并删除已上传文件再兜底一个定时任务定期清掉上传目录里超过一定时间且没有对应数据库记录的文件。上传大小也要配置好尤其是前后端分离的项目spring: servlet: multipart: max-file-size: 10MB max-request-size: 20MBMaxRequestSize要大于MaxFileSize因为一个请求可能带多张图片。很多人改了配置文件还是传不了大文件十有八九是只改了单文件大小限制没改请求总大小限制。3.3 关注、粉丝与Feed流先想清楚查库还是用缓存小型社交平台最常见的动态列表做法就是查库。展示某个人主页时先查post表 where user_id ? 分页展示“我关注的动态”时先查follow表拿到关注用户id列表再查post表 where user_id in (?) 分页。这套逻辑在几千、几万用户时完全没压力。但如果你想让动态流更像真正的社交产品可以用Redis的zset做一份轻量Feed流。思路是发动态时除了写post表同时往自己的zset里写一条动态IDscore是时间戳。别人访问你的主页时直接从zset按分数倒序取出动态ID再回表查详情。这样好处是主页加载很快也避免用户动态多之后连接查询拖慢速度。这里有个必须处理的细节动态删除时要同步删除自己zset里的ID否则会出现列表里有点进详情却提示“动态不存在”的尴尬。定时任务可以把这种残留问题兜底处理但更严谨的做法是在删除动态的方法里直接删zset记录。至于要不要把“关注列表动态”也做进Redis我个人建议小型项目先不要。数据量没到十万级查库完全够用。提前上推模式或者复杂的推拉结合开发周期拉长维护成本翻倍还不一定带来可见的效果提升。3.4 点赞和评论的并发注意点点赞接口最怕的是重复点赞和计数不对。我的做法是点赞表建联合唯一索引user_id post_id然后直接insert用try-catch捕获DuplicateKeyException捕获到就说明重复点赞返回友好提示。这样比先select再insert更稳也少一次数据库往返。点赞计数不建议每次查count可以在post表冗余一个like_count字段。点赞时数据库update like_count like_count 1取消时减1。小型项目这个操作不会成为瓶颈还能避免Redis和数据库计数长时间不一致的问题。如果担心并发数值错误可以给post表对应行加行锁也就是select for update后再update但小型项目通常不需要走那么重。评论相对简单一张comment表字段是post_id、user_id、content、parent_id。parent_id支持楼中楼不需要也能先留着。需要注意两点一是前端传进来的内容一定要做HTML转义或者富文本过滤防XSS二是删除动态时要记得级联删除评论否则前端会出现动态没了、评论列表还挂着几条脏数据。4. 部署文档怎么写出“照着就能跑起来”的步骤4.1 环境准备与版本对齐部署文档写不好项目基本等于白做。我见过太多人只写“环境要求JDK8 MySQL5.7”结果项目是SpringBoot 3写的拿着JDK8的环境一顿操作启动直接报错。版本对齐是部署文档的第一要务。推荐环境如下组件推荐版本说明JDK17SpringBoot 3.x 必须17及以上Maven3.8构建工具MySQL8.0字符集建议 utf8mb4Redis6.x缓存与Feed流Node.js可选16前端项目构建需要如果你的SpringBoot是2.xJDK8或11就行是3.x就别再用JDK8硬扛直接会报UnsupportedClassVersionError。这种低级错误一定要防。4.2 配置文件逐项解释部署文档里不应该甩一个application.yml就完事最好把每个关键项都解释一遍。比如一份典型的配置长这样server: port: 8080 spring: datasource: url: jdbc:mysql://localhost:3306/social_platform?useSSLfalseserverTimezoneAsia/ShanghaicharacterEncodingutf8 username: root password: yourpassword driver-class-name: com.mysql.cj.jdbc.Driver redis: host: localhost port: 6379 database: 0 password: yourredispassword # 没有密码就留空 servlet: multipart: max-file-size: 10MB max-request-size: 20MB jackson: date-format: yyyy-MM-dd HH:mm:ss time-zone: Asia/Shanghai mybatis-plus: configuration: log-impl: org.apache.ibatis.logging.stdout.StdOutImpl # 生产环境删掉 global-config: db-config: logic-delete-field: deleted logic-delete-value: 1 logic-not-delete-value: 0 jwt: secret: your-very-long-secret-key expire-hours: 24 file: upload-dir: /data/upload access-path: /upload/**几个关键点单独说明jwt的secret如果太短解析token时会直接抛异常数据库url不配serverTimezone写入的时间会和本地时间差8小时生产环境记得把MyBatis-Plus的StdOutImpl日志去掉否则每条SQL都会打印出来既吃性能又不安全file.upload-dir一定要是一个绝对路径而且要确保进程有写入权限。4.3 数据库初始化脚本部署文档要附带一份可以直接导入的sql文件。不用写几百条insert数据但表结构必须全。第一行就要指定库和字符集CREATE DATABASE IF NOT EXISTS social_platform DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci; USE social_platform;后面的建表语句所有字符串字段都明确字符集。这样不管是在Navicat里导入还是在命令行执行都不会出乱码。除了表结构我习惯把初始化管理员账号写进去。账号密码不要用明文直接写死一个BCrypt加密后的hash值并注释说明默认密码是什么。4.4 构建打包与启动命令部署文档里给出最稳的构建命令mvn clean package -DskipTests java -jar target/social-platform-1.0.0.jar --spring.profiles.activeprod想让它后台跑先别一上来就上systemd先用nohup最简单nohup java -jar target/social-platform-1.0.0.jar \ --spring.profiles.activeprod \ --server.port8080 \ logs/app.log 21 启动后立刻跟踪日志tail -f logs/app.log | grep -E Started|ERROR|Exception出现Started SocialApplication in x.x seconds才算真正跑起来。这个检查习惯要养成新手看到终端卡住就以为挂了其实SpringBoot可能还在初始化中间件连接。4.5 单机部署与Docker Compose选一条主线如果读者是纯新手优先讲单机部署因为一次引入Docker反而容易把注意力带到容器概念上。但生产环境我更推荐Docker Compose一条命令把MySQL、Redis、应用全拉起来。用Compose要注意三点应用容器和数据库容器要共享同一个自定义网络数据库数据和上传文件目录要挂载到宿主机密码不要写死在镜像里用环境变量传入。我见过一个经典的翻车现场数据库容器没挂volume跑了一周的数据说没就没。这不是开玩笑部署文档里一定要写清楚。另外一个容易被忽略的点前端打包后的静态文件可以直接往SpringBoot的static目录里塞SpringBoot也能老老实实当个静态服务器但生产环境我建议用Nginx托管前端后端只保留/api和/upload两个入口。这样动静分离清晰后端压力小Nginx反向代理配置也简单。无论单机还是Docker上传目录都要单独挂出来。用Docker没挂volume容器一重建用户头像全没了。这种错误一旦上线损失非常难弥补。5. 代码讲解从“会写”变成“会讲”5.1 讲代码时最容易忽略的三件事代码讲解的目标是让别人快速读懂不是照着代码逐行念。我给别人讲项目习惯先画一条“请求数据流”浏览器点按钮 - 前端发ajax - controller接收 - service校验业务 - mapper操作数据库 - 结果逐层返回。把这条链路讲清楚对方就有了骨架之后再填充细节吸收效率翻倍。第二件不能省的事是“异常流”。很多人讲代码只讲正常路径不讲参数不对怎么办、重复请求怎么办、权限不够怎么办。比如登录接口正常流程一行带过但“用户名不存在”“密码错误”“账号被禁用”这三个分支在哪处理一定要单独讲。能讲清楚异常流的讲解才是值钱的讲解。第三一定要用真实数据演示。单测也好、Postman也好跑一个真实注册、登录、发动态、点赞的流程让对方看到数据在表里变化比对着代码空讲有用一百倍。5.2 典型讲解范例关注接口以关注接口为例我的讲解顺序通常是入口FollowController里的follow方法入参是被关注用户id当前用户id从ThreadLocal取。业务校验不能关注自己目标用户必须存在不能重复关注。核心逻辑insert关注关系更新粉丝数和关注数。缓存处理删掉当前用户关注列表缓存、目标用户粉丝列表缓存。消息通知给被关注人写一条type3的通知通过WebSocket推过去。返回统一Result。重点讲第4步。这不是花活是真实痛点“关注后立刻刷新列表新数据就是不出现”多半是缓存没清干净。5.3 把整套源码串成一门“三讲小课”我给学生或同事讲这套项目一般串成三讲第一讲登录注册和JWT拦截器理解整个项目的认证骨架第二讲动态发布、图片上传理解事务和文件的边界第三讲关注、点赞、Feed流理解缓存和关系表的数据走向。每讲配一个小图和两个Postman测试用例。这套讲法对新手特别友好因为每一讲都有一条完整主线而不是零散知识点拼凑。6. 常见问题与排查技巧实录6.1 启动与编译阶段的问题速查现象可能原因解决思路启动报端口被占用8080被其他进程占用Windows用netstat -ano | findstr 8080Linux用lsof -i:8080换端口或杀进程找不到MyBatis-Plus相关类依赖坐标不兼容SpringBoot3必须用mybatis-plus-spring-boot3-starter数据库连接失败报Communications link failureMySQL没启动、账号密码错、端口不通先telnet 127.0.0.1 3306测连通性再检查url和驱动时间字段差8小时JDBC连接没配serverTimezoneurl加serverTimezoneAsia/ShanghaiRedis连接失败Redis没启动、requirepass没配置redis-cli -a 密码 ping返回PONG即可打包后jar包特别大依赖全打进去了这是正常的SpringBoot fat jar就是这么大6.2 运行与接口阶段的高频问题跨域是最常见的线上问题之一。典型现象是浏览器控制台报CORS错误但Postman里接口完全正常。原因基本是后端没允许前端地址。解决思路是写一个CorsConfig全局配置AllowedOriginPatterns里填具体域名比如http://localhost:5173不要用通配符加allowCredentials(true)的组合那样会被浏览器直接拦掉。JWT相关的坑也很经典token过期后前端要能拿到401并跳转登录页而不是看到白屏拦截器解析token要区分“过期”和“无效”两种状态返回不同文案方便定位问题secret一旦发布出去就不要改一改所有已登录用户全部强制下线必要操作也要提前公告。6.3 线上“本地正常、服务器不行”的通用排查法这个问题我答过不下十遍通用顺序是先看进程在不在再看端口通不通再查日志最后看文件配置。很多人一上来就改代码改完再部署纯属浪费时间。服务器和本地差异最大的地方是路径上传目录/data/upload不存在、日志目录没有写权限、Nginx没配置静态资源映射导致图片404。这些都不是代码逻辑问题而是环境差异。6.4 三招写出像样的部署文档第一招标题顺序固定为“环境准备-配置文件-数据库-构建启动-常见问题”每一步都给命令和预期输出。第二招把所有可变项数据库密码、Redis密码、上传路径、端口号集中放在一个“部署前需要修改的位置”表格里别让读者在一堆代码里自己猜。第三招自己部署三遍每遍都从零开始。我每次写完部署文档都会拿一台干净虚拟机从头走流程经常能发现漏了给上传目录加权限或者忘记建logs目录这种细节。这套项目做到这里骨架已经完整。后面的扩展方向也很多把本地文件存储换成云存储、给动态加内容审核、用消息队列解耦通知推送、做关注Feed流的推拉结合每一块都能单独写一篇。不过这些都得建立在一个前提下——先把当前这套源码跑稳、讲透。我自己带人做项目的习惯是拿到任何一套SpringBoot源码第一件事永远是补部署文档、画核心调用链然后才去读业务代码。这个习惯建议所有准备毕业设计答辩或者写简历项目的人认真用起来。