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