做了差不多两个月的项目终于收尾了趁热打铁把这段前后端分离改造的经验整理一篇复盘。这个项目的核心任务很明确把原来耦合在服务端模板里的老系统拆成前后端分离架构重新梳理接口层顺手解决掉一批历史遗留的性能问题。如果你正准备做类似的架构改造、或者想了解接口编写过程中那些文档里不会写清楚的细节这篇内容应该能帮你少踩几个坑。先说结论前后端分离这个方案本身不新鲜但真正落地的时候最难的从来不是技术选型而是边界划分和细节规范。接口写得好不好、优化有没有效果全看前期设计钻得够不够细。下面我把整个过程中的设计思路、接口编写的核心要点、以及优化阶段的实操记录按顺序完整过一遍。1. 前后端分离不只是把代码拆开而是重新定义协作方式很多人一提前后端分离第一反应就是“前端用Vue后端出接口完事”。真这么想就错了。前后端分离的本质是一次职责边界的重组它改变的不只是代码仓库的分布方式更牵扯到团队协作流程、环境部署策略、甚至错误排查的思路。1.1 为什么必须拆老项目到底卡在哪里这次改造的起点是一个跑了四五年的老系统。早先的开发模式是典型的服务端渲染Java写Controller返回的却是拼好的HTML页面模板引擎里塞着大量业务判断前端说想改个按钮样式都得后端同学改模板再重新部署。数据交互基本靠Ajax在页面里零散地写接口没有统一规范参数命名全看个人心情。项目维护到后期每次需求变更都像在一团乱麻里找线头。拆成前后端分离之后最直观的改变是前端团队和后端团队彻底解耦了。前端本地跑Node开发服务器后端只提供纯数据接口页面渲染完全由前端控制。原先那种“改个样式还要等后端发版”的窘境彻底消失前后端各自独立开发、独立部署、独立扩容只要接口契约不变两边可以按自己的节奏迭代。从技术层面拆解这个改造的核心收益有三块前后端通过HTTP接口通信边界清晰职责单一代码可维护性明显提升前后端可以并行开发后端写完接口定义和Mock数据前端就能开工不需要等对方代码完成部署弹性更好。后端接口服务可以水平扩容前端静态资源扔CDN高并发下互不拖累。1.2 工程结构怎么搭才算合理改造第一步是重新设计工程结构。后端我用了Spring Boot按模块分包controller层只做参数接收和响应封装service层管业务逻辑mapper层管数据库交互三层划分严格禁止越层调用。前端选了Vue Vite目录按views、components、api、store、utils拆分其中api目录单独维护所有请求方法和接口路径做到全项目只有这一个地方能看到URL。这个结构的好处是新成员接手项目时看代码的成本极低。api目录就是一份“活的接口清单”store里就是全局状态哪个页面用到什么数据一眼就能看出来。比起之前那种业务逻辑散落在模板和Controller里、靠人肉记忆维护的老项目这种结构化带来的效率提升是肉眼可见的。另一个容易被忽略的点是环境配置。项目拆分开之后本地开发、测试环境、生产环境各走各的配置。前端开发服务器配了proxy代理把/api前缀的请求转发到后端本地端口绕开跨域生产环境用Nginx托管静态文件并反向代理后端接口。这套配置在实际开发中省了我大量时间因为本地联调不再需要纠结CORS策略真正需要处理跨域的地方集中到了生产网关层。1.3 Token与状态管理分离后绕不开的鉴权方案前后端分离后原来的Session方案基本不可用了因为服务端不再维护页面状态Session跨服务共享成本太高。这次改造直接用JWT。登录成功后后端签发Token返回前端前端存在localStorage请求时塞进Authorization头里后端通过拦截器校验。这里有个关键细节很多人踩坑Token存localStorage虽然方便但存在XSS风险。理想方案是存内存变量刷新会丢存cookie又怕CSRF。这次项目我采用的是双Token机制短期Token放内存刷新Token放HttpOnly Cookie里既兼顾了刷新逻辑又降低了泄露面。这个方案实现起来多花一点功夫但安全收益非常值。2. 接口编写从“能用”进化到“好用”的关键细节接口是这个项目的中枢神经前后端所有数据交换都走它。写接口这件事表面上是写几个方法返回JSON实际上设计规范、边界划分、异常处理、文档同步每一个环节都能决定项目后期的协作体验。这一章我把接口编写过程中最核心的几个决策仔细说说。2.1 RESTful接口设计的取舍RESTful设计听起来是老生常谈但真正落到每个接口上取舍点非常多。这次项目统一遵守了这些原则资源用名词复数操作通过HTTP方法体现比如GET /orders查列表、POST /orders创建订单、DELETE /orders/{id}删除订单。状态码也严格区分200正常、201创建成功、400参数错误、401未认证、403无权限、404资源不存在、500系统异常。实际开发中有个容易起争执的点资源路径的嵌套深度。有人喜欢GET /users/123/orders这种嵌套风格我这次更倾向扁平化用户和订单分开通过查询参数关联。原因是嵌套层级过深会让接口复用性变差哪天不需要用户维度查订单了这个接口就废了。扁平化配上清晰的查询参数接口更灵活。分页参数也做了统一约定page当前页码、pageSize每页条数返回结构包含总记录数total和列表list两部分。这个结构看着简单但很多人会漏掉total害得前端翻不了页。2.2 统一响应体一个容易被低估的设计这次项目强制要求所有接口返回统一结构{ code: 0, message: success, data: { list: [], total: 100 } }code为0表示成功非0表示失败。失败时message携带给用户看的信息data一般为null。这套结构的前期沟通成本不高但长期收益巨大前端可以在axios拦截器里统一判断code成功走成功回调失败直接弹提示框业务代码里不再需要一堆冗余的if判断。错误码分级也做了详细规划1xxx参数类错误提示客户端请求参数不合法2xxx业务类错误比如库存不足、订单状态不可操作3xxx权限类错误未登录、Token过期、无操作权限5xxx系统异常代码Bug、数据库异常。错误码设计的核心是方便排查。如果前后端联调时弹一个500blank页面你得去翻日志才知道发生了什么但如果错误码直接告诉你“订单编号不存在”问题瞬间定位。别小看这个细节它直接影响线上故障的响应速度。2.3 鉴权与接口安全容易出事的底层环节接口鉴权这次使用了JWT双Token方案短期Token有效期2小时放在前端内存刷新Token有效期7天放在HttpOnly Cookie里用于短期Token过期后静默续期。这里最核心的逻辑是刷新接口和登录接口必须在请求拦截器里做白名单避免死循环。接口幂等性也是一个绕不开的坑。拿支付回调举例子用户重复点击提交按钮会造成重复扣款这是绝对不允许的。我在写创建订单、支付回调这类接口时让前端生成一个requestId幂等键后端在Redis里检查是否处理过相同requestId没处理过才放行并将请求标记为已处理。这样即使前端因为网络原因重试了10次后端也只生效一次。参数校验放Controller层还是很必要的不能嫌麻烦。JSR 303注解就够用NotNull、Size、Pattern这些标在DTO字段上参数一进来就挡掉大部分脏数据。这条我建议不管项目大小都做上接口入口干干净净业务逻辑里能省掉成千上万行防御性判断。2.4 接口文档与Mock并行开发的核心支撑前后端并行开发能不能顺利推进关键在接口文档。Swagger/OpenAPI是自动生成路由的方式虽然能随代码更新但对拼装细节的描述偏弱。这次项目我额外用了一套YApi作为接口管理平台手动定义接口路径、请求参数、返回示例。Mock数据的功能也很重要。后端还没实现接口时YApi可以按契约自动生成Mock数据前端拿Mock数据先做页面渲染等后端接口真正就绪后再把前端请求基地址切回真实环境。这个协作方式让前后端互相等待的时间几乎降到了零整个开发周期至少快了三分之一。3. 其他优化从慢SQL到首屏加载的一揽子工程接口和架构改造完成之后项目进入优化阶段。优化的范围很宽数据库慢查询、缓存策略、前端加载速度、接口响应效率每一块都有很多可以挖的地方。我按优先级从底向上把这次实际落地并产生明显效果的优化手段逐一说一遍。3.1 慢SQL排查与索引优化复盘优化阶段首先要解决的是数据库层的性能问题。系统里几个查询接口响应超过3秒这在用户侧已经明显能感知到卡顿。排查第一个动作是开启MySQL慢查询日志SET GLOBAL slow_query_log ON; SET GLOBAL long_query_time 1;把所有执行超过1秒的SQL记录下来然后针对每一条执行EXPLAIN分析执行计划。最后发现绝大多数慢SQL的根因是没走索引或者索引失效。典型的几种索引失效场景这次全部遇到了对索引列用了函数运算比如WHERE DATE(create_time) 2025-01-01索引直接失效改成范围查询create_time ? AND create_time ?模糊查询LIKE %关键词%前置百分号导致索引失效这个场景只能用全文索引或者搜索引擎兜底OR条件中某一列未加索引MySQL优化器干脆放弃走索引改写成两个查询再用UNION ALL拼接。除了修索引我顺手优化了几个查询逻辑的改造点大表关联查询拆成多次单表查询在应用层做数据组装排序字段如果选择性很高直接建联合索引(where字段, order字段)避免Using filesort。改造完之后的实测结果最慢的接口从3.2秒降到400毫秒左右效果非常明显。3.2 缓存策略与数据一致性数据库扛住了之后还有一类高频读接口需要从缓存层继续加速。这次统一用Redis做缓存层按业务模块区分key前缀比如用户信息user:info:{id}、商品详情product:detail:{id}。对于访问量极高且实时性要求不高的场景比如首页推荐位和商品列表直接做一个定时任务主动刷新缓存查接口只读缓存。缓存更新这块我这次选了Cache Aside模式更新数据库时先删缓存再更新数据库下次读请求触发缓存重建。这个模式实现简单但存在缓存和数据库短暂不一致的时间窗口。更精细的做法是延迟双删先删缓存再更新数据库隔几百毫秒再删一次缓存把并发窗口期造成的脏数据概率降到最低。实际项目中如果业务对一致性要求很高应该考虑数据变更发消息队列消费者拿到消息再主动更新缓存不过这次项目的业务容忍度尚可延迟双删够用了。另外缓存击穿、穿透、雪崩这三个经典场景在项目里也都做了防护穿透查询数据库结果为空时在缓存里写一个空值并设置短过期时间比如60秒避免恶意请求打到数据库击穿热点key并发查询时用分布式锁控制只有一个线程去重建缓存其他线程等待雪崩缓存过期时间不用固定值加上随机偏移比如60到180秒随机防止大范围key同时过期。这三板斧做完后数据库的查询量肉眼可见地降低了高峰期CPU和连接数都平稳很多。3.3 前端加载速度与渲染性能优化接口快了页面加载速度的瓶颈就转移到了前端。拆包是第一优先级原先Vite打包后一个chunk两兆多首屏加载要好几秒。这次用动态导入(() import(/views/Order.vue))配合路由懒加载把每个页面切成独立chunk第三方库单独拆包利用浏览器缓存长期复用。改造首屏体积直接从2MB缩到500KB以内空白等待时间大幅缩短。静态资源的加载也做了优化图片统一上CDN按尺寸压缩小图标合进字体图标或雪碧图对于超长列表页面比如订单列表、日志列表用了虚拟滚动组件代替全量渲染DOM节点数量直接少了一个数量级滚动流畅度提升非常明显。还有一个小而实用的优化是HTTP请求合并。之前前端为了拼一个页面要串行发5个接口有时还会重复请求同一个接口。这次在请求层做了一个轻量级合并同一时间窗口内相同参数的GET请求自动合并成一个重复的返回值共享同一个Promise。看起来改动不大但网络往返次数减了不少低网速场景的体验改善很明显。3.4 接口层的传输性能调优传输层的优化容易被忽略但收益非常直接。接口响应体开启Gzip压缩原来传输体积能压到原来的三分之一。如果条件允许升级HTTP/2之后多路复用能彻底解决HTTP/1.x的队头阻塞问题这次改造后我把Nginx配置升级到HTTP/2手感和HTTP/1.1差别很大。还有一类场景要主动改接口设计。列表页如果只是展示概要信息那接口返回字段就不应该包含冗长的大文本字段。这次我专门增加了一批摘要接口和详情接口分开返回。同样的列表请求数据量从几十KB降到几KB渲染时间指数级下降。对于耗时比较长的操作比如导出Excel、批量发送消息用同步请求硬等容易把连接池占满改成异步任务加状态查询的架构更合理。客户端提交请求后立即返回任务ID后台线程池执行任务前端轮询任务状态完成后再拉取结果。体验上虽然交互复杂了一点但系统吞吐量提升了非常多。4. 生产环境实战记录那些最容易翻车的坑优化做完之后联调测试阶段也踩了不少坑。这些坑单看任何一个都不大但串在一起如果没处理好完全可以把工时翻倍。4.1 跨域问题——第一个拦路虎前后端分离后本地前端是http://localhost:5173后端是http://localhost:8080浏览器的同源策略直接拦住请求。解决方式是开发环境前端配Vite proxy代理生产环境Nginx反向代理把/api路径转发到后端服务。这里有个经验开发环境和生产环境的跨域策略必须尽可能保持一致否则前端在本地调试得好好的一上测试环境就报跨域错非常折磨人。4.2 Token过期与并发刷新双Token机制上线后遇到了一个典型问题用户操作比较频繁时短期Token过期那刻页面上的多个请求同时返回401。如果每个请求都独立判断401并去刷新Token就会出现并发刷新刷新Token被多次使用直接失效。解决办法是在axios拦截器里做并发刷新处理第一个请求遇到401时发起刷新请求期间其他请求的401全部先挂起在队列里等刷新完成后统一重放。实现大概要几十行代码但能根治401风暴这是生产环境必踩的坑之一。这个逻辑写成核心工具后几乎没再遇到Token相关的登录失效问题。4.3 连接池配置与数据库连接耗尽升级过程中有一阵子系统频繁报“数据库连接池耗尽”的错Connection is not available。排查发现罪魁祸首是一组没有正确设置超时时间的慢查询加上某些特殊的业务路径把数据库连接拿走后长时间不归还。优化措施有三个给HikariCP设置合理的maximumPoolSize和connectionTimeout给代码里的查询统一配置只读事务并确保finally关闭连接用Spring声明事务后其实会自动管理但要注意不要在函数里手动打开连接配合上一节说的慢SQL优化连接池占用基本降下来了。4.4 一个典型慢接口的完整排查案例拿一个印象最深的排查案例收尾吧。现象是运营后台的订单列表页点一下要5秒才出数据数据库CPU直接拉满。排查链条大概是这样的先看慢SQL日志发现一条订单表大范围JOIN十个表的查询耗时4秒再看EXPLAIN发现关联表中有一个表的驱动顺序反了MySQL选错了执行计划大量数据在临时表里排序接着看接口代码发现前端一次请求后端循环查了数十次数据库补齐明细数据没用批量查询最后看索引发现order_status和create_time都有单列索引但组合起来无法高效过滤需要建联合索引。修复方式重写SQL把JOIN数量压到三个以内关联字段统一加索引明细查询改成批量一次性查出再在内存里组装给高频筛选条件建联合索引(order_status, create_time)。修完再测接口耗时从5秒降到200毫秒以内。这次排查给我的启发特别深慢接口极少是单一原因造成的绝大多数是多层性能问题叠加在一起。排查的时候要一层层剥洋葱没有任何一步可以跳过。个人实操心得沉淀几条比代码更重要的原则整个项目做下来最深的感受是架构改造这件事有一个正确的渐进式节奏。你不可能让业务暂停一个月把所有系统推到重来。我这次的做法是先划出最小可用的前后端边界把登录体系和核心链路走通再逐步迁移周边功能最后统一做性能优化。这个节奏既保证了核心链路的稳定性又让团队在迁移中不断积累经验比一次性重写靠谱太多。接口设计上的心得也很明确统一比其他更重要。RESTful规范、响应体结构、错误码分级、参数命名这些约定越早确定越好一旦团队养成习惯后期修改的成本极高。宁可前期多开两次会敲定细节也不要上线后因为规范不一致反复补丁。优化阶段的体会是性能优化永远是先测量再动手。慢日志、链路追踪、前端Performance面板这些工具数据先跑一遍定位真正的瓶颈再动手改。很多人一上来就改代码换框架结果改了半个月发现瓶颈根本不在那儿白折腾。最后再分享一个小技巧接口变更一定要有版本意识。就算内部系统接口也不是说改就改的。在URL路径里带版本号比如/api/v1/orders一旦出问题可以先让客户端降级到旧版本而不是逼着前端连夜发版。这个习惯在所有规模的项目里都值得养起来。