万能的SpringBootVue组合确实是被很多项目验证过的稳妥方案但真正把它用在一个面向具体区域的智慧服务平台上还是有大量从零到一的细节值得捋清楚。我参与的这个项目需求方最初只给了我们一句话为自贸港区域内的企业和居民做一个线上服务入口能查政策、办事、看进度。没有原型图没有功能清单没有UI规范甚至没有明确的服务对象优先级。从那一刻开始我们才意识到最难的从来不是技术实现而是怎么在模糊需求里把项目的边界和功能骨架定下来。这篇文章就是对这个项目的完整复盘。我会从需求如何框定、前后端架构如何划分、后端核心模块怎么实现、前端怎么搭起来到部署上线期间踩到的几个真实坑完整过一遍。这个过程对两类人有直接参考价值一类是要做类似XX智慧服务平台毕业设计的同学另一类是工作中接到偏业务型、周期又紧的前后端分离项目需要快速找到切入点的开发者。我会把当初团队所有的取舍和后悔都写出来供你参考。1. 从一句话需求到六大功能模块项目边界是怎么定下来的1.1 需求方说智慧实际要的是好用先讲一个容易误导人的地方。智慧服务平台听起来很高大上需求方一开始也提过要不要上AI问答、智能推荐这些东西。但我们团队内部做了一轮需求调研之后很快意识到一个事实这类平台的第一用户是普通办事群众和企业经办人他们对智慧最朴素的定义是——不用跑线下窗口、打开网页能知道怎么办、提交材料能知道办到哪一步了。我们当时的做法是先把用户分成了两类企业用户和个人用户。企业用户的核心诉求是政策申报、企业开办或者资质变更这类事项个人用户则更关心社保、公积金、证件办理等个人事项以及政策资讯的浏览。两者都需要一个共同的底座账号登录、身份认证、消息通知。把这两类用户的需求列成一张矩阵我们才发现很多功能是重叠的。比如不管是企业还是个人都需要办事指南材料清单进度查询。所以功能没有那么发散核心收敛成几件事就够了并不需要像大平台那样铺得很开。1.2 功能清单敢于做减法需求沟通阶段最容易犯的错误是什么都想要。我们当时是在会议室里贴了一整面墙的便签里面写了智能问答语音提示企业画像大数据分析等等后来一条条砍。砍的标准很简单三个月内能不能做出来现有团队人手能不能维护用户是否愿意每天打开。答案不明确的一律后置或砍掉。最终定下来的核心功能清单是六块门户首页、政策资讯、事项办事、个人中心、消息通知、后台管理。其中事项办事是绝对的核心承载了申报、材料上传、审核流转、进度查询整条链路。后台管理则是给运营人员用的用来发布政策、管理事项、审核申报、发送通知。这里有一个经验值得记下来做这类平台功能清单的每个模块都要能回答谁在用、解决什么问题、有没有替代方案这三个问题。比如政策资讯最初想法是做一个很复杂的分类检索系统后来发现用户实际场景很简单就是想看到最新发布的政策和按关键词搜一下所以最终做成了一个带分类筛选和标题关键词检索的列表页后台做一个富文本编辑器发布完全够用。1.3 技术选型背后的实际权衡技术栈是SpringBoot加Vue今天看很像默认答案但当时也是比对过几个方案的。后端方面SpringBoot的优势是生态太成熟了团队里没有人需要从零学起做用户认证有现成的框架整合做事务管理、接口校验、定时任务都有成熟的组件。对比过Node.js技术栈但我们团队对Java后端更熟悉考虑到后续维护交接SpringBoot是最优选择。前端选Vue一是Vue3加上Vite构建速度快二是Element Plus组件库对后台管理类页面尤其友好表格、表单、弹窗、分页这些都是现成的能省大量UI时间。我们没有选择自己封装太多UI组件大部分表单、表格直接复用Element Plus再通过二次封装统一交互风格。数据库用MySQL缓存用Redis。文件存储用的是云服务商的对象存储主要存用户上传的材料图片和PDF。部署就是一台云服务器加Nginx前后端分离部署先做出一版能跑的再考虑集群扩展。2. 前后端分离的架构落地SpringBoot和Vue各自该管哪些事2.1 模块划分和工程结构前后端分离听起来很简单前端一个工程后端一个工程接口一对接就行。但实际工程落地我们还是花了不少功夫在包结构和目录划分上。后端按业务模块分包而不是按技术层分这是我们从早期项目里学到的一个重要教训。如果按controller、service、mapper这样分层分包业务一多目录就会变成大杂烩按用户模块、政策模块、事项模块、消息模块来分每个模块内部再去分controller、service、mapper代码归属感会清晰很多。后端整体结构大致是这个样子com.platform ├── common # 通用类Result、异常、工具类 ├── config # 配置跨域、拦截器、Redis、文件上传等 ├── module │ ├── user # 用户、角色、权限 │ ├── policy # 政策资讯 │ ├── item # 事项管理 │ ├── apply # 申报与审核 │ └── message # 消息通知 └── PlatformApplication.java前端工程用的是Vite创建的Vue3项目目录上主要分views、components、router、store、api这五块。api目录下把每个后端的controller按模块对应拆一个文件比如user.js、policy.js、apply.js统一封装axios请求这样前端调用后端接口时路径比较好找修改也集中。2.2 数据库设计的几个关键决策数据库表设计是这类业务系统的地基我们的核心表主要围绕几个对象用户、角色、事项、申报记录、政策文章、通知消息。下面这张表是当时核心数据的概览设计时每个字段都经过了几轮内部讨论表名核心字段说明sys_userid, phone, password, type, status用户表type区分企业/个人sys_role / sys_user_rolerole_code, role_name角色与用户关联用于RBACitem_infoid, name, category, material_list, status可申报事项材料清单用JSON存储apply_recordid, user_id, item_id, status, current_node申报记录状态机流转policy_articleid, title, category, content, publish_time政策文章富文本内容msg_noticeid, user_id, title, content, is_read站内消息关键决策有几个值得展开。第一个是逻辑删除所有表都加一个deleted字段查询时统一过滤。这个平台后期运营人员会频繁做启用、停用事项的操作硬删除数据容易把关联记录也带走逻辑删除至少能保住历史申报记录的可追溯性。第二个是材料清单用JSON字段存储一个事项需要哪些材料这本身是一组相对固定的结构化数据但不同事项差异很大用单独的关联表会导致非常多的中间表。我们用MySQL的JSON类型字段在service层做序列化和反序列化查询效率完全没问题代码也简洁很多。第三个是审计字段统一处理create_time、update_time都用数据库自动填充或者MyBatis-Plus做公共字段自动填充。我们提前在基类里写了createdBy、updatedBy所有表继承这个基类省了每张表重复维护的功夫。2.3 统一接口返回格式与跨域处理后端接口风格统一成RESTful返回结构统一使用Result类这个类在项目里相当于前后端沟通的通用语言。Result包含code、msg、data三个字段code为200表示成功400表示参数错误或业务规则不通过401表示未登录或登录过期500表示服务器异常。前端axios响应拦截器里统一判断code而不是HTTP状态码。这么做的最直接好处是业务异常也是200状态返回HTTP层不会出现语义混乱前端只需要处理一个统一的返回结构。跨域问题在开发环境下用两种方式解决。本地开发时前端Vite配置proxy代理把/api开头的请求代理到后端地址浏览器看到的是同源的不会触发跨域。生产环境直接用Nginx反向代理把所有带/api前缀的请求转发到SpringBoot服务。这样处理比在后端代码里开CORS要干净得多也方便后续做负载均衡。后端同时保留CORS配置作为兜底但只在测试环境打开。3. 后端骨架权限、流程状态机与外部接口的实战实现3.1 JWT加RBAC权限体系不能只做到能登录用户认证这块我们用的是JWT核心原因是前后端分离架构下服务端不需要保存会话状态用户登录后拿到一个token前端存到localStorage后续请求都带在Authorization头里。配合Redis做token的主动失效基本覆盖了日常需求。权限模型用的是经典的RBAC用户绑定角色角色绑定权限码。我们的角色设计得比较简单前台用户只有普通用户和企业用户两种后台管理人员分运营和审核员两种。运营可以发布政策、管理事项审核员只能处理申报审核。在接口层面我们给每个需要权限控制的后台接口都加了权限码校验在拦截器里解析JWT中的角色和权限码再决定是否放行。拦截器实现的关键代码逻辑如下Component public class JwtInterceptor implements HandlerInterceptor { Override public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception { // 放行预检请求 if (OPTIONS.equals(request.getMethod())) { return true; } // 放行白名单路径 if (request.getRequestURI().startsWith(/api/auth/login)) { return true; } String token request.getHeader(Authorization); if (token ! null token.startsWith(Bearer )) { token token.substring(7); try { Claims claims JwtUtil.parseToken(token); request.setAttribute(userId, claims.get(userId)); request.setAttribute(roleCode, claims.get(roleCode)); return true; } catch (Exception e) { // token解析失败走下方拦截 } } response.setStatus(401); response.setContentType(application/json;charsetUTF-8); response.getWriter().write({\code\:401,\msg\:\登录状态已失效请重新登录\}); return false; } }这个实现里我特别想强调一个细节token解析失败时不要返回500也不要抛出异常而是统一返回401并设置响应状态码。前端拦截器会捕获401并跳转登录页用户感知就是登录过期需要重新登录体验上是流畅的闭环。3.2 办事服务从申报到审核的状态机设计办事项业务是整个平台最核心的链路它的复杂程度远超普通增删改查。一份申报记录从创建到最后结束要经历待审核、审核中、待补充材料、已通过、已驳回这几个状态。如果不做约束只靠业务代码里的if-else后期状态流转一定会乱。我们给申报记录设计了一个简单的状态机在代码里用常量加一个状态流转规则类来管理public class ApplyStatusMachine { public static final int DRAFT 0; // 草稿 public static final int PENDING 1; // 待审核 public static final int REVIEWING 2; // 审核中 public static final int NEED_MATERIAL 3; // 待补充材料 public static final int APPROVED 4; // 已通过 public static final int REJECTED 5; // 已驳回 private static final MapInteger, SetInteger ALLOWED_TRANSITIONS new HashMap(); static { ALLOWED_TRANSITIONS.put(DRAFT, new HashSet(Arrays.asList(PENDING, DRAFT))); ALLOWED_TRANSITIONS.put(PENDING, new HashSet(Arrays.asList(REVIEWING, REJECTED))); ALLOWED_TRANSITIONS.put(REVIEWING, new HashSet(Arrays.asList(APPROVED, REJECTED, NEED_MATERIAL))); ALLOWED_TRANSITIONS.put(NEED_MATERIAL, new HashSet(Arrays.asList(REVIEWING, REJECTED))); } public static boolean canTransition(int from, int to) { SetInteger allowed ALLOWED_TRANSITIONS.get(from); return allowed ! null allowed.contains(to); } }用户提交申报时记录进入待审核审核员领单后变为审核中材料不全时退回待补充材料状态用户补充上传后再回到审核中审核通过或驳回则终态。每次变更状态都会插入一条状态变更历史记录前端进度页就靠这份历史记录渲染成时间轴。这个设计如果一开始不做后面做进度跟踪一定会返工因为它涉及的数据查询和页面展示都是围绕历史状态链来做。3.3 政策资讯模块简单需求也值得认真做政策资讯这个模块业务上并不复杂就是一个后台发布、前台展示、支持分类和关键词检索的内容系统。但我们在实现上还是有两个值得分享的细节。第一个是后台富文本内容和纯文本摘要分开存。列表页展示摘要详情页展示富文本内容这样列表查询不需要把很长的HTML正文从数据库拖出来数据库和网络的开销都小不少。第二个是政策列表加缓存。政策资讯读取频率极高、更新频率低非常适合用Redis做缓存。我们以category:page:size作为缓存key后台发布或编辑文章时主动删除对应缓存下一次查询再重新回填命中率很高数据库压力基本打不下来。检索这块没有上搜索引擎用的就是MySQL的LIKE模糊查询加title字段索引数据量只有几百条时性能完全够用。如果后面政策数量上到几十万条再考虑迁移到专门的搜索引擎也不迟重点是当前阶段不要过度设计。3.4 外部服务对接短信和对象存储的整合经验平台的消息通知分为站内消息和短信通知。站内消息是系统自动生成的比如申报状态变化会向用户消息表插入一条记录。短信通知对接了云服务商触发点是两个注册验证码和申报状态变化。这里特别要注意一个坑短信接口必须做频率限制和幂等处理。我们在Redis里对每个手机号设置了一个发送间隔锁比如同一手机号60秒内只能发一次验证码防止恶意刷接口。幂等处理则是基于业务单号同一申报单的状态变化通知不会重复触发。对象存储主要用来承接用户上传的材料文件。后端拿到前端传上来的文件流直接生成一个唯一文件名上传对象存储然后把访问URL存到数据库对应字段。这里有一个经验上传和入库不能做成一个事务里不可分割的两步因为文件上传有网络延迟会拖长事务。我们的做法是先上传文件拿到URL再在业务事务里保存URL到数据库如果事务失败最多多出一个孤儿文件通过一个定时清理任务扫描即可问题不大。4. 前端工程化Vue3页面搭建和与后端联调的完整记录4.1 初始化Vite加Vue3加Element Plus的工程底座前端我们用的是Vue3的组合式API项目用Vite初始化UI框架是Element Plus。初始化过程很快真正花精力的是把公共层搭好。这个公共层包含三件事axios统一封装、路由设计、通用组件提取。axios封装看起来是老生常谈但决定整个联调体验。我们在api目录下一个request.js里做了统一实例设置baseURL为/api请求拦截器从localStorage取token并加到Authorization头响应拦截器统一处理业务码和401跳转。这样业务代码里调用接口就非常干净比如申请列表的直接就是一个返回Promise的调用不需要每个页面重复写header处理。组件提取的原则是一个组件被复用了两次以上才值得单独抽出来。我们当时抽了几个通用组件搜索表单组件、分页列表组件、步骤条进度组件、审核弹窗组件。尤其搜索表单加分页列表这套组合在后台管理页面里几乎每个模块都要用封装一次能省大量重复代码。封装的代价是参数设计要花心思我们因为前期没设计好props和事件中期重构过一次组件这个成本如果能提前规划还是可以避免的。4.2 动态路由与访问控制前端只做展示控制权限控制是前后端配合的活。后端是真正的安全屏障前端则保证界面展示与用户权限匹配也就是没有权限的菜单和按钮不要出现在页面上。我们的实现是用户登录成功后返回JWT的同时后端返回这个用户的菜单权限码列表前端拿到后通过Vue Router的addRoute方法把用户有权限的页面路由动态注册进去。路由守卫里的判断逻辑如下router.beforeEach((to, from, next) { const token localStorage.getItem(token) const userInfo JSON.parse(localStorage.getItem(userInfo) || null) if (to.meta.requiresAuth !token) { next(/login) return } if (token userInfo) { if (to.meta.permission !userInfo.permissions.includes(to.meta.permission)) { next(/403) return } } next() })这个方法的关键在于前端控制菜单和路由只是为了更好的用户体验真正的接口权限校验必须以后端为准。我们当时就遇到过有用户直接访问接口URL的场景因为前端路由做了隐藏但后端接口没有加权限码差点漏成越权漏洞。后来在复盘时把后端所有管理类接口都加了一遍权限码校验这个教训非常深刻。4.3 几个典型页面组件的落地细节首页门户采用区块式布局顶部是导航栏和搜索框中部是政策资讯列表和常见办事事项入口底部是公告通知。页面本身不难但数据请求要做好缓存和加载状态的体验。我们用的是骨架屏加异步加载首次进入显示占位骨架数据返回后渲染真实内容观感比Loading转圈好很多。办事指南页除了事项基础信息和材料清单还放了一个在线申报按钮引导用户完成申报。这里有一个产品层面的小设计材料清单按必需材料和非必需材料分了两个区块用户准备材料时更直观。前端实现上就是JSON数据渲染成两个卡片区域逻辑简单但用户体验提升明显。申报进度页后端返回申报记录和状态变更历史前端用Element Plus的Steps组件渲染成时间轴。在状态多的情况下要让当前步骤和历史步骤分别用高亮和置灰区分当时调试中发现Steps组件的active参数和实际状态码映射需要做一层转换这个转换逻辑放在utils里做了统一处理。4.4 联调阶段的效率手段与常见坑前后端联调是项目里最容易消耗时间的阶段我们后来总结了一套方法。第一个是接口文档先行用统一的接口文档工具维护后端没写完接口前端也可以按文档Mock数据进行开发联调时减少口径不一致的问题。第二个是环境统一前后端统一都走开发代理前端调后端直接用相对路径避免出现把localhost写死在代码里的问题。联调中遇到最多的坑有两个。第一个是字段格式不一致后端返回的日期是2025-03-12 10:30:00这种字符串前端直接展示没问题但要作为时间戳对比时就需要统一转换。我们在request.js里约定所有日期都以字符串返回前端用dayjs统一处理避免不同页面各写各的逻辑。第二个是数组和对象判空后端返回的数组在数据为空时一定返回空数组而不是null这在接口文档里做了严格约定前端代码就不用写一堆空值防御。5. 部署上线阶段撞上的三堵墙从环境到性能的真实排障5.1 服务器环境与部署脚本的准备部署其实不算难难的是把整个流程脚本化避免每次上线靠人工操作。我们服务器上的环境是JDK 17、MySQL 8、Redis 6、Nginx 1.24。后端用一个简单的启动脚本管理进程核心就是nohup加java -jar。前端构建产物就是dist目录Nginx指到dist目录同时配置反向代理把/api请求转发到后端端口server { listen 80; server_name demo.example.com; # 前端静态资源 root /opt/platform/dist; index index.html; # 前端路由history模式找不到文件时回退到index.html location / { 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; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; } }这里有一个连续踩坑的点history路由模式必须配置try_files回退到index.html否则用户直接访问某个子路径时Nginx会返回404。很多前后端分离项目第一次上线都栽在这里。第一次部署后测试发现首页正常但一刷新详情页就是404排查了很久才意识到是Nginx没有配置回退。5.2 排障记录一生产环境跨域报错说来有点丢人开发环境一切正常部署到生产环境后前端调用接口直接跨域报错。最开始我们怀疑是Nginx代理配错了排查半天发现代理是通的curl带token访问后端接口完全正常。问题出在哪里后来检查才发现前端代码里axios的baseURL在构建时被写成了开发环境的地址也就是说生产环境的浏览器直接跨域请求了开发地址和Nginx完全没关系。解决办法是在Vite的构建配置文件里针对不同环境做环境变量替换生产构建时baseURL自动指向生产域名下的/api路径。从那以后我们都要求构建产物里不允许出现任何localhost或者127.0.0.1这样的字面量发现一个就是一个bug。5.3 排障记录二数据库连接池被打满上线第二天运营反馈平台偶尔会出现请求卡住很慢的情况后端日志里大量报连接池获取超时的异常。一开始以为是并发太高查了监控发现峰值QPS也就几十不至于压垮配置。后来检查代码才发现我们有几个地方在循环里调用了数据库查询比如用户详情页面要查用户基本信息、角色列表、最近申报记录这三条查询是串行的虽然每个查询都很快但在循环场景下连接占用时间就长了。解决方法是两点配合一是把这些关联查询要么改成一次性联表查询要么合并成一条SQL或者用Batch查询二是给Redis加了缓存用户信息这种几乎不变的数据直接缓存数据库查询次数大幅下降。连接池参数也从默认值调到了合理范围把最大连接数调大了一些更重要的是给查询走了索引从根上减少占用时间。5.4 排障记录三文件上传超出默认限制运营上传政策封面图时遇到提示上传失败但日志里没有任何异常输出。后来打开浏览器Network面板才发现POST请求的响应是413。这是Nginx默认的client_max_body_size只有1MB造成的而后端SpringBoot同样也有默认的spring.servlet.multipart.max-file-size限制。两边都要调client_max_body_size 20m;后端则要把配置里的文件大小调大并同时设置单文件和请求总大小限制。但这里也有一个安全考虑不要一上来就调成100MB要根据业务实际需要的最大材料体积来定我们调成了20MB并限制了文件类型避免了有人利用上传接口传超大文件打满磁盘的风险。6. 项目复盘重做一次的话我会改掉这五件事6.1 需求沟通阶段必须比做的还不够现在回头看整个项目最大的遗憾不是技术选型而是需求确认阶段没有更早地让运营方和典型用户参与进来。我们前期完全靠自己想象用户在怎么用这个平台直到测试版本出来让运营试用时才发现他们期望的事项分类比我们做的分类要细得多运营希望按业务部门维度再分一层菜单这个改动虽然不大却影响了一系列页面布局和后台配置项。如果在需求阶段就准备一批业务场景故事比如一名来自省外的企业经办人第一次使用平台办理资质变更的全过程再以这个故事的视角去验证功能清单很多分歧就能提前暴露。这种用户故事驱动的需求梳理方式之后的项目我会坚持当成必选环节。6.2 设计阶段要有意识地控制技术债我们为了赶进度在代码层面留了一些后患。比如用户模块的service层里混入了消息模块的判断逻辑事项模块的工具类被放在common包里后期找起来特别费劲。这些债在项目结束后不会消失后续接手的人维护成本会很高。经验是要在代码评审环节坚持模块边界不要因为这次改动很小就随意跨模块塞代码每一次跨模块都应该是经过讨论的决策。6.3 测试用例覆盖核心链路这个项目的自动化测试覆盖其实很弱大部分靠手工点点点。上线前我们专门梳理了一批冒烟用例比如用户注册、登录、发起申报、上传材料、管理员审核、消息通知这条主链路。这套手工冒烟流程每次发版都要完整跑一遍确实能拦住大多数低级的回归问题。如果再做一个类似的项目我会把这条核心链路的关键接口至少覆盖一遍JUnit的集成测试和前端Playwright端到端测试。测试用例不是越多越好但核心业务流程必须有兜底。6.4 给后来者的五条具体建议如果让我给打算做SpringBoot加Vue这类平台项目的同学几句话我会这样说先花至少一周时间把需求文档写清楚包括功能边界、角色权限、核心流程图不要急着写代码数据库设计阶段把所有状态枚举值定好并写在文档里后端代码里不要出现魔法数字全部用常量类维护接口返回格式从一开始就统一不要在项目中期再改前端路由守卫和后端拦截器配合做权限控制只认后端的最终校验部署前在测试环境按上线流程完整走一遍包括Nginx配置和构建流水线避免把上线这事变成第一次踩坑。6.5 做这类项目的最终体会三个月时间从零把一个智慧服务平台做上线技术上其实没有什么炫酷内容Java后端的CRUD、权限、缓存、文件上传Vue前端的基础增删改查和页面展示全是基础功。但真正难的是把这些基础组件像积木一样搭成一个业务上自洽、流程上完整、用户能真正拿来办事的系统。那段时间我最大的体会是项目成功与否往往不取决于你用了多新的技术而取决于需求边界有没有划定清楚、核心流程有没有状态机支撑、前后端之间有没有统一约定。技术是手段业务才是骨架。现在这个平台已经稳定运行了一段时间运营那边也在陆续提新需求比如企业画像、经营态势统计这些偏数据的方向。我后续比较想做的是把申报审批流程再拆成更灵活的工作流引擎让运营人员不需要改代码就能调整审批节点。如果之后真的推进了我大概率还会把这些过程写成另一篇更深入的文章继续把这套实践里的经验沉淀下来。
万能的SpringBootVue组合确实是被很多项目验证过的稳妥方案但真正把它用在一个面向具体区域的智慧服务平台上还是有大量从零到一的细节值得捋清楚。我参与的这个项目需求方最初只给了我们一句话为自贸港区域内的企业和居民做一个线上服务入口能查政策、办事、看进度。没有原型图没有功能清单没有UI规范甚至没有明确的服务对象优先级。从那一刻开始我们才意识到最难的从来不是技术实现而是怎么在模糊需求里把项目的边界和功能骨架定下来。这篇文章就是对这个项目的完整复盘。我会从需求如何框定、前后端架构如何划分、后端核心模块怎么实现、前端怎么搭起来到部署上线期间踩到的几个真实坑完整过一遍。这个过程对两类人有直接参考价值一类是要做类似XX智慧服务平台毕业设计的同学另一类是工作中接到偏业务型、周期又紧的前后端分离项目需要快速找到切入点的开发者。我会把当初团队所有的取舍和后悔都写出来供你参考。1. 从一句话需求到六大功能模块项目边界是怎么定下来的1.1 需求方说智慧实际要的是好用先讲一个容易误导人的地方。智慧服务平台听起来很高大上需求方一开始也提过要不要上AI问答、智能推荐这些东西。但我们团队内部做了一轮需求调研之后很快意识到一个事实这类平台的第一用户是普通办事群众和企业经办人他们对智慧最朴素的定义是——不用跑线下窗口、打开网页能知道怎么办、提交材料能知道办到哪一步了。我们当时的做法是先把用户分成了两类企业用户和个人用户。企业用户的核心诉求是政策申报、企业开办或者资质变更这类事项个人用户则更关心社保、公积金、证件办理等个人事项以及政策资讯的浏览。两者都需要一个共同的底座账号登录、身份认证、消息通知。把这两类用户的需求列成一张矩阵我们才发现很多功能是重叠的。比如不管是企业还是个人都需要办事指南材料清单进度查询。所以功能没有那么发散核心收敛成几件事就够了并不需要像大平台那样铺得很开。1.2 功能清单敢于做减法需求沟通阶段最容易犯的错误是什么都想要。我们当时是在会议室里贴了一整面墙的便签里面写了智能问答语音提示企业画像大数据分析等等后来一条条砍。砍的标准很简单三个月内能不能做出来现有团队人手能不能维护用户是否愿意每天打开。答案不明确的一律后置或砍掉。最终定下来的核心功能清单是六块门户首页、政策资讯、事项办事、个人中心、消息通知、后台管理。其中事项办事是绝对的核心承载了申报、材料上传、审核流转、进度查询整条链路。后台管理则是给运营人员用的用来发布政策、管理事项、审核申报、发送通知。这里有一个经验值得记下来做这类平台功能清单的每个模块都要能回答谁在用、解决什么问题、有没有替代方案这三个问题。比如政策资讯最初想法是做一个很复杂的分类检索系统后来发现用户实际场景很简单就是想看到最新发布的政策和按关键词搜一下所以最终做成了一个带分类筛选和标题关键词检索的列表页后台做一个富文本编辑器发布完全够用。1.3 技术选型背后的实际权衡技术栈是SpringBoot加Vue今天看很像默认答案但当时也是比对过几个方案的。后端方面SpringBoot的优势是生态太成熟了团队里没有人需要从零学起做用户认证有现成的框架整合做事务管理、接口校验、定时任务都有成熟的组件。对比过Node.js技术栈但我们团队对Java后端更熟悉考虑到后续维护交接SpringBoot是最优选择。前端选Vue一是Vue3加上Vite构建速度快二是Element Plus组件库对后台管理类页面尤其友好表格、表单、弹窗、分页这些都是现成的能省大量UI时间。我们没有选择自己封装太多UI组件大部分表单、表格直接复用Element Plus再通过二次封装统一交互风格。数据库用MySQL缓存用Redis。文件存储用的是云服务商的对象存储主要存用户上传的材料图片和PDF。部署就是一台云服务器加Nginx前后端分离部署先做出一版能跑的再考虑集群扩展。2. 前后端分离的架构落地SpringBoot和Vue各自该管哪些事2.1 模块划分和工程结构前后端分离听起来很简单前端一个工程后端一个工程接口一对接就行。但实际工程落地我们还是花了不少功夫在包结构和目录划分上。后端按业务模块分包而不是按技术层分这是我们从早期项目里学到的一个重要教训。如果按controller、service、mapper这样分层分包业务一多目录就会变成大杂烩按用户模块、政策模块、事项模块、消息模块来分每个模块内部再去分controller、service、mapper代码归属感会清晰很多。后端整体结构大致是这个样子com.platform ├── common # 通用类Result、异常、工具类 ├── config # 配置跨域、拦截器、Redis、文件上传等 ├── module │ ├── user # 用户、角色、权限 │ ├── policy # 政策资讯 │ ├── item # 事项管理 │ ├── apply # 申报与审核 │ └── message # 消息通知 └── PlatformApplication.java前端工程用的是Vite创建的Vue3项目目录上主要分views、components、router、store、api这五块。api目录下把每个后端的controller按模块对应拆一个文件比如user.js、policy.js、apply.js统一封装axios请求这样前端调用后端接口时路径比较好找修改也集中。2.2 数据库设计的几个关键决策数据库表设计是这类业务系统的地基我们的核心表主要围绕几个对象用户、角色、事项、申报记录、政策文章、通知消息。下面这张表是当时核心数据的概览设计时每个字段都经过了几轮内部讨论表名核心字段说明sys_userid, phone, password, type, status用户表type区分企业/个人sys_role / sys_user_rolerole_code, role_name角色与用户关联用于RBACitem_infoid, name, category, material_list, status可申报事项材料清单用JSON存储apply_recordid, user_id, item_id, status, current_node申报记录状态机流转policy_articleid, title, category, content, publish_time政策文章富文本内容msg_noticeid, user_id, title, content, is_read站内消息关键决策有几个值得展开。第一个是逻辑删除所有表都加一个deleted字段查询时统一过滤。这个平台后期运营人员会频繁做启用、停用事项的操作硬删除数据容易把关联记录也带走逻辑删除至少能保住历史申报记录的可追溯性。第二个是材料清单用JSON字段存储一个事项需要哪些材料这本身是一组相对固定的结构化数据但不同事项差异很大用单独的关联表会导致非常多的中间表。我们用MySQL的JSON类型字段在service层做序列化和反序列化查询效率完全没问题代码也简洁很多。第三个是审计字段统一处理create_time、update_time都用数据库自动填充或者MyBatis-Plus做公共字段自动填充。我们提前在基类里写了createdBy、updatedBy所有表继承这个基类省了每张表重复维护的功夫。2.3 统一接口返回格式与跨域处理后端接口风格统一成RESTful返回结构统一使用Result类这个类在项目里相当于前后端沟通的通用语言。Result包含code、msg、data三个字段code为200表示成功400表示参数错误或业务规则不通过401表示未登录或登录过期500表示服务器异常。前端axios响应拦截器里统一判断code而不是HTTP状态码。这么做的最直接好处是业务异常也是200状态返回HTTP层不会出现语义混乱前端只需要处理一个统一的返回结构。跨域问题在开发环境下用两种方式解决。本地开发时前端Vite配置proxy代理把/api开头的请求代理到后端地址浏览器看到的是同源的不会触发跨域。生产环境直接用Nginx反向代理把所有带/api前缀的请求转发到SpringBoot服务。这样处理比在后端代码里开CORS要干净得多也方便后续做负载均衡。后端同时保留CORS配置作为兜底但只在测试环境打开。3. 后端骨架权限、流程状态机与外部接口的实战实现3.1 JWT加RBAC权限体系不能只做到能登录用户认证这块我们用的是JWT核心原因是前后端分离架构下服务端不需要保存会话状态用户登录后拿到一个token前端存到localStorage后续请求都带在Authorization头里。配合Redis做token的主动失效基本覆盖了日常需求。权限模型用的是经典的RBAC用户绑定角色角色绑定权限码。我们的角色设计得比较简单前台用户只有普通用户和企业用户两种后台管理人员分运营和审核员两种。运营可以发布政策、管理事项审核员只能处理申报审核。在接口层面我们给每个需要权限控制的后台接口都加了权限码校验在拦截器里解析JWT中的角色和权限码再决定是否放行。拦截器实现的关键代码逻辑如下Component public class JwtInterceptor implements HandlerInterceptor { Override public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception { // 放行预检请求 if (OPTIONS.equals(request.getMethod())) { return true; } // 放行白名单路径 if (request.getRequestURI().startsWith(/api/auth/login)) { return true; } String token request.getHeader(Authorization); if (token ! null token.startsWith(Bearer )) { token token.substring(7); try { Claims claims JwtUtil.parseToken(token); request.setAttribute(userId, claims.get(userId)); request.setAttribute(roleCode, claims.get(roleCode)); return true; } catch (Exception e) { // token解析失败走下方拦截 } } response.setStatus(401); response.setContentType(application/json;charsetUTF-8); response.getWriter().write({\code\:401,\msg\:\登录状态已失效请重新登录\}); return false; } }这个实现里我特别想强调一个细节token解析失败时不要返回500也不要抛出异常而是统一返回401并设置响应状态码。前端拦截器会捕获401并跳转登录页用户感知就是登录过期需要重新登录体验上是流畅的闭环。3.2 办事服务从申报到审核的状态机设计办事项业务是整个平台最核心的链路它的复杂程度远超普通增删改查。一份申报记录从创建到最后结束要经历待审核、审核中、待补充材料、已通过、已驳回这几个状态。如果不做约束只靠业务代码里的if-else后期状态流转一定会乱。我们给申报记录设计了一个简单的状态机在代码里用常量加一个状态流转规则类来管理public class ApplyStatusMachine { public static final int DRAFT 0; // 草稿 public static final int PENDING 1; // 待审核 public static final int REVIEWING 2; // 审核中 public static final int NEED_MATERIAL 3; // 待补充材料 public static final int APPROVED 4; // 已通过 public static final int REJECTED 5; // 已驳回 private static final MapInteger, SetInteger ALLOWED_TRANSITIONS new HashMap(); static { ALLOWED_TRANSITIONS.put(DRAFT, new HashSet(Arrays.asList(PENDING, DRAFT))); ALLOWED_TRANSITIONS.put(PENDING, new HashSet(Arrays.asList(REVIEWING, REJECTED))); ALLOWED_TRANSITIONS.put(REVIEWING, new HashSet(Arrays.asList(APPROVED, REJECTED, NEED_MATERIAL))); ALLOWED_TRANSITIONS.put(NEED_MATERIAL, new HashSet(Arrays.asList(REVIEWING, REJECTED))); } public static boolean canTransition(int from, int to) { SetInteger allowed ALLOWED_TRANSITIONS.get(from); return allowed ! null allowed.contains(to); } }用户提交申报时记录进入待审核审核员领单后变为审核中材料不全时退回待补充材料状态用户补充上传后再回到审核中审核通过或驳回则终态。每次变更状态都会插入一条状态变更历史记录前端进度页就靠这份历史记录渲染成时间轴。这个设计如果一开始不做后面做进度跟踪一定会返工因为它涉及的数据查询和页面展示都是围绕历史状态链来做。3.3 政策资讯模块简单需求也值得认真做政策资讯这个模块业务上并不复杂就是一个后台发布、前台展示、支持分类和关键词检索的内容系统。但我们在实现上还是有两个值得分享的细节。第一个是后台富文本内容和纯文本摘要分开存。列表页展示摘要详情页展示富文本内容这样列表查询不需要把很长的HTML正文从数据库拖出来数据库和网络的开销都小不少。第二个是政策列表加缓存。政策资讯读取频率极高、更新频率低非常适合用Redis做缓存。我们以category:page:size作为缓存key后台发布或编辑文章时主动删除对应缓存下一次查询再重新回填命中率很高数据库压力基本打不下来。检索这块没有上搜索引擎用的就是MySQL的LIKE模糊查询加title字段索引数据量只有几百条时性能完全够用。如果后面政策数量上到几十万条再考虑迁移到专门的搜索引擎也不迟重点是当前阶段不要过度设计。3.4 外部服务对接短信和对象存储的整合经验平台的消息通知分为站内消息和短信通知。站内消息是系统自动生成的比如申报状态变化会向用户消息表插入一条记录。短信通知对接了云服务商触发点是两个注册验证码和申报状态变化。这里特别要注意一个坑短信接口必须做频率限制和幂等处理。我们在Redis里对每个手机号设置了一个发送间隔锁比如同一手机号60秒内只能发一次验证码防止恶意刷接口。幂等处理则是基于业务单号同一申报单的状态变化通知不会重复触发。对象存储主要用来承接用户上传的材料文件。后端拿到前端传上来的文件流直接生成一个唯一文件名上传对象存储然后把访问URL存到数据库对应字段。这里有一个经验上传和入库不能做成一个事务里不可分割的两步因为文件上传有网络延迟会拖长事务。我们的做法是先上传文件拿到URL再在业务事务里保存URL到数据库如果事务失败最多多出一个孤儿文件通过一个定时清理任务扫描即可问题不大。4. 前端工程化Vue3页面搭建和与后端联调的完整记录4.1 初始化Vite加Vue3加Element Plus的工程底座前端我们用的是Vue3的组合式API项目用Vite初始化UI框架是Element Plus。初始化过程很快真正花精力的是把公共层搭好。这个公共层包含三件事axios统一封装、路由设计、通用组件提取。axios封装看起来是老生常谈但决定整个联调体验。我们在api目录下一个request.js里做了统一实例设置baseURL为/api请求拦截器从localStorage取token并加到Authorization头响应拦截器统一处理业务码和401跳转。这样业务代码里调用接口就非常干净比如申请列表的直接就是一个返回Promise的调用不需要每个页面重复写header处理。组件提取的原则是一个组件被复用了两次以上才值得单独抽出来。我们当时抽了几个通用组件搜索表单组件、分页列表组件、步骤条进度组件、审核弹窗组件。尤其搜索表单加分页列表这套组合在后台管理页面里几乎每个模块都要用封装一次能省大量重复代码。封装的代价是参数设计要花心思我们因为前期没设计好props和事件中期重构过一次组件这个成本如果能提前规划还是可以避免的。4.2 动态路由与访问控制前端只做展示控制权限控制是前后端配合的活。后端是真正的安全屏障前端则保证界面展示与用户权限匹配也就是没有权限的菜单和按钮不要出现在页面上。我们的实现是用户登录成功后返回JWT的同时后端返回这个用户的菜单权限码列表前端拿到后通过Vue Router的addRoute方法把用户有权限的页面路由动态注册进去。路由守卫里的判断逻辑如下router.beforeEach((to, from, next) { const token localStorage.getItem(token) const userInfo JSON.parse(localStorage.getItem(userInfo) || null) if (to.meta.requiresAuth !token) { next(/login) return } if (token userInfo) { if (to.meta.permission !userInfo.permissions.includes(to.meta.permission)) { next(/403) return } } next() })这个方法的关键在于前端控制菜单和路由只是为了更好的用户体验真正的接口权限校验必须以后端为准。我们当时就遇到过有用户直接访问接口URL的场景因为前端路由做了隐藏但后端接口没有加权限码差点漏成越权漏洞。后来在复盘时把后端所有管理类接口都加了一遍权限码校验这个教训非常深刻。4.3 几个典型页面组件的落地细节首页门户采用区块式布局顶部是导航栏和搜索框中部是政策资讯列表和常见办事事项入口底部是公告通知。页面本身不难但数据请求要做好缓存和加载状态的体验。我们用的是骨架屏加异步加载首次进入显示占位骨架数据返回后渲染真实内容观感比Loading转圈好很多。办事指南页除了事项基础信息和材料清单还放了一个在线申报按钮引导用户完成申报。这里有一个产品层面的小设计材料清单按必需材料和非必需材料分了两个区块用户准备材料时更直观。前端实现上就是JSON数据渲染成两个卡片区域逻辑简单但用户体验提升明显。申报进度页后端返回申报记录和状态变更历史前端用Element Plus的Steps组件渲染成时间轴。在状态多的情况下要让当前步骤和历史步骤分别用高亮和置灰区分当时调试中发现Steps组件的active参数和实际状态码映射需要做一层转换这个转换逻辑放在utils里做了统一处理。4.4 联调阶段的效率手段与常见坑前后端联调是项目里最容易消耗时间的阶段我们后来总结了一套方法。第一个是接口文档先行用统一的接口文档工具维护后端没写完接口前端也可以按文档Mock数据进行开发联调时减少口径不一致的问题。第二个是环境统一前后端统一都走开发代理前端调后端直接用相对路径避免出现把localhost写死在代码里的问题。联调中遇到最多的坑有两个。第一个是字段格式不一致后端返回的日期是2025-03-12 10:30:00这种字符串前端直接展示没问题但要作为时间戳对比时就需要统一转换。我们在request.js里约定所有日期都以字符串返回前端用dayjs统一处理避免不同页面各写各的逻辑。第二个是数组和对象判空后端返回的数组在数据为空时一定返回空数组而不是null这在接口文档里做了严格约定前端代码就不用写一堆空值防御。5. 部署上线阶段撞上的三堵墙从环境到性能的真实排障5.1 服务器环境与部署脚本的准备部署其实不算难难的是把整个流程脚本化避免每次上线靠人工操作。我们服务器上的环境是JDK 17、MySQL 8、Redis 6、Nginx 1.24。后端用一个简单的启动脚本管理进程核心就是nohup加java -jar。前端构建产物就是dist目录Nginx指到dist目录同时配置反向代理把/api请求转发到后端端口server { listen 80; server_name demo.example.com; # 前端静态资源 root /opt/platform/dist; index index.html; # 前端路由history模式找不到文件时回退到index.html location / { 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; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; } }这里有一个连续踩坑的点history路由模式必须配置try_files回退到index.html否则用户直接访问某个子路径时Nginx会返回404。很多前后端分离项目第一次上线都栽在这里。第一次部署后测试发现首页正常但一刷新详情页就是404排查了很久才意识到是Nginx没有配置回退。5.2 排障记录一生产环境跨域报错说来有点丢人开发环境一切正常部署到生产环境后前端调用接口直接跨域报错。最开始我们怀疑是Nginx代理配错了排查半天发现代理是通的curl带token访问后端接口完全正常。问题出在哪里后来检查才发现前端代码里axios的baseURL在构建时被写成了开发环境的地址也就是说生产环境的浏览器直接跨域请求了开发地址和Nginx完全没关系。解决办法是在Vite的构建配置文件里针对不同环境做环境变量替换生产构建时baseURL自动指向生产域名下的/api路径。从那以后我们都要求构建产物里不允许出现任何localhost或者127.0.0.1这样的字面量发现一个就是一个bug。5.3 排障记录二数据库连接池被打满上线第二天运营反馈平台偶尔会出现请求卡住很慢的情况后端日志里大量报连接池获取超时的异常。一开始以为是并发太高查了监控发现峰值QPS也就几十不至于压垮配置。后来检查代码才发现我们有几个地方在循环里调用了数据库查询比如用户详情页面要查用户基本信息、角色列表、最近申报记录这三条查询是串行的虽然每个查询都很快但在循环场景下连接占用时间就长了。解决方法是两点配合一是把这些关联查询要么改成一次性联表查询要么合并成一条SQL或者用Batch查询二是给Redis加了缓存用户信息这种几乎不变的数据直接缓存数据库查询次数大幅下降。连接池参数也从默认值调到了合理范围把最大连接数调大了一些更重要的是给查询走了索引从根上减少占用时间。5.4 排障记录三文件上传超出默认限制运营上传政策封面图时遇到提示上传失败但日志里没有任何异常输出。后来打开浏览器Network面板才发现POST请求的响应是413。这是Nginx默认的client_max_body_size只有1MB造成的而后端SpringBoot同样也有默认的spring.servlet.multipart.max-file-size限制。两边都要调client_max_body_size 20m;后端则要把配置里的文件大小调大并同时设置单文件和请求总大小限制。但这里也有一个安全考虑不要一上来就调成100MB要根据业务实际需要的最大材料体积来定我们调成了20MB并限制了文件类型避免了有人利用上传接口传超大文件打满磁盘的风险。6. 项目复盘重做一次的话我会改掉这五件事6.1 需求沟通阶段必须比做的还不够现在回头看整个项目最大的遗憾不是技术选型而是需求确认阶段没有更早地让运营方和典型用户参与进来。我们前期完全靠自己想象用户在怎么用这个平台直到测试版本出来让运营试用时才发现他们期望的事项分类比我们做的分类要细得多运营希望按业务部门维度再分一层菜单这个改动虽然不大却影响了一系列页面布局和后台配置项。如果在需求阶段就准备一批业务场景故事比如一名来自省外的企业经办人第一次使用平台办理资质变更的全过程再以这个故事的视角去验证功能清单很多分歧就能提前暴露。这种用户故事驱动的需求梳理方式之后的项目我会坚持当成必选环节。6.2 设计阶段要有意识地控制技术债我们为了赶进度在代码层面留了一些后患。比如用户模块的service层里混入了消息模块的判断逻辑事项模块的工具类被放在common包里后期找起来特别费劲。这些债在项目结束后不会消失后续接手的人维护成本会很高。经验是要在代码评审环节坚持模块边界不要因为这次改动很小就随意跨模块塞代码每一次跨模块都应该是经过讨论的决策。6.3 测试用例覆盖核心链路这个项目的自动化测试覆盖其实很弱大部分靠手工点点点。上线前我们专门梳理了一批冒烟用例比如用户注册、登录、发起申报、上传材料、管理员审核、消息通知这条主链路。这套手工冒烟流程每次发版都要完整跑一遍确实能拦住大多数低级的回归问题。如果再做一个类似的项目我会把这条核心链路的关键接口至少覆盖一遍JUnit的集成测试和前端Playwright端到端测试。测试用例不是越多越好但核心业务流程必须有兜底。6.4 给后来者的五条具体建议如果让我给打算做SpringBoot加Vue这类平台项目的同学几句话我会这样说先花至少一周时间把需求文档写清楚包括功能边界、角色权限、核心流程图不要急着写代码数据库设计阶段把所有状态枚举值定好并写在文档里后端代码里不要出现魔法数字全部用常量类维护接口返回格式从一开始就统一不要在项目中期再改前端路由守卫和后端拦截器配合做权限控制只认后端的最终校验部署前在测试环境按上线流程完整走一遍包括Nginx配置和构建流水线避免把上线这事变成第一次踩坑。6.5 做这类项目的最终体会三个月时间从零把一个智慧服务平台做上线技术上其实没有什么炫酷内容Java后端的CRUD、权限、缓存、文件上传Vue前端的基础增删改查和页面展示全是基础功。但真正难的是把这些基础组件像积木一样搭成一个业务上自洽、流程上完整、用户能真正拿来办事的系统。那段时间我最大的体会是项目成功与否往往不取决于你用了多新的技术而取决于需求边界有没有划定清楚、核心流程有没有状态机支撑、前后端之间有没有统一约定。技术是手段业务才是骨架。现在这个平台已经稳定运行了一段时间运营那边也在陆续提新需求比如企业画像、经营态势统计这些偏数据的方向。我后续比较想做的是把申报审批流程再拆成更灵活的工作流引擎让运营人员不需要改代码就能调整审批节点。如果之后真的推进了我大概率还会把这些过程写成另一篇更深入的文章继续把这套实践里的经验沉淀下来。
