1. 為什么還要回頭寫(xiě)一個(gè)前后端分離的Demo前后端分離這個(gè)詞現(xiàn)在聽(tīng)起來(lái)已經(jīng)不算新鮮了但真正動(dòng)手從零搭一套 Vue Spring Boot 的完整項(xiàng)目很多人還是會(huì)卡在跨域、接口聯(lián)調(diào)、打包部署這幾個(gè)環(huán)節(jié)上。我這次回頭重寫(xiě)這個(gè) Demo不是為了追什么新技術(shù)而是想把這套最經(jīng)典的組合徹底捋一遍把當(dāng)年踩過(guò)的坑、繞過(guò)的彎路都整理出來(lái)給剛接觸前后端分離的朋友一個(gè)能直接抄的參考。這個(gè) Demo 的核心目標(biāo)很明確前端用 Vue 負(fù)責(zé)頁(yè)面渲染和交互后端用 Spring Boot 提供 RESTful 接口兩邊通過(guò) HTTP 請(qǐng)求通信各自獨(dú)立開(kāi)發(fā)、獨(dú)立部署。它解決的是傳統(tǒng) JSP 或 Thymeleaf 那種前后端代碼混在一起、改一個(gè)按鈕都要重新編譯整個(gè)項(xiàng)目的問(wèn)題。適合誰(shuí)看如果你已經(jīng)會(huì)一點(diǎn) Java 和 JavaScript但還沒(méi)完整搭過(guò)一個(gè)前后端分離項(xiàng)目或者你搭過(guò)但總是被跨域和接口格式搞得頭大那這篇內(nèi)容應(yīng)該能幫到你。我這次用的技術(shù)棧是 Vue 3 Vite Axios 做前端Spring Boot 3 MyBatis-Plus MySQL 做后端整體結(jié)構(gòu)不復(fù)雜但每個(gè)環(huán)節(jié)我都會(huì)把“為什么這么選”講清楚。比如為什么用 Vite 不用 Webpack為什么接口返回要統(tǒng)一封裝為什么跨域不能隨便用CrossOrigin糊弄過(guò)去。這些細(xì)節(jié)才是真正決定項(xiàng)目能不能順利跑起來(lái)的關(guān)鍵。2. 整體架構(gòu)設(shè)計(jì)與技術(shù)選型思路2.1 前后端分離到底分的是什么很多人以為前后端分離就是前端寫(xiě)頁(yè)面、后端寫(xiě)接口其實(shí)這只是表面。真正的分離體現(xiàn)在三個(gè)層面代碼分離、開(kāi)發(fā)分離、部署分離。代碼分離意味著前端項(xiàng)目和后端項(xiàng)目是兩個(gè)獨(dú)立的代碼倉(cāng)庫(kù)前端不依賴(lài)后端模板引擎后端也不關(guān)心頁(yè)面長(zhǎng)什么樣。開(kāi)發(fā)分離是指前端工程師和后端工程師可以并行開(kāi)發(fā)只要提前約定好接口文檔前端可以用 Mock 數(shù)據(jù)先跑起來(lái)。部署分離則是前端打包成靜態(tài)文件放到 Nginx 或 CDN后端打成 Jar 包跑在服務(wù)器上兩邊互不干擾。我見(jiàn)過(guò)不少項(xiàng)目號(hào)稱(chēng)前后端分離結(jié)果前端代碼里還嵌著后端返回的 HTML 片段或者后端接口直接返回頁(yè)面路徑這種就是典型的“假分離”。真正的分離要求后端只返回?cái)?shù)據(jù)通常是 JSON 格式前端拿到數(shù)據(jù)后自己決定怎么渲染。這樣做的好處是前端可以靈活替換技術(shù)棧今天用 Vue明天換 React后端完全不用動(dòng)。后端也可以同時(shí)服務(wù) Web 端、App 端、小程序端一套接口多處復(fù)用。2.2 為什么選 Vue 3 Vite 而不是其他組合Vue 3 的 Composition API 是我這次選它的主要原因。Options API 寫(xiě)多了之后邏輯分散在 data、methods、computed 里一個(gè)功能要改好幾個(gè)地方。Composition API 可以把相關(guān)邏輯寫(xiě)在一起復(fù)用起來(lái)也方便。Vite 的冷啟動(dòng)速度比 Webpack 快很多改代碼后熱更新幾乎是秒級(jí)開(kāi)發(fā)體驗(yàn)提升明顯。Axios 就不用說(shuō)了攔截器機(jī)制用來(lái)統(tǒng)一處理 token 和錯(cuò)誤提示非常順手。后端選 Spring Boot 3 是因?yàn)樗鼘?duì) Java 17 支持更好而且 Spring Boot 的自動(dòng)配置讓整合 MyBatis-Plus、MySQL 驅(qū)動(dòng)這些變得很簡(jiǎn)單。MyBatis-Plus 相比原生 MyBatis 省去了大量 XML 配置簡(jiǎn)單的增刪改查直接用BaseMapper就能搞定復(fù)雜查詢(xún)?cè)賹?xiě)自定義 SQL。MySQL 選 8.0 版本主要是為了支持 JSON 字段類(lèi)型和更好的性能。2.3 項(xiàng)目目錄結(jié)構(gòu)怎么劃分才合理前端項(xiàng)目我習(xí)慣按功能模塊劃分目錄而不是按文件類(lèi)型。比如src/views下面放頁(yè)面組件src/components放公共組件src/api放接口請(qǐng)求src/utils放工具函數(shù)。這樣找文件的時(shí)候直接按業(yè)務(wù)模塊找不用在components里翻半天。后端項(xiàng)目按經(jīng)典的三層架構(gòu)分controller層負(fù)責(zé)接收請(qǐng)求和返回響應(yīng)service層處理業(yè)務(wù)邏輯mapper層操作數(shù)據(jù)庫(kù)。實(shí)體類(lèi)放在entity包數(shù)據(jù)傳輸對(duì)象放在dto包視圖對(duì)象放在vo包。這里有個(gè)經(jīng)驗(yàn)不要把entity直接返回給前端。數(shù)據(jù)庫(kù)實(shí)體可能包含密碼、刪除標(biāo)記這些敏感字段直接返回會(huì)有安全隱患。我一般用vo類(lèi)專(zhuān)門(mén)做返回?cái)?shù)據(jù)的封裝只暴露前端需要的字段。比如用戶(hù)表里有password字段但返回給前端的UserVO里只有id、username、nickname這樣既安全又清晰。3. 后端核心細(xì)節(jié)與實(shí)操要點(diǎn)3.1 Spring Boot 項(xiàng)目初始化與依賴(lài)配置用 Spring Initializr 生成項(xiàng)目骨架的時(shí)候我勾選了 Spring Web、MyBatis Framework、MySQL Driver、Lombok 這幾個(gè)依賴(lài)。Lombok 一定要加不然實(shí)體類(lèi)的 getter、setter 寫(xiě)起來(lái)太啰嗦。pom.xml里我額外加了 MyBatis-Plus 的 starter版本選 3.5.5 以上對(duì) Spring Boot 3 的支持更穩(wěn)定。dependency groupIdcom.baomidou/groupId artifactIdmybatis-plus-boot-starter/artifactId version3.5.5/version /dependency配置文件application.yml里主要配三塊數(shù)據(jù)源、MyBatis-Plus、服務(wù)器端口。數(shù)據(jù)源用 HikariCPSpring Boot 默認(rèn)就是它性能比 Druid 好一些。MyBatis-Plus 要配mapper-locations指向 XML 文件位置還要開(kāi)map-underscore-to-camel-case這樣數(shù)據(jù)庫(kù)的user_name字段能自動(dòng)映射到 Java 的userName屬性。spring: datasource: url: jdbc:mysql://localhost:3306/demo_db?useUnicodetruecharacterEncodingutf8serverTimezoneAsia/Shanghai username: root password: 123456 driver-class-name: com.mysql.cj.jdbc.Driver mybatis-plus: mapper-locations: classpath:mapper/*.xml configuration: map-underscore-to-camel-case: true log-impl: org.apache.ibatis.logging.stdout.StdOutImpl server: port: 8080注意serverTimezone一定要配不然 MySQL 8.0 連接時(shí)會(huì)報(bào)時(shí)區(qū)錯(cuò)誤。log-impl配成 StdOutImpl 可以在控制臺(tái)看到執(zhí)行的 SQL調(diào)試的時(shí)候非常有用但上線(xiàn)前記得關(guān)掉不然日志會(huì)刷屏。3.2 統(tǒng)一接口返回格式的設(shè)計(jì)后端接口返回的數(shù)據(jù)格式必須統(tǒng)一不然前端處理起來(lái)會(huì)很亂。我定義了一個(gè)Result類(lèi)包含code、message、data三個(gè)字段。code用 200 表示成功其他值表示各種錯(cuò)誤。message放提示信息data放實(shí)際數(shù)據(jù)。這樣前端只需要判斷code是不是 200就能知道請(qǐng)求成功還是失敗。Data public class ResultT { private Integer code; private String message; private T data; public static T ResultT success(T data) { ResultT result new Result(); result.setCode(200); result.setMessage(操作成功); result.setData(data); return result; } public static T ResultT error(String message) { ResultT result new Result(); result.setCode(500); result.setMessage(message); return result; } }這里有個(gè)細(xì)節(jié)data字段用了泛型這樣返回不同類(lèi)型的數(shù)據(jù)時(shí)不用強(qiáng)轉(zhuǎn)。比如ResultUserVO和ResultListUserVO都能用同一個(gè)類(lèi)。另外我建議加一個(gè)全局異常處理器用RestControllerAdvice捕獲所有異常統(tǒng)一返回Result.error()這樣前端永遠(yuǎn)不用處理 500 頁(yè)面所有錯(cuò)誤都是 JSON 格式。3.3 跨域問(wèn)題的正確處理方式跨域是前后端分離繞不開(kāi)的坎。瀏覽器同源策略規(guī)定協(xié)議、域名、端口三者只要有一個(gè)不同就算跨域。前端跑在localhost:5173后端跑在localhost:8080端口不同所以跨域。很多人圖省事直接在 Controller 上加CrossOrigin但這樣每個(gè)接口都要加而且生產(chǎn)環(huán)境可能還有 Nginx 代理配置會(huì)亂。我推薦用全局配置類(lèi)來(lái)處理跨域在config包下建一個(gè)CorsConfig類(lèi)實(shí)現(xiàn)WebMvcConfigurer接口重寫(xiě)addCorsMappings方法。這樣所有接口自動(dòng)支持跨域不用一個(gè)個(gè)加注解。Configuration public class CorsConfig implements WebMvcConfigurer { Override public void addCorsMappings(CorsRegistry registry) { registry.addMapping(/**) .allowedOriginPatterns(*) .allowedMethods(GET, POST, PUT, DELETE, OPTIONS) .allowedHeaders(*) .allowCredentials(true) .maxAge(3600); } }注意allowedOriginPatterns和allowedOrigins的區(qū)別在于前者支持通配符后者在allowCredentials為 true 時(shí)不能用*。所以如果你要傳 Cookie 或 Token必須用allowedOriginPatterns。maxAge設(shè)置預(yù)檢請(qǐng)求的緩存時(shí)間3600 秒意味著一天內(nèi)同一個(gè)跨域請(qǐng)求不用重復(fù)發(fā) OPTIONS 預(yù)檢能減少請(qǐng)求次數(shù)。4. 前端核心細(xì)節(jié)與實(shí)操要點(diǎn)4.1 Vue 3 項(xiàng)目搭建與 Axios 封裝用npm create vitelatest創(chuàng)建項(xiàng)目選 Vue 模板然后裝 Axios 和 Vue Router。Axios 我習(xí)慣封裝一個(gè)request.js在里面創(chuàng)建實(shí)例、配置基礎(chǔ)路徑、設(shè)置請(qǐng)求攔截器和響應(yīng)攔截器。請(qǐng)求攔截器用來(lái)統(tǒng)一加 Token響應(yīng)攔截器用來(lái)統(tǒng)一處理錯(cuò)誤碼。import axios from axios const request axios.create({ baseURL: http://localhost:8080, timeout: 10000 }) request.interceptors.request.use( config { const token localStorage.getItem(token) if (token) { config.headers.Authorization Bearer ${token} } return config }, error Promise.reject(error) ) request.interceptors.response.use( response { const res response.data if (res.code ! 200) { alert(res.message || 請(qǐng)求失敗) return Promise.reject(new Error(res.message)) } return res.data }, error { alert(網(wǎng)絡(luò)異常請(qǐng)稍后重試) return Promise.reject(error) } ) export default request這樣封裝之后頁(yè)面里調(diào)用接口只需要request.get(/user/list)返回的已經(jīng)是data字段的內(nèi)容不用每次寫(xiě)res.data.data。錯(cuò)誤提示也統(tǒng)一在攔截器里處理了頁(yè)面代碼干凈很多。4.2 接口請(qǐng)求的模塊化管理不要把接口請(qǐng)求散落在各個(gè)組件里我習(xí)慣在src/api目錄下按模塊建文件。比如user.js放用戶(hù)相關(guān)的接口article.js放文章相關(guān)的接口。每個(gè)文件里導(dǎo)出具體的請(qǐng)求函數(shù)組件里直接 import 調(diào)用。// src/api/user.js import request from /utils/request export function getUserList(params) { return request.get(/user/list, { params }) } export function addUser(data) { return request.post(/user/add, data) } export function updateUser(data) { return request.put(/user/update, data) } export function deleteUser(id) { return request.delete(/user/delete/${id}) }這樣做的好處是接口路徑集中管理改路徑的時(shí)候只改一個(gè)地方。而且函數(shù)名有語(yǔ)義getUserList比直接寫(xiě)request.get(/user/list)更容易理解。如果后端接口有變動(dòng)前端只需要改api目錄下的文件組件代碼不用動(dòng)。4.3 頁(yè)面路由與權(quán)限控制Vue Router 用createRouter創(chuàng)建實(shí)例路由模式選createWebHistory這樣 URL 里沒(méi)有#號(hào)看起來(lái)更干凈。路由配置里可以加meta字段標(biāo)記哪些頁(yè)面需要登錄然后在全局前置守衛(wèi)里判斷。router.beforeEach((to, from, next) { const token localStorage.getItem(token) if (to.meta.requiresAuth !token) { next(/login) } else { next() } })注意前端路由守衛(wèi)只是提升用戶(hù)體驗(yàn)不能作為安全屏障。真正的權(quán)限校驗(yàn)必須放在后端每個(gè)接口都要驗(yàn)證 Token 是否有效、用戶(hù)是否有權(quán)限訪(fǎng)問(wèn)該資源。前端守衛(wèi)可以被繞過(guò)后端校驗(yàn)才是最后一道防線(xiàn)。5. 前后端聯(lián)調(diào)與常見(jiàn)問(wèn)題排查5.1 接口聯(lián)調(diào)的標(biāo)準(zhǔn)流程聯(lián)調(diào)的時(shí)候我習(xí)慣先用 Postman 或 Apifox 測(cè)后端接口確保單獨(dú)跑沒(méi)問(wèn)題。然后再到前端頁(yè)面里調(diào)如果前端報(bào)錯(cuò)先看瀏覽器控制臺(tái)的 Network 面板確認(rèn)請(qǐng)求 URL、請(qǐng)求方法、請(qǐng)求頭、請(qǐng)求體是否正確。常見(jiàn)的問(wèn)題有請(qǐng)求方法寫(xiě)錯(cuò)了比如后端要 POST前端發(fā)了 GET、參數(shù)格式不對(duì)后端要 JSON前端發(fā)了 form-data、請(qǐng)求頭缺少 Content-Type。我一般會(huì)在后端 Controller 里加日志打印接收到的參數(shù)這樣能快速判斷是前端沒(méi)傳對(duì)還是后端沒(méi)接住。前端也可以在 Axios 攔截器里打印請(qǐng)求配置兩邊對(duì)照著看問(wèn)題很快就能定位。5.2 常見(jiàn)問(wèn)題速查表問(wèn)題現(xiàn)象可能原因排查方法解決方案瀏覽器報(bào) CORS 錯(cuò)誤后端未配置跨域看控制臺(tái)是否有Access-Control-Allow-Origin相關(guān)提示添加全局跨域配置類(lèi)請(qǐng)求返回 404接口路徑不對(duì)Network 面板看請(qǐng)求 URL檢查baseURL和接口路徑拼接請(qǐng)求返回 401Token 無(wú)效或未傳看請(qǐng)求頭是否有 Authorization檢查登錄邏輯和攔截器請(qǐng)求返回 500后端代碼異常看后端控制臺(tái)堆棧信息根據(jù)異常信息修復(fù)代碼數(shù)據(jù)返回但頁(yè)面不渲染字段名不匹配對(duì)比接口返回字段和頁(yè)面綁定字段統(tǒng)一字段命名或做映射跨域預(yù)檢失敗OPTIONS 請(qǐng)求被攔截Network 面板看是否有 OPTIONS 請(qǐng)求后端放行 OPTIONS 方法5.3 我踩過(guò)的幾個(gè)坑第一個(gè)坑是RequestBody和RequestParam混用。前端發(fā) JSON 數(shù)據(jù)時(shí)后端必須用RequestBody接收而且只能有一個(gè)。如果同時(shí)想接收路徑參數(shù)和 JSON 體路徑參數(shù)用PathVariableJSON 體用RequestBody兩者不沖突。我當(dāng)初把RequestBody和RequestParam寫(xiě)在一個(gè)方法里結(jié)果一直報(bào) 400 錯(cuò)誤排查了半天才發(fā)現(xiàn)是注解用錯(cuò)了。第二個(gè)坑是日期格式。Java 的LocalDateTime默認(rèn)序列化成數(shù)組或時(shí)間戳前端拿到后沒(méi)法直接顯示。解決辦法是在字段上加JsonFormat(pattern yyyy-MM-dd HH:mm:ss)或者在配置文件里全局配置日期格式。我建議用全局配置省得每個(gè)字段都加注解。spring: jackson: date-format: yyyy-MM-dd HH:mm:ss time-zone: GMT8第三個(gè)坑是打包部署后接口 404。開(kāi)發(fā)環(huán)境前端跑在 5173 端口后端跑在 8080 端口跨域配置生效。但打包后前端靜態(tài)文件放到 Nginx后端還是 8080這時(shí)候如果前端請(qǐng)求的baseURL還是localhost:8080用戶(hù)瀏覽器訪(fǎng)問(wèn)的是 Nginx 的地址請(qǐng)求就會(huì)發(fā)到用戶(hù)自己的電腦上自然 404。解決辦法是在 Nginx 里配置反向代理把/api開(kāi)頭的請(qǐng)求轉(zhuǎn)發(fā)到后端服務(wù)。location /api/ { proxy_pass http://localhost:8080/; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; }這樣前端baseURL改成/api請(qǐng)求先到 Nginx再由 Nginx 轉(zhuǎn)發(fā)給后端就不存在跨域問(wèn)題了。這也是生產(chǎn)環(huán)境推薦的做法比后端配跨域更安全、更靈活。6. 項(xiàng)目打包與部署的實(shí)操記錄6.1 前端打包與靜態(tài)資源優(yōu)化前端打包用npm run buildVite 會(huì)把代碼壓縮、分割、生成帶哈希的文件名。打包產(chǎn)物在dist目錄里面是index.html和assets文件夾。我一般會(huì)把dist里的文件傳到 Nginx 的html目錄然后配置 Nginx 的root指向這個(gè)目錄。Vite 默認(rèn)的打包配置已經(jīng)夠用但有幾個(gè)地方可以?xún)?yōu)化。比如build.rollupOptions.output.manualChunks可以把第三方庫(kù)單獨(dú)打包避免業(yè)務(wù)代碼更新后用戶(hù)還要重新下載 Vue、Axios 這些不變的庫(kù)。還有build.chunkSizeWarningLimit可以調(diào)大避免打包時(shí)提示文件過(guò)大。// vite.config.js export default defineConfig({ build: { chunkSizeWarningLimit: 1500, rollupOptions: { output: { manualChunks: { vendor: [vue, vue-router, axios] } } } } })6.2 后端打包與運(yùn)行后端用 Maven 打包mvn clean package生成可執(zhí)行的 Jar 文件。運(yùn)行的時(shí)候用java -jar xxx.jar可以加--spring.profiles.activeprod指定生產(chǎn)環(huán)境配置。生產(chǎn)環(huán)境的配置文件里數(shù)據(jù)庫(kù)密碼、日志級(jí)別這些要和開(kāi)發(fā)環(huán)境區(qū)分開(kāi)。我習(xí)慣把配置文件分成application-dev.yml和application-prod.yml主配置文件里用spring.profiles.active指定當(dāng)前環(huán)境。這樣本地開(kāi)發(fā)用 dev服務(wù)器部署用 prod互不干擾。生產(chǎn)環(huán)境的日志級(jí)別調(diào)成 WARN避免 INFO 日志太多占滿(mǎn)磁盤(pán)。6.3 部署后的驗(yàn)證清單部署完成后我一般按這個(gè)清單逐項(xiàng)驗(yàn)證前端頁(yè)面能否正常打開(kāi)、靜態(tài)資源是否加載成功看 Network 面板有沒(méi)有 404、登錄接口是否正常返回 Token、帶 Token 的請(qǐng)求是否通過(guò)鑒權(quán)、數(shù)據(jù)庫(kù)增刪改查是否生效、Nginx 反向代理是否配置正確。每一項(xiàng)都確認(rèn)沒(méi)問(wèn)題才算部署完成。提示部署后如果頁(yè)面白屏先看瀏覽器控制臺(tái)有沒(méi)有報(bào)錯(cuò)。常見(jiàn)原因是靜態(tài)資源路徑不對(duì)比如 Vite 默認(rèn)的base是/如果部署在子目錄下需要改成./或具體子路徑。還有可能是 Nginx 的try_files沒(méi)配刷新頁(yè)面后 404需要加try_files $uri $uri/ /index.html。7. 這個(gè) Demo 還能怎么擴(kuò)展這套基礎(chǔ)框架跑通之后可以往上加的東西很多。比如加 JWT 做無(wú)狀態(tài)鑒權(quán)把 Token 存到 Redis 里做黑名單管理加 Spring Security 做細(xì)粒度權(quán)限控制區(qū)分管理員和普通用戶(hù)加 Swagger 或 Knife4j 自動(dòng)生成接口文檔前后端對(duì)接更高效加 Redis 緩存熱點(diǎn)數(shù)據(jù)減輕數(shù)據(jù)庫(kù)壓力加消息隊(duì)列處理異步任務(wù)比如發(fā)送郵件、生成報(bào)表。前端方面可以加 Pinia 做狀態(tài)管理把用戶(hù)信息、權(quán)限列表這些全局狀態(tài)統(tǒng)一管理加 Element Plus 或 Ant Design Vue 做 UI 組件庫(kù)頁(yè)面開(kāi)發(fā)速度能快不少加 ESLint 和 Prettier 做代碼規(guī)范團(tuán)隊(duì)協(xié)作時(shí)風(fēng)格統(tǒng)一。我個(gè)人在實(shí)際操作中的體會(huì)是不要一上來(lái)就把所有東西都堆進(jìn)去。先把最基礎(chǔ)的增刪改查跑通把跨域、接口封裝、異常處理這些基礎(chǔ)設(shè)施搭好后面加功能就是水到渠成的事。我見(jiàn)過(guò)太多項(xiàng)目一開(kāi)始就上微服務(wù)、上消息隊(duì)列結(jié)果基礎(chǔ)功能還沒(méi)跑通光環(huán)境問(wèn)題就耗了一兩周。先把單體能跑通再考慮擴(kuò)展這個(gè)順序不能亂。最后再分享一個(gè)小技巧接口文檔一定要在開(kāi)發(fā)前就定好用 Apifox 或 Swagger 寫(xiě)清楚每個(gè)接口的路徑、方法、參數(shù)、返回格式。前后端并行開(kāi)發(fā)的時(shí)候前端用 Mock 數(shù)據(jù)先跑頁(yè)面后端按文檔實(shí)現(xiàn)接口聯(lián)調(diào)的時(shí)候基本一次過(guò)。我試過(guò)幾次沒(méi)寫(xiě)文檔直接口頭溝通結(jié)果字段名對(duì)不上、參數(shù)類(lèi)型不對(duì)改來(lái)改去浪費(fèi)的時(shí)間比寫(xiě)文檔多得多。