做农家乐管理系统这套东西最早是因为一位做旅游行业的朋友找上我。他们那边几十家农家乐还在用Excel记房态、记订单旺季的时候前台忙得脚不沾地还经常出现一房多订、退房时账目对不上的问题。后来我用 Java SpringBoot Vue3 MyBatis 这套前后端分离方案配合 MySQL 数据库给他做了一整套数字化农家乐管理平台从客房预订、入住登记、餐饮点单到经营结算全部打通。今天不聊虚的就把这套系统的数据库设计、后端接口思路、前端页面联调、部署上线流程以及我实际踩过的坑完整拆一遍。这篇内容适合谁看一种是正在做毕业设计、想找完整全栈项目参考的同学另一种是给农家乐、民宿、小型酒店做数字化升级的开发者。不管你是想自己从零搭一套还是想理解 SpringBoot Vue3 前后端分离项目的完整链路这篇都能给你不少可以直接抄作业的东西。1. 需求拆解农家乐平台到底要管什么1.1 传统农家乐的业务痛点在做这套系统之前我专门去朋友那边蹲了两天观察他们的真实工作流。传统农家乐的管理状态基本是这样的前台一个大本子记着各类房型的预订情况厨房下单靠口头喊或者手写小纸条退房结账的时候要把住宿费、餐饮费、游玩项目费用一笔一笔翻出来核对。这里面最痛的不是累而是乱。房间状态完全靠人脑记忆客户电话预订了国庆的房间前台忘记记录客人到店发现房间被重复订出去了体验直接崩塌。餐饮和住宿分开记账客人退房时账单对不上最后往往是老板自己贴钱息事宁人。还有一点老客户没有沉淀客人走了就失联了回头客只能靠缘分。所以数字化平台要解决的本质上不是把纸质换电子而是把业务流理顺客户在线看房、下单、支付前台实时看到房态变化厨房接到电子订单退房时系统自动汇总账单老板在后台看经营报表。一句话让每一间房、每一笔钱、每一个客人都能被系统追踪到。1.2 功能模块怎么划分基于上面的痛点我把系统拆成了用户端和管理端两大块。用户端面向游客核心功能有注册登录手机号加密码用 JWT 做登录态管理。客房展示与预订按日期查询可订房间看房型图片、价格、设施说明提交预订订单。餐饮菜单浏览查看菜品分类、价格、图片加入购物车后统一提交。个人中心查看自己的订单列表、订单详情、取消未支付的订单、发表评论。公告板查看农家乐发布的优惠活动和园区通知。管理端面向农家乐老板和前台功能更多一些数据看板今日订单量、今日营收、入住率、近一周营收趋势。房型管理增删改查房型设置价格、床位数、面积、描述和图片。房间管理维护具体房间号、所属楼层、房间状态空闲/入住中/打扫中。订单管理查看所有订单确认预订、办理入住、办理退房、取消订单。菜品管理维护菜单上下架菜品调整价格。评论管理查看游客评论回复或删除不当评论。用户管理查看注册用户列表禁用恶意账号。公告管理发布和下线公告。1.3 技术栈选型的逻辑技术栈选择上SpringBoot Vue3 MyBatis MySQL 这套组合放在当下依然是中小型管理系统最稳的方案没有之一。SpringBoot 的优势是起步快、配置少、生态成熟。一个空项目拉起来写两个接口跑通十分钟都不用。对于这种以 CRUD 为主的业务系统SpringBoot 的开箱即用特性特别合适不需要像 Spring 老项目那样写一堆 XML 配置。Vue3 这边组合式 API 写业务逻辑比选项式 API 更顺手配合 Vite 的冷启动速度开发体验很好。再加上 Element Plus 这套组件库后台管理页面的表格、表单、弹窗、日期选择器基本不用自己造轮子。MyBatis 在这个项目里比 JPA 更合适。农家乐系统的报表查询、房态冲突检测、订单分页筛选都是 SQL 极其灵活的查询场景。MyBatis 把 SQL 写在 XML 里可控性最强复杂查询出了问题一眼就能看到是哪段 SQL 写错了。JPA 虽然省事但碰到复杂查询时自动生成的 SQL 往往不是你想要的排查起来反而更费劲。MySQL 就不用多说了中小业务量级下性能、稳定性、运维成本都是最优解。前后端分离则是为了后续扩展比如以后要接小程序端、App 端后端接口可以直接复用不用重新开发。2. 数据库设计整个系统的地基数据库设计是我在这个项目里花时间最多的地方。前期表结构没想清楚后面写代码全是坑。我最终设计了 9 张核心表下面把表结构和几个关键设计思路展开讲。2.1 核心表结构一览用户表 userid、username、password、nickname、phone、avatar、role、status、create_time。role 字段区分管理员和普通用户值取 ADMIN 或 USER不用单独建角色表这个量级的项目用字段枚举就够了。房型表 room_typeid、name、price、bed_count、area、description、image、status。status 控制房型是否对外展示。房间表 roomid、type_id、room_no、floor、status。status 表示房间当前物理状态0 空闲、1 入住中、2 打扫中。订单表 ordersid、order_no、user_id、room_id、check_in_date、check_out_date、total_amount、status、create_time、pay_time。status 取 0 待支付、1 已支付待入住、2 已入住、3 已完成、4 已取消。菜品表 menuid、name、category、price、image、description、status。餐饮订单表 orders_itemid、order_id、menu_id、menu_name、price、quantity。冗余 menu_name 和 price 是为了防止菜品改价或删除后历史订单数据失真。评论表 commentid、user_id、order_id、rating、content、create_time。公告表 noticeid、title、content、create_time、status。游玩项目表 activityid、name、price、description、image、status。2.2 订单表和房间状态的设计思路这个项目里最重要的表就是 orders。我踩过的第一个坑就是最初把房间状态设计成了房间表上的一个字段预订时直接修改状态。后来发现完全行不通因为房间状态必须是有时间维度的同一间房今天空闲、明天被订不能简单用一个状态字段表示。最终方案是房间表只维护物理状态是否在住、是否脏房预订状态完全由订单表根据入住离店日期动态计算。查询某段时间哪些房可订就是找该时间段内没有冲突订单的房间。订单号我用了时间戳加随机数的方式生成格式类似 ORD20250101123045001避免并发下订单号重复。金额计算放在后端前端传过来的价格只做展示。预订的可用性检测 SQL 是整个系统最核心的一段逻辑。要判断某个房间在入住日期和离店日期之间是否已被占用不能只看日期相等还要处理区间重叠判断逻辑是新订单的入住日期小于原订单的离店日期且新订单的离店日期大于原订单的入住日期。这段思路理解了房态查询就通了。2.3 数据库初始化与测试数据的准备项目里我提供了一个 init.sql 脚本包含建表语句和测试数据。测试数据这块有个建议别只插几条意思一下要模拟真实场景不同房型各插几间房、菜品覆盖多个分类、订单横跨过去三个月到未来一个月、评论覆盖不同评分。这样开发前端页面时列表、筛选、分页、图表都有真实数据可以调试不用边开发边造数。初始化数据还有一个作用就是验证 SQL 的性能虽然数据量不大但该建的索引要建好。orders 表的 room_id、check_in_date、check_out_date、status 字段room 表的 type_iduser 表的 username这些都要建索引。预订查询虽然数据量小的时候感受不到差别但真到旺季几千单的时候没有索引的查询会让接口明显变慢。3. 后端实现SpringBoot MyBatis 的关键代码思路3.1 项目分层与包结构设计后端工程我采用了经典的分层结构按技术职责横向划分controller 层接收请求、service 层处理业务、mapper 层操作数据库、entity 放实体类。同时拆出 config、common、dto、util 等辅助包。这种结构最直观团队新人也容易上手。业务逻辑简单的项目不需要按模块垂直拆分否则每个模块里都是同样的 controller、service、mapper反而显得重复。把公共部分抽出来比如统一返回结果类 Result、统一异常处理器 GlobalExceptionHandler、JWT 工具类 JwtUtil放在 common 包里各模块直接调用。统一返回结果这块我封装了一个 Result 类结构是 code、message、data 三段。所有接口统一返回这个格式前端 Axios 响应拦截器里统一处理。这样做的好处是前端不用每个接口单独判断成功失败一次封装到处复用。3.2 JWT 认证与拦截器权限控制登录认证我用了 JWT没有引入 Spring Security。不是 Spring Security 不好而是这个项目的权限模型太简单只有 ADMIN 和 USER 两种角色用拦截器加注解就能搞定引入 Security 反而要写一堆配置。具体实现是登录接口验证用户名密码成功后生成一个 token把用户 ID 和角色塞进 token 的 claims 里返回给前端。前端存储 token每次请求在请求头里带上 Authorization 字段。后端定义一个拦截器拦截所有需要登录的接口解析 token解析失败返回 401。需要管理员权限的接口我在 controller 方法上加了自定义注解 RequireAdmin拦截器里解析 token 中的角色字段不是 ADMIN 就直接拒绝。这样权限控制的粒度合适也容易理解。有个细节要注意token 过期时间我设置的是 24 小时但实际用户可能连续住好几天。如果 token 过期了前端路由守卫会拦截到 401自动跳转登录页但这样体验不好。更好的做法是前端在 Axios 响应拦截器里捕获 401弹出提示然后跳转登录页并保留当前页面路径登录成功后跳回来。这个小体验很多人会忽略但我建议做上。3.3 MyBatis 动态 SQL 处理复杂查询MyBatis 的 XML 里写动态 SQL是这个项目最出效果的部分。拿房态查询举例用户在前端选择入住日期、离店日期、房型、价格范围后端需要组合查询符合条件的房间。如果用 Java 代码拼 SQL条件一多代码就乱套了动态 SQL 就干净很多。下面这段是房态查询的核心 SQL逻辑是房间没被其他订单占用并且满足价格和房型筛选条件select idfindAvailableRooms resultTypecom.example.farmstay.entity.Room SELECT r.*, rt.name AS typeName, rt.price FROM room r LEFT JOIN room_type rt ON r.type_id rt.id WHERE r.status 0 if testtypeId ! null AND r.type_id #{typeId} /if if testminPrice ! null AND rt.price gt; #{minPrice} /if if testmaxPrice ! null AND rt.price lt; #{maxPrice} /if AND r.id NOT IN ( SELECT room_id FROM orders WHERE status IN (1, 2) AND (#{checkIn} lt; check_out_date AND #{checkOut} gt; check_in_date) ) /select这里有个特别容易被新人踩的坑XML 里小于号要写成lt;大于号要写成gt;。我第一次写的时候直接在 SQL 里写了启动报错找了半天才反应过来是 XML 转义的问题。3.4 订单状态流转的 Service 层实现订单状态流转是这个项目业务逻辑的核心。我的实现方式是在 OrderService 里定义了 cancelOrder、checkIn、checkOut 三个方法每个方法都先校验当前状态是否符合流转条件再更新状态和对应时间字段。举个例子cancelOrder 只允许取消状态为待支付或已支付的订单并且要判断入住日期距离当前时间是否大于 24 小时否则不能取消。checkIn 要求订单状态必须是已支付同时要更新房间状态为入住中。checkOut 要求订单状态是入住中计算实际入住天数更新订单总金额把房间状态改为打扫中。这套状态机放在 service 层统一管理比散落在 controller 里好维护太多。每个方法开头先查订单、校验状态、执行更新逻辑清晰也不容易出现状态错乱。4. 前端实现Vue3 界面与联调细节4.1 前端工程结构与路由设计前端用的 Vite Vue3 Pinia Vue Router Element Plus Axios 这套组合。工程结构按页面模块划分views 下面分 user 端页面和 admin 端页面components 放复用组件api 下面按业务模块放接口请求文件router 放路由配置store 放 Pinia 状态。路由设计上我把页面分成三类公开页面登录、注册、首页、客房列表、菜单展示、需要登录的页面个人中心、订单提交、我的订单、需要管理员权限的页面后台所有管理页面。通过路由守卫实现权限控制核心逻辑是判断 token 是否存在再判断目标路由的 meta 里有没有 requireAdmin 属性有的话还要从 Pinia 里拿用户角色如果角色不是 ADMIN 就重定向到首页。这套方案不复杂但很实用。4.2 Axios 封装与跨域处理Axios 封装几乎是每个 Vue 项目都绕不开的环节。我在 api 目录下建了一个 request.js做统一配置import axios from axios const request axios.create({ baseURL: /api, timeout: 10000 }) request.interceptors.request.use(config { const token localStorage.getItem(token) if (token) { config.headers.Authorization Bearer ${token} } return config }) request.interceptors.response.use( response { const res response.data if (res.code ! 200) { if (res.code 401) { localStorage.removeItem(token) router.push(/login) } return Promise.reject(new Error(res.message)) } return res.data }, error { return Promise.reject(error) } )baseURL 设成 /api开发环境通过 Vite 代理转发到后端生产环境通过 Nginx 反向代理转发。这样前端代码里不用写死后端地址环境切换非常方便。开发环境的跨域问题在 vite.config.js 里配置代理就行这是开发联调时最常用的解法。4.3 核心页面实现要点前台首页的房态预订页是这个系统的流量入口。我用了一个日历组件让用户选择入住和离店日期选完日期后调用房态查询接口返回可订房间列表。这里前端做了一个细节日期选择器禁止选择今天之前的日期并且离店日期必须晚于入住日期用 Element Plus 的 disabledDate 回调就可以实现。房型卡片上展示房型图片、名称、床位数、面积、价格点击预订按钮跳转到订单确认页。订单确认页展示了入住天数、单价、总价用户确认后提交订单生成待支付订单然后跳转到订单列表页面。餐饮点单页我实现了类似购物车的交互左侧菜品分类右侧菜品列表点击加号添加到购物车右上角显示购物车数量和总价。提交后生成餐饮订单关联到当前用户。管理端的订单管理页面是最复杂的页面。用了 Element Plus 的 el-table 展示订单列表状态列用 el-tag 做不同颜色的标签操作列根据订单状态动态显示可用按钮。比如待支付订单显示取消订单按钮已支付订单显示办理入住已入住订单显示办理退房。这样运营人员不用记状态流转规则系统告诉你能点什么。5. 部署上线全流程实录系统开发完下一步就是部署上线。前后端分离项目的部署比单体项目多几个环节很多人卡在这一步我把我实际操作过的一套流程完整写下来。5.1 环境准备与版本选型部署环境我建议用一台 Linux 服务器2核4G 配置就够跑这个系统。下面是版本选型的参考JDK 1.8 以上建议直接用 JDK 11使用更稳定Maven 3.6 以上用于后端打包MySQL 5.7 或 8.0推荐 MySQL 8.0字符集默认 utf8mb4更好的中文支持Node.js 16 以上用于前端构建Nginx 1.20 以上用于部署前端静态文件和反向代理后端接口这里有个容易踩的坑MySQL 8.0 连接串时区问题比较典型必须加上 serverTimezoneAsia/Shanghai否则连接报错。后端数据库连接配置示例spring: datasource: url: jdbc:mysql://127.0.0.1:3306/farmstay?useSSLfalseserverTimezoneAsia/ShanghaicharacterEncodingutf8mb4 username: root password: your_password driver-class-name: com.mysql.cj.jdbc.Driver5.2 数据库导入与后端启动数据库初始化这块把项目里的 init.sql 复制到服务器上执行 mysql 命令导入。导入完成后用 Navicat 或命令行验证一下表结构和测试数据是否正常。后端打包用 Maven命令是mvn clean package -DskipTests打包完成后在 target 目录下会生成一个 jar 包用 java -jar 直接启动程序。我建议用 systemd 或 nohup 方式守护进程避免终端退出后服务挂掉。nohup java -jar farmstay-server.jar --server.port8080 app.log 21 启动后用 curl 测试接口是否响应curl http://127.0.0.1:8080/api/room/list有 JSON 返回基本就说明后端跑通了。5.3 前端构建与 Nginx 配置前端构建需要先安装依赖再执行构建命令npm install npm run build构建完成后项目目录下生成 dist 文件夹里面就是打包好的静态文件。把 dist 文件夹整体上传到服务器放到 /usr/share/nginx/html 目录。Nginx 配置是整个部署环节最关键的一步。前后端分离项目的核心配置是两个 location 块第一个处理静态页面请求第二个把 /api 开头的请求反向代理到后端服务。server { listen 80; server_name your_domain; location / { root /usr/share/nginx/html; index index.html; try_files $uri $uri/ /index.html; } location /api/ { proxy_pass http://127.0.0.1:8080/api/; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; } }try_files 这行配置是 Vue Router history 模式的关键。如果没用这行用户刷新 /rooms 页面会直接 404因为服务器上根本没有这个文件。try_files 会把所有不存在的路径回退到 index.html交给前端路由处理。配置完成后重启 Nginx然后访问服务器 IP 或域名。如果页面能打开、接口能通整个项目就上线成功了。6. 踩坑实录前后端分离项目的常见问题最后这部分内容是我在实际开发部署中反复遇到的问题和对应的排查方案也是很多从零写全栈项目的人最容易卡住的环节。6.1 跨域问题开发环境跨域用 Vite 代理解决这个前面说过。但生产环境往往还会遇到一个情况用户直接在浏览器访问前端域名接口请求发到后端域名如果没有代理层浏览器会拦截跨域响应。我推荐生产环境用 Nginx 反向代理的方式解决后端不开启 CORS 反而更安全。后端需要开放 CORS 也可以但要注意配置允许的来源别直接写 *否则任何网站都能调你的接口。6.2 MyBatis 查询结果映射不上最常见的 MyBatis 问题是数据库字段是下划线命名create_timeJava 属性是驼峰命名createTime默认情况下映射不上查询结果里这个字段是 null。解决方法是在 application.yml 里配置mybatis: configuration: map-underscore-to-camel-case: true这个配置加上之后MyBatis 会自动把下划线字段映射为驼峰属性一劳永逸。6.3 前后端时间格式化不一致Java 8 的时间类型 LocalDateTime默认序列化成 JSON 时格式是2025-01-01T12:30:00中间带个 T前端显示不友好。我在 Jackson 配置里统一设置了格式spring: jackson: date-format: yyyy-MM-dd HH:mm:ss time-zone: Asia/Shanghai这样所有接口返回的时间字段都统一成2025-01-01 12:30:00格式。前端拿到字符串直接展示或者用 dayjs 处理都可以。6.4 常见问题速查表问题现象可能原因解决方法前端接口全部 404Nginx 缺少 try_files 或 proxy_pass 路径不对检查 Nginx 两个 location 配置接口返回 500日志显示 MySQL 通信异常连接串缺少时区参数或数据库连接池耗尽加 serverTimezoneAsia/Shanghai检查连接池配置登录成功但请求接口 401token 过期或请求头没带 Authorization检查 Axios 拦截器确认 token 传递方式中文乱码MySQL 字符集不是 utf8mb4建库时指定 CHARACTER SET utf8mb4端口被占用上次启动的后端进程没杀掉lsof -i:8080 查进程kill 掉再启动前端刷新页面空白路由模式是 history缺少 try_files 回退Nginx 加 try_files $uri $uri/ /index.html6.5 前端构建报错与依赖版本处理现在很多项目初始化时用的依赖版本比较新新版本对 Node.js 版本有要求。比如 Vite 5 要求 Node.js 18 以上如果你本地还是 Node.js 16构建时会出现一堆报错。我的建议是安装 nvm 管理 Node 版本项目里用 .nvmrc 文件锁定版本号。还有 Element Plus 的按需引入如果用 unplugin-vue-components 插件要注意插件版本的兼容性。我遇到过组件库版本和插件版本不匹配导致按钮组件样式消失的问题。排查半天最后是统一升级到最新版本解决的。后端这块SpringBoot 2.7 和 3.x 的差异要注意SpringBoot 3.x 要求 JDK 17 以上而且 javax 包名改成了 jakarta。如果你照着 SpringBoot 2.x 的教程写代码直接套到 3.x 项目里启动时会报 ClassNotFound 之类的错误。我用的是 SpringBoot 2.7 配合 JDK 11生态成熟问题少。强烈建议新手先从这个组合入手别一上来就追新版本。我在实际开发中还发现前后端分离项目的联调效率很大程度上取决于接口文档的规范程度。我习惯先用 Postman 把每个接口的入参、出参、错误码测试通过再让前端对接。后端每个接口都统一返回 Result 格式前端封装好拦截器之后整个对接过程异常顺利。最后再说一个实用的小技巧这套系统的订单状态机设计其实可以直接复用到其他行业项目里。不管是预约服务、课程报名还是租赁管理核心都是预订、确认、履约、完成这套流转。把订单表的字段抽象成通用的业务类型、业务 ID、时间区间、状态就能做成一个通用的订单模块这是我后来做其他系统时反复验证过的思路。如果你也要从零搭一套类似的管理平台我最大的建议是别急着写代码先把业务流程图和数据表结构画清楚。我在这个项目里前期花了一半时间在数据库设计和状态流转梳理上后期写代码几乎没怎么返工。这个习惯比我写代码本身更值钱。