1. 项目概述与整体定位社区医疗服务系统这类项目说白了就是给基层卫生服务中心做的一套业务管理系统。相比大型医院的HIS系统它的业务边界更聚焦挂号预约、门诊记录、慢性病随访、药品库存、体检档案核心是让社区医生用一套Web系统把日常门诊和健康管理跑起来。我这次做的这套系统技术栈选的是SpringBoot2 Vue3 MyBatis-Plus MySQL8.0前后端分离架构源码和文档齐全正好可以拿来作为毕业设计、课设作品或者中小型诊所信息化的基础版本二次开发。先说下选这套技术栈的原因。SpringBoot2到今天依然是Java Web领域最稳妥的选择生态成熟排错资料多MyBatis-Plus把单表CRUD和分页的重复劳动省掉了大半开发效率提升非常明显MySQL8.0是当前主流版本性能和数据安全机制都比5.7有改善。前端用Vue3的组合式API配合Element Plus或者自研组件都能快速出页面。整套组合的成本很低——一台2核4G的云服务器就能跑起来对高校实训环境或者小型卫生站来说非常友好。这套系统适合谁来参考如果你是刚学完SpringBoot和Vue3、想找完整项目练手的同学这份源码能让你少走很多弯路——因为里面包含了真实业务场景的所有典型坑JWT过期处理、跨域配置、MyBatis-Plus分页插件注册、MySQL8.0时区问题等这些都是教科书里不会细写的。如果你是想做社区医疗信息化改造的技术负责人这套系统的模块划分也可以拿来直接做需求采编的底稿。我在实际部署和二次开发这套系统的过程中踩过不少坑也总结出了一些自己的经验。这篇文章会把整体架构、核心模块实现、关键配置、常见问题排查全部拆开讲一遍每部分都会附上我实际操作后的结论和替换方案希望对你有实际帮助。2. 系统架构设计与技术选型思路2.1 前后端分离的整体拓扑这套系统的部署结构很标准前端Vue3项目打包后由Nginx托管静态资源后端SpringBoot打成Jar包独立运行二者通过HTTP接口通信接口统一走/api前缀。数据库只用了一个MySQL实例没有引入Redis和消息队列——社区医疗场景下并发量通常不高一台服务器承载几十个医生工作站完全够用引入额外中间件反而增加运维负担。前后端分离带来的最大好处是开发和部署可以各自独立。开发阶段前端用Vite代理解决跨域后端专心处理业务生产阶段Nginx统一入口接口地址通过location /api反向代理到后端服务的8080端口就不存在浏览器跨域问题了。这里有个细节如果你直接把前端打包后的静态文件扔进SpringBoot的static目录也能跑但后续前端更新就得重新打包整个Jar不推荐这么干。2.2 后端分层与包结构规划后端包结构我按常见的四层模型拆分但做了一点调整。controller层负责参数接收和结果封装service层写业务逻辑mapper层通过MyBatis-Plus的BaseMapper继承通用CRUDentity层放数据库映射实体。额外增加了一个common包统一放返回结果封装类、异常处理器、JWT工具类、全局常量。这样做的目的是保证代码边界清晰后续加功能时知道往哪儿放代码——比如新增一个体检报告导出功能流程就是entity建表、mapper写SQL、service写业务、controller暴露接口非常顺。实体类上的注解需要注意一个小点MyBatis-Plus的TableId如果数据库主键是自增的类型要写成IdType.AUTO如果是雪花ID则用IdType.ASSIGN_ID。我在文档里曾经看到有人把这两种混用导致插入数据时主键冲突或者雪花ID插成了字符串。自己写代码时最好统一约定避免后期排查半天。2.3 Vue3前端项目组织方式前端部分用的是Vue3 Vite Vue Router Pinia没有引入TypeScript——因为社区医疗这类管理系统页面以表单和列表为主类型约束带来的收益远不如开发速度重要。路由采用了动态权限思路登录后根据用户角色管理员、医生、护士、患者动态生成可访问的路由表。这个设计在文档里是作为亮点写的实现逻辑也值得细看。状态管理用Pinia存两类数据一是用户信息和Token二是侧边栏折叠状态这类全局UI状态。这里我建议不要把接口请求数据一股脑塞进Store——页面刷新后数据就没了而且容易造成响应式追踪的额外开销。接口数据在组件内用ref管理跨页面共享的数据才放Store这是我在多个项目里总结出的经验。2.4 数据库设计与角色权限模型数据库设计这套系统一共11张表核心表包括用户表、角色表、权限表、患者信息表、医生排班表、预约挂号表、门诊记录表、药品表、处方明细表、体检记录表。角色权限是经典的RBAC模型三张表用户-角色-权限加两张关联表。有一个实际设计上的坑想提醒你社区医疗系统里患者和用户最好不要拆成两张表然后做关联——很多患者根本没有登录账号全是医生在后台帮忙建档。把患者身份字段直接放在用户表里比如user_type标识是患者还是医生用status字段区分已建档和已注册会简化大量逻辑。我在文档的数据库设计说明里见到的是拆分为独立表的做法这在讲解RBAC时更清晰但若你准备在真实诊所部署建议按我说的合并方案改造能少写很多联表查询。3. 后端核心功能实现与业务逻辑拆解3.1 基于SpringSecurity JWT的认证鉴权认证这块选的是SpringSecurity整合JWT而不是简单的拦截器加Token。原因很直接社区医疗系统里存在接口级别的权限控制需求比如医生只能查询自己名下的门诊记录护士只能修改体检数据管理员才能操作用户管理。SpringSecurity的注解式鉴权PreAuthorize可以方法级别控制比自己在拦截器里写死逻辑灵活得多。具体的认证流程是用户提交用户名密码后端校验通过后生成JWT把用户ID和角色信息放进去返回给前端前端每次请求在Header里带Authorization: Bearer token后端有一个JwtAuthenticationFilter继承OncePerRequestFilter每次请求解析Token并放入SecurityContext。这里有个非常容易踩的坑Token过期后前端拿到的还是过期Token接口返回401但前端路由守卫只判断了本地有没有Token没有校验是否过期结果就是用户明明退出不了每次点刷新都跳到登录页。我建议前端在拿到401时统一做一次集中跳转处理而不是在每一个请求里单独写。3.2 预约挂号模块的状态流转设计预约挂号是社区医疗系统的核心业务我把状态机设计成了四个状态待就诊、已就诊、已取消、已过期。为什么不用简单的未就诊/已就诊两个状态因为在真实场景下患者挂了号当天没来系统要能自动把号源释放掉这就需要已过期状态来标识。同时医生可以手动取消预约也需要独立状态区分是谁取消的。具体实现上预约记录表里存了appointment_time、status、cancel_reason三个关键字段。自动释放号源的逻辑用Spring的Scheduled定时任务每天凌晨扫描前一天状态为待就诊的预约记录统一置为已过期同时把对应医生的号源数量加回去。这个定时任务我在最初版本里写成了每分钟扫一次发现数据量小的时候纯属浪费数据库IO后来改成每天凌晨跑一次配合前端展示规则——超过预约日期当天未就诊的就显示已失效。社区医院的患者预约量一天很少超过几千条这种批处理策略完全够用。3.3 门诊记录与电子处方读写医生看完病要开处方这个模块涉及两张表的写入门诊记录表和处方明细表。事务管理是这里的重点——如果门诊记录写成功了但处方明细写失败那么医生就会看到一条没有用药信息的门诊记录患者端也会出现已就诊但无处方的尴尬情况。所以保存处方的Service方法上一定要加Transactional注解并且我建议指定rollbackFor Exception.class否则遇到非运行时异常比如IOException事务不会自动回滚。药品库存的扣减逻辑也值得说一下。我的做法是在生成处方时只校验库存是否足够不实际扣减真正扣减发生在药房发药环节。这样设计的好处是避免医生开单时误扣库存导致其他患者拿不到药也符合真实药房的操作流程——先审方后发药。如果你一上来就把扣库存写在保存处方的地方后期加一个退药功能时就会很痛苦。3.4 文件上传与体检报告管理体检报告模块涉及Excel导入和图片上传两个点。Excel导入用的是POI每次解析模板后把数据批量插入体检表。这里有一个我反复提醒过自己的点批量插入必须用MyBatis-Plus的saveBatch方法不要循环里一个一个save——一百条数据前者一条SQL搞定后者要跑一百次SQL慢出几个数量级。图片上传我存储在本地磁盘指定目录不存数据库BLOB字段。数据库里只记录URL路径。这个方案的缺点是后续迁移服务器时要同步迁移文件目录但优点是查询性能好、备份方便、前端可以直接用静态URL访问。如果不想自己维护文件目录后续可以替换成对象存储服务接口层只需要改上传和回显两个方法业务层完全不用动。4. 前端核心页面与交互实现解析4.1 后台管理布局与路由守卫前端整体布局用的经典结构左侧菜单、顶部导航栏、右侧内容区。菜单数据是根据当前用户角色从后端动态拉取的后端返回的是一棵菜单树结构前端拿到后动态渲染el-menu。这样做的好处是权限调整时只需改数据库记录不需要重新发布前端。路由守卫这块用了Vue Router的beforeEach全局前置守卫。首次进入时判断本地有没有Token——没有就跳转登录页有Token但没拿到用户信息时先去后端拉用户信息和菜单数据然后next()放行。这里有个容易犯错的地方动态路由必须用router.addRoute()在守卫内注册如果静态路由表里写死了所有页面那动态权限就形同虚设。我在文档里看过不少示例用本地路由前置判断方式代替后端动态路由那种做法权限逻辑分散在前端代码里安全性差很多。4.2 表单校验与日期组件的高频场景社区医疗系统的表单密集度非常高挂号要选医生、选号源时间建档要填身份证号、手机号开处方要搜药品、填用量。Vue3中我用el-form的rules加上自定义validator做了统一的校验方案。这里强烈建议把身份证号校验、手机号校验这种通用规则提取成公共模块而不是在每个页面重复写——我在第一版就是把身份证校验散落在四五个页面里后来因为逻辑更新新版身份证号规则调整要逐个页面改非常痛苦。日期选择组件用el-date-picker有两个经验想分享一是设置disabled-date属性把过去的时间禁掉避免患者约到已经过去的时间段二是医生排班页面的日期格式精确到天即可用value-formatyyyy-MM-dd存储不要存带时分秒的完整时间否则联表查询和分组统计时还得用DATE_FORMAT做一次转换。4.3 Axios请求封装与错误提示规范前端接口统一封装在request.js里基于Axios实例化。请求拦截器在Header里挂Token响应拦截器先处理业务状态码——后端返回结构是统一的{ code, message, data }code为200时走成功逻辑其他code弹ElMessage提示错误信息。401状态统一跳转登录页并清空本地Token。关于错误提示规范我踩过一个实际的坑后端参数校验失败的message直接抛出SQL异常前端把英文错误堆栈展示给了用户体验极差。后来在后端加了统一异常处理器RestControllerAdvice把参数校验、业务异常、系统异常分别映射成友好的中文提示。前端只管展示message字段。这个属于联调规范问题但直接影响系统的专业感建议在项目初期就定好。4.4 数据展示与统计报表实现首页数据看板需要展示今日预约量、门诊量、药品库存预警、慢性病随访人数四个核心指标。统计接口写在后端的StatisticsController里通过Mapper注解SQL统计当日数据。前端用ECharts渲染折线图和饼图——折线图展示近7天门诊量趋势饼图展示疾病分类占比。做统计报表有个性能方面的坑要提醒不要在统计SQL里嵌套太多子查询。我第一次实现门诊量趋势时按日期分组查了7次每次单独查一天数量接口响应时间到了800毫秒。后来改成一条SQL用DATE_FORMAT(create_time, %Y-%m-%d)分组统计7天数据一次查出全部结果响应时间降到50毫秒。数据量不大时看似无所谓但统计接口经常被前端轮询调用累积起来对后端压力还是明显的。5. 关键配置与常见问题排查实录5.1 MyBatis-Plus分页与自动填充配置MyBatis-Plus的PaginationInnerInterceptor是必须配置的否则调用selectPage方法时只执行了查询全部数据然后在内存分页——数据量超过万条时会拖垮内存。配置方式是在MyBatisConfig里注册MybatisPlusInterceptor添加分页和乐观锁两个内置插件。createTime和updateTime两个字段我配置了自动填充实体上标注TableField(fill FieldFill.INSERT)然后在配置类里实现MetaObjectHandler插入和更新时自动写入当前时间。这个方案的坑在于——如果你手动给这两个字段赋值自动填充不会覆盖默认只在为空时填充但多表更新时可能会出现时间不一致。我的建议是倾向于把时间字段的逻辑放在CreateTime属性上统一维护业务代码里完全不要手动去set这两个字段。5.2 MySQL8.0连接配置与常见连接异常MySQL8.0和5.x在驱动和连接URL上有明显区别。驱动类不再用com.mysql.jdbc.Driver而是com.mysql.cj.jdbc.DriverURL里必须显式配置serverTimezoneAsia/Shanghai否则会报The server time zone valueÖйú±ê׼ʱ¼ä这种时区错误。还有个容易忽视的是useSSLfalse参数——8.0默认开启SSL握手本地开发环境没有配置证书时会连接超时加上这个参数可以跳过SSL认证。连接池用的是HikariCPSpringBoot2默认内置我踩过的一个坑是连接池连接空闲超时后数据库端主动断开服务端没有及时感知导致下一个请求拿到一个失效连接。解决方案是把connection-test-query设置为SELECT 1并且把空闲超时时间配成比数据库的wait_timeout小一些这样连接池会定期校验连接有效性。5.3 前端跨域与Nginx反向代理配置开发阶段跨域问题用Vite的proxy解决server: { proxy: { /api: { target: http://localhost:8080, changeOrigin: true } } }这个配置的效果是前端请求/api/user/list时Vite开发服务器把请求转发到后端的8080端口浏览器看到的请求源是同源的自然不存在跨域限制。但注意changeOrigin: true必须设置否则转发后请求头里的Origin还是前端域名后端做CORS判断时可能还是会被拦截。生产环境用Nginx配置location /api/ { proxy_pass http://127.0.0.1:8080; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; }有一个比较隐蔽的问题如果proxy_pass后面带了路径比如http://127.0.0.1:8080/斜杠会导致请求路径被替换——前端请求/api/user/list会被转发为/user/list而后端Controller映射的是/api/user/list就会出现404。我的做法是proxy_pass不带斜杠让完整路径透传下去后端统一在RequestMapping(/api)前缀下开发两边的路径对得很齐。5.4 数据库初始化与文档的一致性校验这套系统包含一份SQL初始化脚本建库建表加初始管理员账号。我在实际部署时发现一个普遍问题——MySQL8.0的utf8mb4字符集和排序规则如果不在建库时指定默认可能用utf8mb4_0900_ai_ci部分老版本的数据迁移脚本用的还是utf8mb4_general_ci会导致导入报错。建议在脚本开头显式指定CREATE DATABASE IF NOT EXISTS community_medical DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;另外文档里写的字段类型和SQL脚本可能出现不一致——比如文档把身份证号标注为varchar(20)但实际人员信息表里却是varchar(18)。这种不一致在二次开发时很容易埋雷。我的经验是拿到项目后先跑一遍全部SQL脚本再用可视化工具核对每张表的字段和文档中的ER图列一遍差异清单能省掉后面大量排查时间。6. 常见问题速查与二次开发避坑指南6.1 部署运行阶段的高频问题速查表我把这套系统从拉取源码到最终跑起来的过程中遇到的高频问题整理成了速查表方便直接对照现象可能原因解决方案启动报Failed to configure a DataSource配置文件里没写数据库连接信息或写错了库名检查application.yml中的url、username、password前端页面空白Vue路由mode为history但Nginx未做try_files配置Nginx加try_files $uri $uri/ /index.html;登录接口报500数据库密码加密方式不兼容在MySQL里执行ALTER USER rootlocalhost IDENTIFIED WITH mysql_native_password BY 密码;查询数据库乱码连接URL没加characterEncodingutf8在jdbc url中追加characterEncodingutf8上传图片后访问403文件目录Nginx没授权访问Nginx增加location /upload/ { alias /path/to/upload/; }定时任务不执行主启动类没加EnableScheduling注解在入口类上增加该注解6.2 二次开发时最容易忽略的三个点第一个是接口鉴权遗漏。新写一个Controller时如果忘记加PreAuthorize注解而这个接口又没在Security配置里排除放行那么它会要求登录但允许任何登录用户访问——这是很危险的比如患者信息修改接口如果没加仅本人或管理员的限制普通护士登录后就能随便改。建议在Controller类上统一加类级权限注解方法级再精确收口。第二个是前端重复请求。表单页面在保存成功后往往有刷新列表的逻辑但保存按钮如果没做防重复提交处理用户连续点两次就会插入两条重复数据。我在保存方法里用一个loading状态控制按钮禁用请求结束后再恢复这个改动成本很低但能避免大量脏数据。第三个是日志规范。上线后排查问题时没有日志几乎寸步难行。我在这套系统中加了AOP切面统一打印Controller层的入参和出参日志级别设为INFO。生产环境建议把日志文件滚动策略配好按天切分、保留30天否则磁盘被日志堆满的系统我见过不止一次了。6.3 文档阅读与代码对照的方法论这套项目附带的文档写了将近100页包含需求说明、数据库设计、接口文档和部署手册。我的建议是别从头到尾通读而是带着任务去查——动手部署前只看部署手册和环境要求跑起来之后从登录接口开始跟着前端页面操作一步步看后端日志和数据库变化用这种点对点方式理解代码效率最高。接口文档里如果标注了[POST] /api/patient/add去代码里找到PatientController的add方法读一遍Service实现再看Mapper里的SQL等于一条完整的业务链路从头到尾走了一遍。碰到不懂的设计比如某个状态字段的流转再回到数据库设计章节去查重点就自然而然地浮现出来了。7. 一些经验体会与扩展方向我做完这套社区医疗服务系统后的最大体会是业务系统的难点从来不在技术栈本身而在于对领域场景的理解和边界情况的处理。预约状态的流转、药品库存的扣减时机、权限控制的粒度这些才是真正决定系统能不能用的关键。技术选型方面SpringBoot2 Vue3这套组合对中小型管理系统来说属于性价比之王——框架足够稳性能完全够用社区资料遍地都是遇到问题基本搜索十分钟就能解决。有几个值得做的扩展方向供参考。一是给预约挂号模块增加短信通知功能患者预约成功后自动发送提醒这需要对接短信服务商改动核心业务逻辑不大但使用体验提升明显。二是增加体检报告的PDF导出功能社区老年人体检后都很希望有一份纸质报告后端用模板引擎导出可以复用现有数据。三是把药品库存告警接入钉钉或企业微信机器人推送药剂师能第一时间收到补货提醒。这些扩展方向都建立在现有源码上按我前面讲的模块边界去加代码整体成本很低。最后分享一个小技巧拿到这类带文档的系统源码后先把文档里的数据库初始化脚本在本地跑通再用账号进入系统体验一遍所有功能最后对照着代码把每个页面对应的后端接口勾画一遍。这套流程走完你对该系统的熟悉程度不会比原作者差多少——剩下的就交给业务需求去驱动你的二次开发了。