做中介业务系统有一个很深的体会技术坑其实都能填平真正麻烦的是业务模型梳理不清。这套房屋中介管理系统后端用的 Spring Boot前端用的 Vue是我个人完整走完设计和开发全流程的一个模拟项目X。它解决的核心问题很简单——把房源、客户、带看、成交这四件事串成一条可追踪的链路让中介门店不再靠 Excel 和微信记录业务。适合正在做毕设或刚入门全栈开发的同学参考也适合中小中介团队拿来改造成自己的内部工具。系统本身不大但麻雀虽小五脏俱全。我会从技术选型、数据库设计、后端接口、前端页面四个维度拆开讲最后把开发中容易踩的坑全部列出来都是实测过的经验不是文档里能查到的。1. 整体设计与技术选型为什么是 Spring Boot Vue1.1 技术选型的核心考量项目标题里已经写明了技术栈Spring Boot 框架和 Vue。这个组合在中小型管理系统里几乎是标准答案但标准答案背后有它成立的逻辑。后端选 Spring Boot核心原因是开发效率。房屋中介管理系统本质上是增删改查密集型的 CRUD 应用Spring Boot 的自动配置机制帮我们省掉了大量 Spring 时代的 XML 配置。我实际开发中用到的核心依赖就三块Spring Web 处理接口路由MyBatis Plus 做数据库操作JWT 做登录鉴权。这三块加起来一个空项目从创建到跑通第一个接口半天时间足够了。前端选 Vue 的原因也很直接组件化开发让页面复用变得简单。中介系统里有大量相似页面——房源列表、客户列表、成交记录它们的表格结构、筛选条件、分页逻辑几乎一致用 Vue 的组件继承和 mixin 机制可以抽出一套通用模板后续新增页面只需要改字段配置。这一点在实际开发中节省的时间非常可观。还有一个隐形考量是生态成熟度。Element UI 组件库对标的后台管理场景恰好覆盖了中介系统的全部需求表格、表单、弹窗、日期选择器这些高频组件都有现成封装不需要自己造轮子。这点对个人开发者特别重要因为我们的时间应该花在业务逻辑上而不是底层组件上。1.2 系统架构与模块划分整个系统按业务域划分为六大模块各自职责如下表所示模块核心功能关键表登录鉴权用户登录、Token校验、权限控制user房源管理房源录入、上下架、条件筛选house客户管理客户需求登记、跟进记录customer带看管理预约看房、带看反馈appointment成交管理成交登记、佣金计算deal合同管理合同创建、状态跟踪contract这个划分不是凭空想出来的我参考了几家实际中介门店的作业流程。核心逻辑是房源和客户是基础数据带看是连接动作成交是最终目标。开发时按这个顺序做天然形成数据流转关系——先有房源和客户才能预约带看带看满意才进入成交。这个顺序也决定了数据库外键的设计方向。技术架构上前端 Vue 通过 Axios 调用后端 Restful 接口后端统一返回 JSON 数据格式。接口设计中我定义了一套统一响应结构包含状态码、消息和数据三部分。这样一个接口是成功还是失败前端只需要判断一个状态码字段不需要每个接口单独处理异常代码整洁度提升非常明显。2. 数据库设计中介业务的核心表结构拆解2.1 核心表设计思路数据库设计是整个项目里最不能急的部分。我见过太多人上来就建表做到一半发现字段不够用回头改表结构连带改一堆接口非常痛苦。中介系统的表设计要抓住两条主线人客户和员工和物房源这两条线在带看和成交表里交汇。先看最核心的房源表。房源字段除了基础的标题、价格、面积、户型、地址之外我特别加了一个 status 字段取值范围是 0-3分别代表草稿、在售、已预订、已成交。这个字段极其重要因为中介系统的所有业务动作都会联动修改它——房源成交后必须自动置为已成交状态不能再出现在在售列表里。如果在代码里散落着各种 if 判断来管理状态早晚会出 bug集中在数据库字段和对应枚举里管理是更稳的做法。客户表的设计要考虑到中介业务的一个特点同一组客户可能在多个门店登记。所以客户表里我用 phone 字段做唯一索引录入时先查重防止重复建档。另外还加了一个 requirement 字段用 JSON 格式存储客户的详细需求比如期望区域、价位区间、户型偏好。这个设计一开始被质疑过觉得规范化应该拆成单独的表但实际使用中发现 JSON 字段灵活性更好——客户需求本身就是松散的描述性信息硬拆表反而增加开发量。2.2 关系设计与索引优化表间关系遵循业务流转的递进逻辑中介录房源、录客户之后为某客户对某房源发起带看预约带看完成反馈后进入成交创建流程。外键关联我用逻辑外键而非数据库物理外键原因是物理外键在数据量上来后会影响插入性能而且分库分表场景下物理外键根本没法用。逻辑外键的做法是保留关联字段但不建 FOREIGN KEY 约束靠代码层保证数据一致性。字段类型上有几个实际踩坑的经验。价格字段千万不能用 float浮点数的精度问题会导致金额算错必须用 decimal(10,2)小数点后两位正好对应到分。时间字段推荐用 datetime 类型并且所有时间在数据库统一存 UTC 时间展示时由前端根据用户时区转换这样避免了很多跨时区的时间错乱问题。索引设计遵循最左前缀原则高频查询条件一定要建联合索引。房源表里最常见的查询是区域 状态 价格区间所以建了 idx_area_status_price 联合索引实测查询速度提升非常明显。客户表的 phone 字段因为要做唯一性检查建了唯一索引这个既是业务约束也是性能保障。3. 后端核心实现Spring Boot 的关键环节3.1 分层架构与统一响应后端我采用的是经典的三层架构Controller 接收请求、Service 处理业务逻辑、Mapper 操作数据库。很多人觉得三层架构啰嗦小项目用得着吗我的经验是必须用。原因有两个一是代码可维护性业务逻辑集中在 Service 层Controller 层只做参数校验和结果返回后续加功能改逻辑都清晰二是单元测试好写针对 Service 层做测试时不需要走 HTTP 请求直接调用方法就能验证。统一响应结构是每个 Spring Boot 项目都应该封装的基础设施。我定义的响应体包含三个字段code 表示状态码message 为提示信息data 携带业务数据。成功时 code 为 200失败时根据场景返回 400参数错误、401未登录、403无权限、500服务器异常。前端 Axios 的响应拦截器统一判断 code非 200 直接弹出错误提示并中断后续逻辑这让所有接口的错误处理逻辑完全收敛不用每个页面重复写。一个设计细节是分页接口的参数规范化。全系统分页参数统一为 pageNum 和 pageSize返回结构统一为 { total, list }。这看起来是小事但统一之后前端的分页组件和后端的分页插件才能完美配合不用每个接口做特殊的适配逻辑。我强烈建议从一开始就定好这个规则中途改协议的代价很高。3.2 登录鉴权与 JWT 实战登录鉴权我选的 JWT 方案而不是传统的 Session 方案。区别在于 Session 需要服务端存储状态分布式部署时要引入 Redis 做会话共享JWT 是无状态的Token 本身包含用户信息服务端只需要验证签名就能确认用户身份天然适合前后端分离架构。JWT 的落地细节有几个要注意的地方。Token 过期时间我设置了 24 小时这样用户体验和安全性比较平衡——太短要频繁重新登录太长有安全隐患。Token 里只放 userId 和 role 两个字段不放敏感信息。另外我在 Token 生成时加了一个随机字符串作为签名密钥的盐这个在做密码找回或者账号被顶号下线功能时会很有用。拦截器是鉴权的核心实现。我写了一个 TokenInterceptor 实现 HandlerInterceptor在 preHandle 方法里从请求头取 Token解析验证通过后把 userId 放入 ThreadLocal方便后续业务逻辑获取当前用户。对无需登录的接口比如登录接口本身通过注册时的排除路径处理。这里有一个很隐蔽的坑Spring Boot 对静态资源的拦截默认是不生效的但如果你的静态资源和接口路径配置不对拦截器可能会误伤静态资源导致前端页面加载不出来。排查思路是在 WebMvcConfigurer 的 addInterceptors 里明确排除静态资源路径前缀。3.3 业务逻辑层的关键处理业务逻辑层里最典型的是房源上下架和成交状态流转。这部分我用了状态机思维来管理拒绝在业务代码里散落状态判断。以房源为例状态流转路径是固定的草稿 - 在售 - 已预订 - 已成交。每一次状态变更都对应一个明确的业务动作。草稿转在售是中介点击上架在售转已预订是客户缴纳意向金已预订转已成交是完成签约付款。我在 Service 层封装了状态变更方法方法内部先校验当前状态是否允许目标状态不允许就直接抛异常。这么做的直接好处是两个第一业务规则集中在一个地方不会出现某个接口绕过校验直接改状态的情况第二后续扩展新状态比如下架整改时只需要改状态机定义不用满项目找 if 判断。成交模块里还有佣金计算的逻辑。佣金金额 成交价格 × 佣金比例不同的房屋类型对应不同的佣金比例这部分我用策略模式实现每种房屋类型对应一个计算策略类通过 Map 做分发。这种写法比 if-else 链清晰得多而且新加一种房屋类型只需要新增一个策略类符合开闭原则。4. 前端实现Vue 的核心页面与交互逻辑4.1 前端架构与路由权限控制前端我用的是 Vue 2 Vue Router Vuex Axios 的组合配合 Element UI 组件库做界面。这个组合虽然不是最新的 Vue 3 方案但在稳定性、社区资料和二手资料丰富程度上是最有优势的遇到问题基本都能搜到解决方案对个人开发项目来说是性价比最高的选择。路由权限控制是前端的一个关键环节。虽然后端接口已经做了权限校验前端路由仍然要做一层控制否则用户手动输入 URL 也能跳转到无权限页面体验很差。我的做法是路由配置表里给每个路由增加 meta 字段包含角色信息路由守卫 beforeEach 里判断当前用户角色是否在 meta.roles 范围内不匹配就重定向到 403 页面。Axios 的封装也很重要。我在 utils/request.js 里统一配置了 Axios 实例包括基础 URL、请求超时时间以及请求和响应拦截器。请求拦截器负责自动附加 Token 到 Header响应拦截器负责统一处理业务错误码比如 401 时自动跳转登录页并清除本地用户信息。这个拦截器逻辑写完之后所有业务页面完全不感知鉴权细节新增页面时只需要正常写接口调用登出、Token失效这些逻辑自动生效。4.2 房源管理模块的界面实现房源管理模块是系统里交互最复杂的部分也是最能体现 Vue 组件化优势的地方。列表页包含搜索条件区、表格展示区、分页器和操作按钮组。搜索条件区我用了 Element UI 的 el-form 配合 el-select、el-input、el-date-picker 组件每个搜索条件都 v-model 绑定到一个查询对象点击查询按钮时根据查询对象组装请求参数。这里有一个提升体验的关键细节房源列表的搜索和分页是联动的。页码变化时前端会带上当前搜索条件重新请求数据两个状态变量查询参数和页码用一个统一的方法处理。实际开发中很多人会忽略分页时丢失搜索条件的问题导致用户翻到第二页突然发现搜索结果变了。规避方法是维护一个可变的查询条件对象分页回调里传入当前条件对象。表单新增和编辑我复用了同一个对话框组件。打开新增时表单清空打开编辑时表单回显。关键实现是判断当前操作类型通过一个切换标识控制表单提交的接口调用路径。回显数据时要注意日期选择器的值格式Element UI 的日期组件默认返回 Date 对象而后端存储的是字符串提交前需要做格式化。这个问题我单独封装了一个日期格式化工具函数统一处理。4.3 带看与成交页面的流程联动带看管理模块是整个系统里业务逻辑最密集的。它的核心流程是选中客户、选择房源、设置带看时间、填写带看反馈。前端用一个带看表单弹窗承载这三个步骤房源选择用级联选择器先选区域再选具体房源数据源从后端接口动态加载。带看完成后的反馈页是我单独设计的组件。中介在带看完成后需要填写客户意向、房源问题、下次跟进时间。这些字段的价值在后期的数据分析里会体现——意向字段统计每个房源的被看好率这个数据能直接指导中介的业务决策。所以前端提交反馈时我会把带看状态的变更一起提交后端在事务里同时更新带看记录和房源热度统计保证数据一致性。成交模块前端最主要是合同预览功能。合同模板用 HTML 模板拼接填充动态数据后嵌入到页面中预览中介确认信息无误后点击确认即正式生效。这个功能实现不复杂但对于实际使用体验提升巨大——中介不用从系统复制数据到 Word 里手工做合同了系统自动生成减少大量重复录入工作也杜绝了录入错误的风险。5. 常见问题与排查技巧实录5.1 前后端联调中的高频问题开发过程中最大的时间黑洞往往是前后端联调环节这里列几个我实际遇到频率最高的问题。跨域问题排第一。前端运行在 localhost:8080后端运行在 localhost:9090端口不同必然产生跨域。解决方案是在后端配置 CORS用 CorsFilter 组件统一处理允许的前端地址显式配置。要注意的是 allowCredentials 必须设为 true否则前端请求携带 Token 的 Cookie 会被浏览器拦截。日期格式不一致排在第二。前端传递的日期格式是 2024-01-15但后端实体类里的 Date 字段默认接收的是带时间戳的格式解析直接报错。解决方法是后端实体类的日期字段上加 JsonFormat 注解统一指定 pattern 为 yyyy-MM-dd HH:mm:ss。这个坑特别隐蔽因为第一个接口调通后开发者很容易忽略传参类型的严格匹配直到某天传了一个日期参数才发现报错。大数据量分页查询性能问题排在第三。房源表录入几千条数据后不带条件的全量分页查询响应时间明显变长。优化方案是分页查询时强制带上状态筛选因为业务上不会一次查询全部状态的房源。同时给常用的查询条件组合建联合索引查询速度提升非常明显。5.2 部署上线阶段的实战经验项目开发完部署上线又是一个新的关卡。个人开发项目最常见的部署方式是前后端分离部署后端打 jar 包放到服务器上通过 java -jar 启动前端构建后的静态文件交给 Nginx 托管。部署阶段最容易被忽略的是 Nginx 的反向代理配置。前端部署后访问的是服务器 IP 或域名前端代码里的 API 请求地址指向的是相对路径如果 Nginx 不配置代理转发所有接口请求都会 404。我的配置方式是在 Nginx 的 location /api/ 块里配置 proxy_pass 转发到后端的 localhost:9090这样前端请求 /api/login 会正确转发到后端接口。数据库的初始化也要特别小心。我先在本地开发环境中把建表语句和初始数据通过数据脚本整理好上线时按顺序执行。这里建议用专业的数据库迁移工具或者在 schema 变更文档中记录清楚每次变更内容这样后续更新环境时不会出现表结构不一致的排查难题。上线前最好对生产环境的数据量和并发量做一次预估确保服务器配置够用——我遇到过一次配置过低导致接口响应极慢的情况最后把 jar 包启动参数里的初始堆内存调大才解决。还有一个小技巧上线前把应用日志的 log level 从 debug 调成 info避免生产环境磁盘被大量调试日志快速填满尤其是带看和成交模块这种日志输出密集的地方。同时启用日志文件的按天滚动切分配合定时清理策略能保证磁盘空间长期稳定。5.3 项目复盘与后续扩展做完整个项目后复盘几个设计决策回头看是相当关键的。第一个是统一响应结构的定义它让所有前后端接口对接有了统一标准联调时几乎不需要逐个接口沟通错误格式。第二个是状态机管理房源状态后续扩展业务时只需要增加新状态和流转规则不需要在代码里到处修改判断条件。第三个是 JWT 鉴权方案它让系统天然支持前后端分离部署和未来的多端扩展。如果后续要扩展这个系统我会优先考虑两个方向。一是增加数据分析看板把带看转化率、区域热度、客户来源等指标可视化呈现帮助门店管理层决策。实现上后端增加统计接口前端用 ECharts 做图表展示技术上没有新门槛但业务价值非常高。二是引入 WebSocket 实现消息推送比如带看预约通过后即时通知相关中介这个能力能显著提升业务协同效率建议后续接入。说到最后还是要强调那句话这类管理系统本身不难难的是把业务流程吃透并且用代码正确表达出来这需要先想清楚业务模型再动手做起来会顺很多。踩过的坑或者说积累的经验都写在上面这些内容里了读者照着实操一次就能少走很多弯路。