SpringBoot+Vue全栈项目实战：从架构设计到部署上线完整指南

每个人做全栈项目，基本都会经历过这样的阶段：需求看着明白，代码也能写，但一问“前后端怎么配合”“部署到服务器上怎么跑起来”就卡壳。这篇文章我拿一个之前做过的社区医疗服务系统当例子，把从架构设计、核心模块实现到最终部署上线的完整过程拆开讲一遍。这套系统用的是 SpringBoot + Vue + MyBatis + MySQL 的组合，涉及的场景也比较典型：患者预约挂号、医生接诊开方、后台管理药品和公告，几乎覆盖了中小型业务系统的全部常见功能。如果你是正在做毕业设计的学生，或者刚转行想找一个完整项目练手，又或者是在小团队里需要独立交付一套系统的开发者，这篇文章可以当一份参考模板来用。

1. 项目全貌与核心需求拆解

1.1 社区医疗服务系统要解决的现实问题

社区医院和大型三甲医院的信息化需求差别很大。大型医院追求的是高并发、多院区协同、复杂检查检验流程；而社区医院更看重的是轻量、好用、维护成本低。我当初接这个需求时，对方提出的核心痛点有三个：一是患者挂号基本靠现场排队，高峰期混乱；二是医生的诊疗记录和处方全靠纸质，后续统计随访非常困难；三是药品和公告的管理没有统一入口，经常出现信息不一致。

基于这些痛点，系统最终圈定的核心模块就是：患者端的预约挂号与病历查看、医生端的工作台与处方开具、管理端的医生排班、药品管理和资讯发布。权限角色拆成三类：管理员、医生、患者。这套功能看着不复杂，但如果一上来就埋头写代码，大概率会陷入改来改去的泥潭。我的习惯是先画一版简单的角色-功能矩阵，把每个角色的核心操作和页面列清楚。

这个矩阵看起来简单，但它在后续开发里帮了大忙。每次有需求变动，我都会回到这张表问一句：影响哪个角色、改动哪个模块。这个习惯值得养成，尤其是当你一个人要写前端又要写后端的时候，没有清晰边界很容易写着写着就乱了。

1.2 技术选型为什么是这套“老组合”

SpringBoot + Vue + MyBatis + MySQL，放在今天看不算新潮，但它是中小型系统里最稳的组合。先分别说理由：SpringBoot 简化了配置和部署，内嵌 Tomcat 意味着不需要单独装服务器；Vue 的响应式数据绑定让前端页面开发效率高，组件化写法也适合维护；MyBatis 相比 JPA 更灵活，SQL 掌握在开发者手里，排查慢查询、做复杂统计都更直观；MySQL 就不用说了，社区医院的数据量级用它的免费版绰绰有余。

也有人问我，为什么不用微服务？为什么不把 Vue 升级到用 TypeScript 重写？我的回答是：要看项目体量。社区医疗服务系统的用户并发可能就几十人，数据量在百万级以内，这时候上微服务只会增加部署和运维负担。SpringBoot 单体应用配合前后端分离，已经把“扩展性”和“可维护性”平衡得很好了。技术选型不是追新，而是选择最贴合当前问题的方案，这个观点我希望每个做项目的朋友都记住。

2. 架构设计与数据库建模的关键细节

2.1 前后端分离的目录规划与接口约定

前后端分离项目最怕什么？最怕前后端各自为政，接口路径乱、返回格式不统一、联调时互相甩锅。所以项目落地第一步，不是写业务代码，而是把接口规范和目录结构定死。

后端按经典分层来组织：controller 接收请求、service 处理业务逻辑、mapper 负责数据库操作、entity 映射数据表。控制层只做参数接收和结果返回，业务判断全部下沉到 service 层。比如“预约挂号”这个操作，controller 里就是一个方法调用，真正的号源校验、防重复逻辑都在 service 里完成。这样写的直接好处是接口层非常薄，后续如果要做接口测试或者对接小程序，几乎不用改 service。

前端的目录规划同样重要。我习惯把 src 下面拆成 api、views、router、store、utils 几个目录。api 目录下按业务模块建文件，比如 appointment.js、doctor.js、admin.js，每个文件里统一导出接口调用函数；views 按页面放组件；router 做路由管理，配合后端的角色返回做动态路由。这样的结构让新人接手时能快速定位代码，不会出现“找一个接口定义翻遍全项目”的情况。

接口约定方面，我用一个统一的 Result 返回体，结构固定为 code、message、data 三部分。code 为 0 表示成功，非 0 表示业务异常；message 给前端提示语；data 放业务数据。这个约定最大的价值在于，前端的 axios 拦截器可以统一处理异常弹窗和登录失效跳转，不需要每个业务方法都写一套错误处理。

public class Result<T> { private Integer code; private String message; private T data; public static <T> Result<T> success(T data) { Result<T> result = new Result<>(); result.code = 0; result.message = "success"; result.data = data; return result; } public static <T> Result<T> error(String message) { Result<T> result = new Result<>(); result.code = 500; result.message = message; return result; } }

前端 axios 封装里，response 拦截器判断 code，非 0 直接弹出 message，同时识别 401 状态跳转登录页。这样一套约定下来，前后端联调的时候非常省心。

2.2 数据表设计：从需求到建表的完整过程

数据库表设计是这类系统里最见功力的部分。我见过太多项目代码写了一半发现表结构不对，回头改表导致前后端一起返工。所以建表前一定要把数据关系画清楚。

这个系统核心表整理一下大概有这些：用户表（包含患者和医生账户）、患者信息表、医生信息表、科室表、排班表、预约挂号表、病历表、处方表、药品表、公告表。用户表与具体角色表分开设计，目的是后续如果要扩展新角色，不用改动现有认证逻辑。排班表和预约挂号表是重点，排班表记录某医生某天某个时间段的号源总量和剩余量，预约表记录患者到底约了哪一条排班记录。

设计“预约挂号”相关的表时，有一个细节值得特别注意：排班表的字段要包含“排班日期”“时间段编码”“总号源数”“剩余号源数”，预约表则要带上“排班ID”“患者ID”“预约状态”。状态字段建议用 tinyint 存整数，比如 0 表示待就诊、1 表示已完成、2 表示已取消，而不是直接存中文。存整数的好处是查询效率高、占空间小，展示层的转换交给前端或后端枚举处理。

所有业务表都加上 create_time、update_time、deleted 三个字段。deleted 字段用逻辑删除，是因为医院的病历处方数据有审计要求，物理删除了将来查不到就麻烦了。比如一个病历被误删，逻辑删除还能恢复，物理删除就只能靠备份，非常被动。

3. 核心功能模块的实操实现

3.1 JWT登录认证与权限控制

社区医疗系统涉及患者隐私数据，登录认证是绝对不能省的一环。我用的是 JWT 方案，流程不复杂：用户提交用户名密码，后端校验通过后生成一个包含用户ID、角色信息的 token 返回给前端；前端存在 localStorage 里，每次请求通过 axios 拦截器在请求头加上 Authorization 字段；后端通过拦截器解析 token，判断是否有效，取出用户信息放到请求上下文。

实现上有几个细节要处理好。第一，token 要设置合理的过期时间，这里配置的是 12 小时，考虑到医生可能上一天班中途不退出，太短会导致频繁重新登录。第二，拦截器要放行登录接口、注册接口和静态资源，否则用户还没登录就被拦在门外。第三，密码存储必须用 BCrypt 加密，绝对禁止明文。社区医院项目里，我见过有开发者为了省事直接明文存密码的，这是拿用户隐私开玩笑。

@Configuration public class WebConfig implements WebMvcConfigurer { @Override public void addInterceptors(InterceptorRegistry registry) { registry.addInterceptor(new JwtInterceptor()) .addPathPatterns("/api/**") .excludePathPatterns("/api/auth/login", "/api/auth/register"); } }

角色权限的控制，我在拦截器之外加了一个简单的注解校验：自定义一个 @RequireRole 注解，标注在 controller 方法上，写一个切面去校验当前登录用户的角色是否匹配。比如管理员才能调用药品管理的接口，就在方法上加 @RequireRole("ADMIN")。这个做法比引入 Spring Security 全家桶轻量得多，对这类中小型系统够用了。

3.2 患者预约挂号：可用性大于华丽

预约挂号是系统的门面功能，患者第一印象就来自这里。实现上我用了一个被验证过很多次的设计：排班时先由管理员或医生生成一周的排班计划，每个排班覆盖上午和下午两个时间段，每个时间段设定号源数量。患者端看到的是当前有剩余号源的排班，点击“预约”时后端通过事务控制更新剩余号源数并插入预约记录。

这里有几条实战经验特别重要。第一条是防重复预约，同一患者对同一个排班只能预约一次。实现方式是在预约表上建联合唯一索引，字段组合是 patient_id + schedule_id，这一条直接在数据库层面挡住重复请求，比在 Java 代码里判断靠谱多了。第二条是剩余号源的扣减要加条件：update 语句里带where remaining > 0，如果影响行数为 0，说明号源已经被抢完，直接提示患者。这样做可以天然避免超卖，不需要引入 Redis 分布式锁。

UPDATE schedule SET remaining = remaining - 1 WHERE id = #{scheduleId} AND remaining > 0

第三条是状态机的设计。预约状态用一个字段管理：待就诊、已完成、已取消、已过期。每次状态流转都必须在 service 层做校验，不能让前端随意调接口改变状态。比如“已完成”只能由医生在接诊流程中触发，不能给患者开一个“标记完成”的按钮。

3.3 电子病历与开方：事务与扩展性要考虑

电子病历和处方是医生端的核心操作，也是整个系统里业务逻辑最重的部分。一次开方动作涉及的操作包括：更新病历表、插入处方记录、处方药品明细批量插入、如果患者选择在线支付还会涉及订单创建。这些操作必须在一个事务里完成，任何一步失败都要回滚。

SpringBoot 里用 @Transactional 注解可以解决事务问题，但要注意几个坑。第一，事务默认只在运行时异常下回滚，如果你在方法里捕获了异常没往外抛，事务是不会回滚的。所以建议在事务方法里尽量不要自己 try-catch，让异常自然抛出交给全局异常处理器。第二，事务方法不要用 private 修饰，否则 Spring 的代理机制生效不了，注解完全不起作用。第三，数据库表引擎要确认是 InnoDB，MyISAM 不支持事务，这个检查排错时很容易被忽略。

开方界面的药品选择，我建议做出“药品模糊搜索 + 库存校验”的效果。医生输入药品名关键字，前端调用后端搜索接口返回匹配药品列表，并显示当前库存。选中药后填写用量用法。药品库存的扣减一定要在事务里和处方单一起做，否则会出现处方开了但库存不够的尴尬场景。

4. 部署上线的完整流程与加固

4.1 本地环境搭建与项目运行步骤

部署第一步是环境准备。如果你用的版本跟我不同，大概率会遇到一些莫名其妙的问题，所以这里直接给出我验证过的版本组合：JDK 1.8、MySQL 5.7、Node.js 14+、Maven 3.6+。

后端启动步骤：先把项目源码里的 application.yml 改好，重点是数据库连接地址、用户名密码，以及 JWT 的密钥配置。然后在项目根目录执行mvn spring-boot:run，等控制台出现“Started Application”就说明启动成功。为了验证接口是否正常，可以用浏览器直接访问 Swagger 地址，我习惯在项目里集成 springfox 的 Swagger，方便开发阶段调试接口。

前端启动步骤：进入 vue 目录，先执行npm install安装依赖。这一步如果慢，可以把 npm 源切换到国内镜像源。依赖装完执行npm run serve，前端默认跑在 8080 端口。开发环境下前端和后端存在跨域问题，需要在 vue.config.js 里配置 devServer 的 proxy 代理，把/api前缀的请求转发到后端地址。

// vue.config.js module.exports = { devServer: { port: 8080, proxy: { '/api': { target: 'http://localhost:8081', changeOrigin: true } } } }

配置完代理后，前端请求/api/login时，开发服务器会自动转发到http://localhost:8081/api/login，前端代码里完全不需要写死后端地址。

4.2 前后端分离打包与 Nginx 部署

本地开发跑起来只是第一步，把系统部署到服务器才是完整的交付。我用的方案是前端打包成静态文件交给 Nginx 托管，后端打成 jar 包用 Systemd 守护运行。

后端打包执行mvn clean package -DskipTests，生成的 jar 包在 target 目录下。上传到服务器后，建一个专门的服务目录，用java -jar 服务名.jar启动。为了日志管理方便，我把标准输出重定向到 log 文件，启动命令后面加上> application.log 2>&1 &。当然更规范的做法是写一个 Systemd 服务单元，这样开机自启、崩溃重启都能自动处理，但小项目用 nohup 方式也能应付。

前端打包执行npm run build，产物在 dist 目录下。把 dist 里的文件上传到 Nginx 的 html 目录，然后修改 Nginx 配置文件。其中最关键的是 location 规则：/路径指向静态文件，/api路径做反向代理转发给后端的 8081 端口。

server { listen 80; server_name localhost; location / { root /usr/share/nginx/html; index index.html; try_files $uri $uri/ /index.html; } location /api/ { proxy_pass http://127.0.0.1:8081; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; } }

这里try_files那句一定要有。Vue 是单页应用，前端路由切换时 URL 会变化，如果没配置 try_files，用户刷新页面就会报 404。这个坑几乎所有 Vue 部署都会踩一次，记住配置上就不怕了。

4.3 服务器加固与数据库定期备份

部署完成不代表交付完成。系统上线后最重要的两件事：数据备份和安全加固。数据备份我用的是 mysqldump，每天凌晨通过 crontab 定时任务执行备份脚本，备份文件保留最近 7 天。恢复操作也简单，mysql -u用户名 -p密码 数据库名 < 备份文件.sql即可。

安全加固方面，第一步是修改 MySQL 的默认端口和密码策略，禁用 root 远程登录。第二步是配置防火墙，只开放 80 和 22 端口。第三步是后端配置里不要明文写数据库密码，可以通过环境变量注入。第四步是给 JWT 密钥设置一个足够长的随机字符串，避免被暴力猜测。这些操作不复杂，但在实际交付项目时是区分“能用”和“好用”的分水岭。

5. 常见问题与排错实录

开发部署过程中踩的坑，整理成一份速查表，比什么文档都实用。

再分享一个排查技巧：遇到问题先看日志。SpringBoot 运行时的控制台或者 log 文件会打印完整的异常堆栈，大部分问题都能从报错信息直接定位。初学者最容易犯的错就是一上来就乱改代码，改半天发现根本不是这里的问题。建议先把报错信息读完，再配合断点调试，效率会高很多。

6. 一点个人经验体会

这几个月做下来，我对这类业务管理系统的最大体会是：技术本身不是瓶颈，真正考验人的是把需求翻译成系统结构的能力。同样是预约挂号，不同项目的细节千差万别，有的要求支持医保结算，有的要求对接排队叫号大屏，有的要求移动端小程序。如果一开始就把系统的边界和表结构设计得清晰，后面这些需求都是在现有骨架上的追加和扩展，不会推翻重来。

最后再分享一个小技巧：给系统留一个“超级管理员”初始账号。第一次部署时，如果没有管理员账号，你连后台都进不去，还得去数据库手动插入用户记录。我现在习惯在项目启动时做一个数据初始化处理器，检测到用户表为空就自动创建默认的管理员账号，并打印出初始密码。这个细节虽小，但每次交付环境都能省不少事。

如果你正在做类似的系统，我的建议只有一句话：别急着写业务代码，先把接口约定、表结构、目录规划这三件事想明白。这几件事想通了，一万行代码写起来也只是时间问题。