簡介一份面向初中級開發(fā)者的前后端分離實戰(zhàn)資源基于Vue 3與Element Plus構(gòu)建前端界面后端采用Spring Boot 3并整合Spring Security、JWT、Redis及文件上傳下載等常用能力適合希望快速掌握企業(yè)級項目搭建流程的學習者。資源共2000個文件其中以1811個JavaScript文件為主輔以Java、JSON、XML及SQL腳本分別對應前端頁面邏輯、后端服務代碼、配置文件與數(shù)據(jù)庫表結(jié)構(gòu)壓縮包整體22.59MB便于下載與檢索。目前已有98人學習可作為從零搭建VueSpringBoot項目的參考模板。除核心源碼外還包含數(shù)據(jù)庫設計、接口設計和安全性設計思路能夠幫助讀者理解JWT認證機制、Redis緩存應用、文件傳輸實現(xiàn)等關鍵環(huán)節(jié)具備較強的實戰(zhàn)參考價值。1. 項目概述與整體設計1.1 這個項目到底在做什么說句實在話前后端分離這個詞已經(jīng)被念叨了好幾年但真到了自己動手從零搭一個 Vue SpringBoot 項目的時候不少朋友還是會被各種細節(jié)卡住。這個項目本身并不復雜——前端用 Vue 3 Vite后端用 SpringBoot 2.7 MyBatis-Plus實現(xiàn)一套最典型的用戶登錄注冊 數(shù)據(jù)列表查詢 文件上傳下載的小系統(tǒng)。但麻雀雖小五臟俱全它能完整覆蓋從開發(fā)到聯(lián)調(diào)再到部署的一條鏈路。我之所以選這個組合來做實例是因為 Vue 和 SpringBoot 是目前國內(nèi)中小團隊使用率最高的前后端技術(shù)棧。Vue 上手曲線平緩、中文文檔齊全、生態(tài)豐富SpringBoot 則讓 Java 后端的開發(fā)變得異常輕量內(nèi)置 Tomcat、自動配置、起步依賴這些特性幾乎就是為快速交付業(yè)務接口而生的。兩個東西加在一起能解決的問題非常廣企業(yè)內(nèi)部管理系統(tǒng)、電商后臺、內(nèi)容管理平臺、小程序管理端基本上都能用這套骨架去套。適合誰來參考呢我建議有三類人認真看完第一類是剛學完 Vue 和 SpringBoot 基礎語法、想做一個完整項目練手的同學第二類是公司里被迫從零搭建前后端分離工程、但沒人帶的新人開發(fā)第三類是準備面試、需要把前后端交互鏈路講清楚的朋友。這篇內(nèi)容不是教科書是我實際開發(fā)中一步步踩出來的經(jīng)驗總結(jié)跟著做能少走很多彎路。1.2 為什么選擇 Vue 3 Vite SpringBoot 這套組合選型這事情沒有絕對的最好只有適合當前場景的方案。我最初也糾結(jié)過要不要用 Vue 2畢竟公司老項目里 Vue 2 的存量很大。但考慮到 Vue 3 的組合式 APIComposition API確實讓邏輯復用變得干凈很多而且 Vite 帶來的冷啟動速度提升是肉眼可見的——以前用 Vue CLI 啟動一個中型項目要等二三十秒換成 Vite 之后基本秒開。對于開發(fā)體驗來說這個差距太明顯了。后端用 SpringBoot 2.7 而非 3.x主要考慮的是生態(tài)兼容性。很多常用的第三方庫比如一些工作流引擎、代碼生成器在 SpringBoot 3.x 上還在適配期而 2.7 是 2.x 系列的最后一個穩(wěn)定版本坑相對少得多。如果你的項目剛起步、不需要用那些冷門庫直接上 3.x 也沒問題但作為一個教學型實例我選擇更穩(wěn)妥的版本。數(shù)據(jù)庫方面我用的是 MySQL 8.0 MyBatis-Plus。MyBatis-Plus 對單表 CRUD 的增強非常實用不需要手寫 XML 就能完成大部分數(shù)據(jù)操作非常適合快速搭建原型項目。同時我還配置了 MyBatis-Plus 的自動建表功能——這個功能在某些場景下極其好用比如演示環(huán)境、測試環(huán)境、快速交付演示項目時完全不需要手動去執(zhí)行 SQL 腳本。整個項目的前后端交互走的是 RESTful API JSON前端開發(fā)時通過 Vite 的代理Proxy解決跨域問題生產(chǎn)環(huán)境則用 Nginx 做反向代理將/api路徑的請求轉(zhuǎn)發(fā)到后端服務。這套方案是我在多個生產(chǎn)項目中驗證過的穩(wěn)定性和可維護性都很好。2. 前端 Vue 部分的關鍵搭建與實現(xiàn)2.1 Vue 安裝及環(huán)境配置的注意事項很多新手在第一步就栽跟頭——不是 Node 版本不對就是 npm 源太慢導致依賴安裝失敗。我先說一下我自己比較推薦的配置流程。安裝 Node.js 的時候盡量選擇 LTS 版本。不要追新有些 Vite 插件在最新的 Node 奇數(shù)版本上可能存在兼容性問題。裝完 Node 順手把 npm 鏡像切到國內(nèi)源npm config set registry https://registry.npmmirror.com這一步能節(jié)省大量等待時間實測下來安裝依賴的速度能快三倍以上。創(chuàng)建項目我推薦用 Vite 的官方腳手架npm create vitelatest frontend -- --template vue這里解釋一下為什么要用 Vite 而不是 Vue CLI。Vite 基于原生 ES Module開發(fā)模式下不需要打包整個應用而是按需編譯瀏覽器請求的模塊所以啟動速度和熱更新速度都非?？?。我印象最深的一次是一個項目有三百多個組件用 Vue CLI 改一行代碼要等兩秒左右才能看到熱更新效果換成 Vite 之后幾乎是即時刷新。創(chuàng)建完成后進入項目目錄安裝路由和狀態(tài)管理相關的依賴。這里我用了 Vue Router 4 和 Pinianpm install vue-router4 pinia然后安裝 UI 組件庫。如果做后臺管理系統(tǒng)推薦 Ant Design Vue如果做面向用戶的網(wǎng)站推薦 Element Plus。這個項目我選的是 Element Plus因為它的表格、表單、彈窗組件寫起來非常順手。npm install element-plus element-plus/icons-vue這里有一個我自己總結(jié)的小經(jīng)驗Element Plus 的圖標需要單獨安裝而且如果按需引入需要在 main.js 里把所有用到的圖標統(tǒng)一注冊。很多人忘了這一步結(jié)果頁面上圖標顯示不出來排查半天才發(fā)現(xiàn)是注冊的問題。2.2 路由設計從登錄頁到業(yè)務頁面的完整跳轉(zhuǎn)邏輯路由是前端項目的骨架我見過很多項目路由寫得很隨意結(jié)果后面加權(quán)限控制的時候痛不欲生。這里我推薦一套清晰的路由組織方式。在src/router/index.js下定義路由至少要有兩種路由基礎路由和業(yè)務路由?；A路由包括登錄頁、404 頁面業(yè)務路由放在一個統(tǒng)一的 Layout 布局組件之下方便統(tǒng)一加載導航欄和側(cè)邊欄。import { createRouter, createWebHistory } from vue-router const routes [ { path: /login, name: Login, component: () import(../views/Login.vue) }, { path: /, component: () import(../layout/Index.vue), redirect: /dashboard, children: [ { path: dashboard, name: Dashboard, component: () import(../views/dashboard/index.vue) }, { path: user, name: UserList, component: () import(../views/user/index.vue) } ] } ] const router createRouter({ history: createWebHistory(), routes }) // 全局前置守衛(wèi)未登錄跳轉(zhuǎn)到登錄頁 router.beforeEach((to, from, next) { const token localStorage.getItem(token) if (!token to.path ! /login) { next(/login) } else { next() } }) export default router路由懶加載這個點要重點提一下——用() import()的方式導入組件Vite 會自動把每個頁面拆成獨立的 chunk首屏只加載當前頁面需要的代碼。之前有個項目沒有做懶加載首屏體積到了 2MB 多白屏時間差不多兩秒改成懶加載之后首屏壓到了 500KB 以內(nèi)體驗提升非常明顯。還有一個細節(jié)是路由模式。我這里用的是createWebHistory也就是 HTML5 History 模式URL 看起來是http://xxx.com/user而不是http://xxx.com/#/user。但要注意使用 History 模式后線上的 Nginx 需要配置try_files把所有路徑都重定向到index.html否則刷新頁面會報 404。這個在后文部署部分會細說。2.3 登錄注冊模塊與后端接口的第一次握手登錄注冊是整個前后端項目里第一次真正意義上的數(shù)據(jù)交互也是很多人第一次被跨域問題卡住的地方。我先說我前端這邊的寫法。登錄頁模板里放一個表單兩個字段用戶名、密碼加一個登錄按鈕。提交的時候調(diào)用封裝好的登錄接口import request from ../utils/request export function login(data) { return request({ url: /api/auth/login, method: post, data }) }這里的request是基于 Axios 封裝的一個實例統(tǒng)一配置了 baseURL 和攔截器。重點說一下響應攔截器的寫法它決定了你在組件里代碼能少寫多少import axios from axios import { ElMessage } from element-plus const request axios.create({ baseURL: import.meta.env.VITE_API_BASE_URL || /api, timeout: 10000 }) // 請求攔截器統(tǒng)一攜帶 token request.interceptors.request.use(config { const token localStorage.getItem(token) if (token) { config.headers.Authorization Bearer ${token} } return config }) // 響應攔截器統(tǒng)一處理異常 request.interceptors.response.use( response { const res response.data if (res.code ! 200) { ElMessage.error(res.message || 請求失敗) return Promise.reject(new Error(res.message)) } return res }, error { ElMessage.error(error.response?.data?.message || 網(wǎng)絡異常) return Promise.reject(error) } ) export default request這樣做的好處是組件里調(diào)用接口只需要關心返回的數(shù)據(jù)不需要每寫一個接口都處理一遍code ! 200的邏輯分支。在登錄頁面拿到后端返回的 token 后存到 localStorage然后調(diào)用router.push(/dashboard)跳轉(zhuǎn)到首頁。整個交互鏈路就完成了。3. 后端 SpringBoot 部分的搭建與核心接口開發(fā)3.1 快速創(chuàng)建一個 SpringBoot 項目避免超時問題的三個辦法后端的項目創(chuàng)建我一般用 IDEA 的 Spring Initializr但很多人都會遇到一個很煩的問題——創(chuàng)建項目時連接 start.spring.io 超時轉(zhuǎn)半天圈然后報錯。這里講三個我自己驗證過的方法。第一個方法改 IDEA 的 HTTP 代理設置讓它能順利訪問外部網(wǎng)絡。但這辦法受限于公司網(wǎng)絡策略有些環(huán)境下不好使。第二個方法使用國內(nèi)的 Spring Initializr 鏡像。阿里云提供了一個地址是https://start.aliyun.com。在 IDEA 的 Server URL 處替換掉默認地址創(chuàng)建速度就是一個字——快。需要注意的是阿里云鏡像里提供的依賴版本可能會比官方源舊一點但對大多數(shù)項目沒有影響。第三個方法是離線創(chuàng)建。在 IDEA 的 Maven 配置里設置好本地倉庫路徑然后自己手動在項目里添加pom.xml最后右鍵選擇 Add as Maven Project。這種方式適合網(wǎng)絡環(huán)境極端惡劣的情況。我平時最常用的是第二個方法基本上選好 Spring Web、MyBatis-Plus、MySQL Driver、Lombok 這幾個依賴十幾秒項目就創(chuàng)建完了。3.2 核心依賴與配置文件yml 里的靜態(tài)資源和密碼處理經(jīng)驗項目創(chuàng)建好之后第一步是改配置文件。我習慣把默認的application.properties改成application.yml因為 YAML 的層級結(jié)構(gòu)更清晰尤其是配置多數(shù)據(jù)源、Redis 這類需要嵌套的信息時可讀性高得多。一個需要注意的地方是 SpringBoot 2.7 以后的配置項變更。比如spring.redis改成了spring.data.redis以及 MyBatis 配置里的mapper-locations路徑寫法。版本不同配置不同搜資料的時候要先確認自己用的版本不然被舊資料坑了會花很多時間調(diào)莫名其妙的問題。server: port: 8080 spring: datasource: driver-class-name: com.mysql.cj.jdbc.Driver url: jdbc:mysql://localhost:3306/demo_db?useUnicodetruecharacterEncodingutf8useSSLfalseserverTimezoneAsia/ShanghaiallowPublicKeyRetrievaltrue username: root password: ${DB_PASSWORD:123456} mybatis-plus: configuration: map-underscore-to-camel-case: true global-config: db-config: table-prefix: t_關于密碼配置我多說一句。生產(chǎn)環(huán)境極度不建議把數(shù)據(jù)庫密碼明文寫在 yml 里這屬于安全底線問題。SpringBoot 本身沒有內(nèi)置的加密方案但可以引入 jasypt-spring-boot-starter對配置文件中的密碼進行加密。基本用法是在配置項外面套一層ENC()標記然后在啟動參數(shù)里傳入解密密鑰password: ENC(加密后的密文)啟動時java -jar demo.jar --jasypt.encryptor.password你的密鑰這套方案在 demo 里可以不搞但放到公司項目里建議一定要加上。安全問題越早考慮后面成本越低。3.3 表結(jié)構(gòu)自動創(chuàng)建MyBatis-Plus 中的建表工具類實現(xiàn)這個項目的數(shù)據(jù)表很少總共就用戶表、日志表幾張所以我沒有引入專門的數(shù)據(jù)庫遷移工具比如 Flyway而是寫了一個簡單的表結(jié)構(gòu)自動創(chuàng)建工具類。原理其實很簡單項目啟動時讀取一個schema.sql文件檢查數(shù)據(jù)庫中是否存在目標表如果不存在就執(zhí)行建表語句。實現(xiàn)方式是在 SpringBoot 的 ApplicationRunner 啟動類里做處理Component public class TableInitRunner implements ApplicationRunner { Resource private JdbcTemplate jdbcTemplate; Override public void run(ApplicationArguments args) { String checkTableSql SELECT COUNT(*) FROM information_schema.tables WHERE table_schema demo_db AND table_name t_user; Integer count jdbcTemplate.queryForObject(checkTableSql, Integer.class); if (count null || count 0) { executeSqlScript(new ClassPathResource(sql/schema.sql)); } } }這樣帶來的好處是很直觀的——把項目拉下來運行不必手動去 Navicat 里執(zhí)行建表 SQL前后端同學都省心。尤其是快速搭建演示環(huán)境的時候這個細節(jié)能省掉至少十分鐘的溝通成本。不過要說清楚這種方案只適合表結(jié)構(gòu)不頻繁變動的場景。如果項目進入迭代期表字段經(jīng)常調(diào)整還是得回歸 Flyway 或者 Liquibase否則增量 SQL 的執(zhí)行順序會成為新的麻煩。3.4 用戶登錄接口從 Controller 到 Service 的完整代碼路徑后端接口開發(fā)我遵循三層結(jié)構(gòu)Controller接收請求、Service業(yè)務邏輯、Mapper數(shù)據(jù)訪問。以登錄接口為例代碼路徑大概是這樣的。首先是 Controller 層RestController RequestMapping(/api/auth) public class AuthController { Resource private AuthService authService; PostMapping(/login) public ResultVOString login(RequestBody LoginDTO loginDTO) { String token authService.login(loginDTO); return ResultVO.success(token); } }然后是 Service 層。注意這里有一個細節(jié)——我用了ResultVO統(tǒng)一包裝返回結(jié)果結(jié)構(gòu)是{ code, message, data }這樣的格式。這樣前后端約定好了交互協(xié)議前端攔截器里的res.code ! 200判斷才有意義。Service public class AuthServiceImpl implements AuthService { Resource private UserMapper userMapper; Override public String login(LoginDTO loginDTO) { // 1. 查詢用戶 User user userMapper.selectByUsername(loginDTO.getUsername()); // 2. 校驗密碼BCrypt加密存儲 if (user null || !BCrypt.checkpw(loginDTO.getPassword(), user.getPassword())) { throw new BizException(用戶名或密碼錯誤); } // 3. 生成token并返回 return JwtUtil.generateToken(user.getId(), user.getUsername()); } }密碼為什么一定要用 BCrypt 加密存儲因為 MD5 撞庫太容易了反查一個弱密碼幾乎是秒級的事。BCrypt 自帶隨機鹽能有效對抗彩虹表攻擊而且計算成本可以調(diào)整這是目前業(yè)界比較推薦的密碼存儲方案。用戶表結(jié)構(gòu)很簡單對應字段就是 id、username、password、created_time 幾個通過 MyBatis-Plus 的注解就能完成映射Data TableName(t_user) public class User { TableId(type IdType.AUTO) private Long id; private String username; private String password; TableField(created_time) private LocalDateTime createdTime; }3.5 跨域問題解析前后端分離后最常踩的一個坑跨域問題我單獨拿出來說因為十個前后端聯(lián)調(diào)項目里有九個會被它卡一下?？缬虻谋举|(zhì)是瀏覽器的同源策略——只有當請求的協(xié)議、域名、端口都一樣時瀏覽器才允許 JavaScript 讀取響應。在開發(fā)環(huán)境下前端跑在http://localhost:5173后端跑在http://localhost:8080端口不同瀏覽器就會攔截跨域請求。三種解決方案我都用過說下各自的適用場景。第一種是后端開 CORS 全局配置。在 SpringBoot 里寫一個配置類Configuration public class CorsConfig { Bean public CorsFilter corsFilter() { CorsConfiguration config new CorsConfiguration(); config.addAllowedOriginPattern(*); config.addAllowedMethod(*); config.addAllowedHeader(*); config.setAllowCredentials(true); UrlBasedCorsConfigurationSource source new UrlBasedCorsConfigurationSource(); source.registerCorsConfiguration(/**, config); return new CorsFilter(source); } }這種方案配置簡單適合生產(chǎn)環(huán)境前后端域名不同的情況。但我個人不太建議在生產(chǎn)環(huán)境把允許來源設為*最好顯式寫成你前端的域名特別是如果網(wǎng)站要存 Cookie 做會話保持*會導致前端請求無法攜帶憑證必須精確指定來源。第二種是前端開發(fā)環(huán)境下的代理方案。在 Vite 的vite.config.js里配置export default defineConfig({ server: { proxy: { /api: { target: http://localhost:8080, changeOrigin: true } } } })這樣前端發(fā)請求時瀏覽器看到的請求目標是http://localhost:5173/api/auth/login同源不觸發(fā)跨域。Vite 把請求轉(zhuǎn)發(fā)給后端的http://localhost:8080/api/auth/login。這是開發(fā)環(huán)境最推薦的方式不需要后端做任何額外配置同時還能靈活地切換后端地址。第三種是生產(chǎn)環(huán)境用 Nginx 反向代理。這種方式本質(zhì)上和第二種類似只是轉(zhuǎn)發(fā)職責從 Vite 交給 Nginx 來做。在 Nginx 配置里加一段 locationlocation /api/ { proxy_pass http://127.0.0.1:8080; }三種方案可以在同一個項目里組合使用開發(fā)走 Vite 代理生產(chǎn)走 Nginx 代理后端保持不提供跨域配置。這樣后端的接口更為獨立也方便直接供第三方系統(tǒng)調(diào)用。4. 前后端聯(lián)調(diào)從零到一打通全流程4.1 聯(lián)調(diào)前的三個準備工作前后端聯(lián)調(diào)不是拉個群兩邊把代碼一跑就算完的。我經(jīng)歷過太多次聯(lián)調(diào)現(xiàn)場因為準備不足而浪費一兩天時間的情況。做足準備聯(lián)調(diào)效率能提升一倍。第一個準備是接口文檔先行。不要后端寫完接口再補文檔要在動手寫代碼之前就把接口的路徑、請求參數(shù)、返回結(jié)構(gòu)定義清楚。工具上我推薦 Apifox 或者 YApi可以在線管理接口文檔并生成 Mock 數(shù)據(jù)。前端根據(jù)文檔寫頁面后端根據(jù)文檔開發(fā)接口兩邊并行推進聯(lián)調(diào)的時候只需要對細節(jié)而不是爭論字段叫什么名字。第二個準備是統(tǒng)一錯誤碼規(guī)范。項目里返回結(jié)構(gòu)統(tǒng)一是code、message、data但 code 的取值范圍和含義要提前約定。比如 200 是成功401 是未認證403 是權(quán)限不足500 是服務器內(nèi)部錯誤。前端攔截器根據(jù) code 做統(tǒng)一處理比如遇到 401 就跳轉(zhuǎn)登錄頁遇到 500 就彈出錯誤提示。如果每個接口返回的錯誤碼風格不同前端攔截器就形同虛設。第三個準備是接口字段命名約束。Java 后端習慣用駝峰命名userName數(shù)據(jù)庫習慣用下劃線user_name而前端 JavaScript 兩種風格都有人寫。我建議前后端接口傳輸?shù)慕y(tǒng)一用駝峰命名數(shù)據(jù)庫字段映射交給 MyBatis-Plus 的下劃線轉(zhuǎn)駝峰配置前端永遠只面對駝峰字段這樣最省心。4.2 如何快速區(qū)分前后端 Bug聯(lián)調(diào)階段每天都要面對各種報錯如何快速判斷問題出在前端還是后端這是每個開發(fā)都必須掌握的技能。我有幾個高效的定位手段。第一招是看 Network 面板。按 F12 打開瀏覽器開發(fā)者工具切到 Network 標簽頁找到對應的接口請求。如果請求狀態(tài)碼是 404 或 405說明路徑或請求方法不對大概率是后端問題如果狀態(tài)碼是 200但返回數(shù)據(jù)里的 code 是 500說明后端內(nèi)部拋異常了點開 Response 看具體錯誤信息如果請求根本沒有發(fā)出或者請求 vender 里標著(failed) net::ERR_FAILED那是前端的問題先檢查代理配置和接口地址。第二招是分階段確認。前端能顯示的頁面結(jié)構(gòu)、交互邏輯屬于前端問題數(shù)據(jù)是否正確、接口是否返回符合預期的內(nèi)容屬于接口問題接口返回的內(nèi)容是否被正確處理屬于前端問題。很多人會在這三層之間來回橫跳我的習慣是先在 Network 面板里確認后端返回的原始 JSON 數(shù)據(jù)是否符合預期如果正確那問題一定在前端處理數(shù)據(jù)的代碼上從那兒往下查很快。第三招是巧用后端日志。SpringBoot 默認會輸出 WEB 層的訪問日志可以看到每個請求的路徑、參數(shù)、處理耗時以及異常堆棧。如果前端說接口報錯但后端日志里壓根沒有相關請求記錄那多半是請求沒到后端問題出在代理或路由配置上。這個判斷方法在排查跨域和代理問題時尤其高效。4.3 文件上傳下載這類耗時接口的聯(lián)調(diào)細節(jié)這個項目里我還加了一個文件上傳下載的接口。初看很簡單但實際聯(lián)調(diào)時有不少細節(jié)容易出問題。前端的文件上傳我用 Element Plus 的el-upload組件配置好 action 地址和請求頭即可。但有個坑是文件上傳接口一般不需要也不應該攜帶認證 header而我在 Axios 請求攔截器里統(tǒng)一加了Authorization頭這會導致部分瀏覽器觸發(fā)一次額外的 OPTIONS 預檢請求。后端如果沒處理好預檢請求就會報跨域錯誤。解決辦法是在后端過濾器里對 OPTIONS 請求直接放行if (OPTIONS.equals(request.getMethod())) { response.setStatus(HttpServletResponse.SC_OK); return; }大文件上傳則是另一個話題。如果文件超過 100MB直接上傳很容易超時我推薦做分片上傳。前端把文件切割成固定大小的分片比如每片 5MB逐個上傳后端接收后合并。斷點續(xù)傳也依賴這個基礎——記錄已上傳的分片列表下次上傳時跳過已完成的分片。我在項目里實現(xiàn)了一個簡單的分片上傳接口前端用Blob.prototype.slice切分文件后端收到分片后暫存在臨時目錄最后一片上傳成功后通知后端合并。代碼本身不復雜但能覆蓋絕大多數(shù)大文件上傳的業(yè)務需求。4.4 Vite 代理配置技巧與常見聯(lián)調(diào)報錯匯總前面已經(jīng)提過 Vite 代理的基礎配置這里補充一些實際使用中的進階技巧。如果你需要同時訪問多個后端服務可以通過配置多個代理規(guī)則實現(xiàn)proxy: { /api: { target: http://localhost:8080, changeOrigin: true }, /file: { target: http://localhost:9090, changeOrigin: true } }changeOrigin: true這個選項的作用是修改請求頭中的 Host 字段為目標地址的 Host如果不設置有些后端服務器會校驗 Host 并拒絕請求。聯(lián)調(diào)中最常見的報錯我整理成了一張表方便對照排查現(xiàn)象可能原因解決辦法瀏覽器報 CORS error后端未配置CORS或代理規(guī)則不匹配檢查代理配置或在后端添加CORS配置請求404前端代理路徑與后端接口路徑不一致核對接口URL前綴請求返回500后端代碼異常查看后端日志定位異常堆棧前端拿不到data字段后端返回結(jié)構(gòu)不統(tǒng)一約定統(tǒng)一ResultVO結(jié)構(gòu)Token失效但登錄頁不跳轉(zhuǎn)攔截器未處理401狀態(tài)碼在響應攔截器中加錯誤跳轉(zhuǎn)處理4.5 調(diào)試工具與接口測試的實用技巧聯(lián)調(diào)階段有兩類工具是效率神器。第一類是前端 Vue 調(diào)試工具。Vue 3 對應的瀏覽器插件是Vue.js devtools在 Chrome 商店就能安裝。它能直觀查看組件的 props、data、computed 值還能追蹤事件和路由。排查響應式數(shù)據(jù)沒更新、computed 計算錯誤這類問題非常高效。調(diào)試的時候先在 devtools 里檢查組件 data 的值是否正確如果不正確再看是不是接口數(shù)據(jù)的問題逐層排查比瞎猜有用得多。第二類是接口測試工具。Apifox 有個很好用的功能——從一個接口的測試用例里直接生成前后端聯(lián)調(diào)時的 Mock 數(shù)據(jù)。前端頁面開發(fā)階段不需要等待后端接口就緒直接調(diào)用 Mock 數(shù)據(jù)就能正常渲染后端接口真正寫好后只要把測試環(huán)境地址切換到真實后端頁面就能無縫銜接真實數(shù)據(jù)。這個工作流我用了很久確實能有效減少聯(lián)調(diào)等待時間。5. 前后端項目的部署與上線5.1 前端打包常見錯誤與 Nginx 配置指南前端開發(fā)完后的部署我一般分四步打包、上傳、配 Nginx、驗證。打包前建議確認環(huán)境變量配置。Vite 默認區(qū)分開發(fā)環(huán)境和生產(chǎn)環(huán)境通過.env.development和.env.production文件管理。生產(chǎn)環(huán)境里的VITE_API_BASE_URL我習慣設為空字符串讓所有請求都走同源相對路徑/api然后交給 Nginx 做代理轉(zhuǎn)發(fā)。這樣部署路徑靈活不需要根據(jù)不同機房改前端代碼。執(zhí)行npm run build之后產(chǎn)物在dist目錄。上傳到服務器后Nginx 配置的核心部分長這樣server { listen 80; server_name your-domain.com; root /var/www/frontend/dist; index index.html; # 前端路由 history 模式刷新支持 location / { try_files $uri $uri/ /index.html; } # 接口反向代理 location /api/ { proxy_pass http://127.0.0.1:8080; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; } }try_files $uri $uri/ /index.html;這一行極其關鍵。如果沒有這一行刷新http://your-domain.com/user頁面時Nginx 會去物理目錄找 user 文件找不到就報 404。加上之后Nginx 發(fā)現(xiàn)文件不存在會回退到index.html由前端路由接管渲染。這個坑我在初學階段栽過一次后來每次部署都要確認一遍。5.2 使用 Docker Compose 一鍵編排前后端服務如果服務器是全新的我推薦直接用 Docker Compose 來編排服務。把 MySQL、后端、前端 Nginx 打成三個容器一條命令啟動所有服務可復現(xiàn)性和可維護性都很好。先說鏡像構(gòu)建。前端需要一個帶 Nginx 的自定義鏡像Dockerfile 大概長這樣FROM node:18-alpine AS build WORKDIR /app COPY package*.json ./ RUN npm install --registryhttps://registry.npmmirror.com COPY . . RUN npm run build FROM nginx:alpine COPY --frombuild /app/dist /usr/share/nginx/html COPY nginx.conf /etc/nginx/conf.d/default.conf EXPOSE 80 CMD [nginx, -g, daemon off;]這里用了多階段構(gòu)建——第一階段用 Node 鏡像編譯前端資源第二階段把編譯產(chǎn)物拷貝進干凈的 Nginx 鏡像。這樣最終鏡像體積小也不包含編譯工具鏈的冗余文件。后端同理FROM maven:3.8-openjdk-8 AS build WORKDIR /app COPY pom.xml . RUN mvn dependency:go-offline COPY src ./src RUN mvn package -DskipTests FROM openjdk:8-jre-alpine COPY --frombuild /app/target/demo.jar /app/demo.jar EXPOSE 8080 ENTRYPOINT [java, -jar, /app/demo.jar]然后寫docker-compose.ymlversion: 3.8 services: mysql: image: mysql:8.0 environment: MYSQL_ROOT_PASSWORD: root123 MYSQL_DATABASE: demo_db ports: - 3306:3306 volumes: - mysql_data:/var/lib/mysql restart: always backend: build: ./backend depends_on: - mysql environment: SPRING_DATASOURCE_URL: jdbc:mysql://mysql:3306/demo_db?useSSLfalseserverTimezoneAsia/Shanghai SPRING_DATASOURCE_USERNAME: root SPRING_DATASOURCE_PASSWORD: root123 ports: - 8080:8080 restart: always frontend: build: ./frontend depends_on: - backend ports: - 80:80 restart: always volumes: mysql_data:這里要特別注意的是 Docker Compose 內(nèi)部網(wǎng)絡的 DNS 解析——后端容器里訪問數(shù)據(jù)庫不能寫localhost而要寫服務名mysql。同理前端 Nginx 容器里反向代理后端也不應該寫127.0.0.1而要寫后端服務名backend。這個細節(jié)如果忽略部署上去就會發(fā)現(xiàn)容器之間網(wǎng)絡不通。啟動命令很簡單docker-compose up -d --build整個前后端項目在三分鐘內(nèi)就能在任意一臺安裝好 Docker 的服務器上跑起來。這對于交付演示環(huán)境、臨時測試環(huán)境來說非常省事。5.3 云服務器部署的完整步驟與常見坑不習慣用 Docker 的話在云服務器上直接部署也更常規(guī)。流程一般是服務器裝好 JDK 和 Nginx上傳后端 jar 包運行再上傳前端 dist 目錄到 Nginx 站點目錄。后端 jar 包啟動推薦用nohup加日志輸出nohup java -jar demo.jar --spring.profiles.activeprod app.log 21 這里有兩個注意點。第一--spring.profiles.activeprod指定配置文件生產(chǎn)環(huán)境走生產(chǎn)環(huán)境的數(shù)據(jù)庫配置。第二 app.log 21將標準輸出和錯誤輸出都重定向到日志文件這樣排查問題的時候可以在日志文件里看到完整的異常信息。啟動后驗證接口是否正常curl http://127.0.0.1:8080/api/auth/login如果后端正常再檢查 Nginx 配置是否生效nginx -t nginx -s reload最后從瀏覽器訪問http://服務器公網(wǎng)IP能看到前端頁面說明部署成功。云服務器部署常見的坑我來盤一盤第一安全組端口沒開。阿里云和騰訊云的服務器默認只有 22 端口是開放的要在控制臺安全組里放行 80 和 8080 端口否則外部無法訪問。這個問題非常常見我曾經(jīng)在一次項目演示前五分鐘才發(fā)現(xiàn)端口沒開當場排查了半天。第二數(shù)據(jù)庫訪問權(quán)限問題。云服務器的 MySQL 默認只監(jiān)聽本地回環(huán)地址后端在與數(shù)據(jù)庫連接時要注意賬號是否有遠程訪問權(quán)限但在單機部署中通常都用localhost連接這時問題不大。如果數(shù)據(jù)庫單獨部署在另一臺機器上就要到 MySQL 用戶權(quán)限表里給應用賬號授權(quán)。第三防火墻沖突。云服務器上可能同時存在云安全組和系統(tǒng)內(nèi)部的 firewalld/iptables 兩層防護兩層都要放行對應端口。經(jīng)常有人配好了安全組仍然訪問不了一查發(fā)現(xiàn)是機器內(nèi)防火墻把端口拒了。6. 常見問題與排查技巧實錄6.1 Maven 與 npm 依賴下載超時的終極解決方案幾乎每個新人都被這個問題折磨過。npm 依賴裝一半卡住不動Maven 依賴下載一直報超時本質(zhì)原因都是默認源在國外網(wǎng)絡不穩(wěn)定。Maven 源修改很簡單打開 Maven 安裝目錄下的conf/settings.xml在mirrors節(jié)點里加入阿里云鏡像mirror idaliyunmaven/id mirrorOfcentral/mirrorOf name阿里云公共倉庫/name urlhttps://maven.aliyun.com/repository/public/url /mirrornpm 源前面已經(jīng)說過改成registry.npmmirror.com就行。這倆改完之后下載速度提升一個量級基本上不會再有超時問題。還有一種情況本地網(wǎng)絡本身沒問題但依賴就是下載慢?？梢栽囋囅仁謩酉螺d jar 包放到本地倉庫里再用mvn install:install-file命令安裝到本地。這種方式在應急場景下比較有用比如某一天某個依賴分發(fā)出問題了從中央倉庫拿不到包。6.2 SpringBoot 版本太高導致的各種兼容性問題版本選型是后端項目成敗的關鍵細節(jié)之一。我見過不少項目因為用了剛發(fā)布的最新版 SpringBoot結(jié)果引入某個第三方庫時發(fā)現(xiàn)對方還沒有適配新版本導致項目啟動失敗或者運行時出現(xiàn)古怪異常。SpringBoot 3.x 最大的變化是底層從javax.*切換到了jakarta.*命名空間這意味著所有依賴這個命名空間的第三方庫都需要升級適配。如果你在項目中還在用一些老牌的、維護不頻繁的庫某些公司內(nèi)部的框架、老版本的工作流引擎升級到 SpringBoot 3.x 基本就是勸退。我的經(jīng)驗是公司項目跟著穩(wěn)定版本走個人學習可以跟著最新版本走。目前 2.7 和 3.2 都是相對穩(wěn)妥的選擇。如果項目里有大量歷史遺留依賴2.7 會更合適如果是全新項目直接 3.2 也沒問題畢竟技術(shù)總要往前迭代。6.3 Vue 常見面試考點與項目實戰(zhàn)的結(jié)合這個項目寫完之后最大的收益其實是面試。面試官問 Vue 相關的問題基本都繞不開這幾個v-if和v-show的區(qū)別、Vue 3 組合式 API 和選項式 API 的區(qū)別、key的作用、路由守衛(wèi)的用法。如果只是背概念答不出亮點但如果結(jié)合項目實戰(zhàn)來講效果會好很多。比如v-if和v-show——實際項目中登錄狀態(tài)、權(quán)限按鈕這種頻繁切換的場景我一般用v-show因為它只是切換 CSS 的display屬性不需要重新渲染組件開銷小而像低概率出現(xiàn)的彈窗、不同角色的大塊頁面內(nèi)容我會用v-if因為它能徹底銷毀組件避免內(nèi)存泄漏。再比如路由守衛(wèi)我的項目里不僅做了登錄校驗還做了一個小的權(quán)限控制根據(jù)后端返回的角色信息在路由守衛(wèi)里判斷用戶是否有權(quán)訪問某個頁面沒有權(quán)限就跳轉(zhuǎn) 403 頁面。把這個邏輯講出來面試官會覺得你是真的在項目里解決過問題而不是背概念。還有一個必問的Vue 3 組合式 API 和選項式 API 的區(qū)別。我在項目里兩種都寫過實際體會是——組合式 API 對復雜邏輯的復用確實方便用computed、watch、ref這些組合函數(shù)能把原本散落在data、methods、watch里的代碼組織到一起。但簡單頁面用選項式 API 也完全沒問題代碼反而更直觀。面試官問這個問題的時候你就可以說兩種都實踐過我的選型標準是邏輯復雜度而不是盲目追新。7. 項目擴展方向與我的實操心得項目跑通之后完全可以基于這個骨架繼續(xù)擴展。我列幾個我實際做過或者覺得很有價值的方向。第一個方向是引入工作流引擎。SpringBoot 集成 Flowable 是做審批類系統(tǒng)最常見的需求。比如請假審批、費用報銷這些場景用 Flowable 定義好流程模板后端通過 API 啟動流程實例在任務完成節(jié)點做業(yè)務處理前端通過接口查詢待辦任務、已辦任務。這套能力在很多企業(yè)級系統(tǒng)里都是剛需。Flowable 7 有相對好用的 REST API可以直接在前端調(diào)用也可以包一層自己的接口做權(quán)限控制。第二個方向是音視頻處理。Vue 前端播放 HLS 視頻流m3u8 格式的需求越來越多特別是直播回放、監(jiān)控視頻這類場景。前端可以用hls.js這個庫幾行代碼就能實現(xiàn) m3u8 的播放。需要注意的是瀏覽器原生的 video 標簽并不支持 m3u8 格式除了 Safari必須通過hls.js做轉(zhuǎn)封裝或者使用帶 MSE 支持的播放器組件。這個功能我建議在有相關業(yè)務需求時再引入不要一開始就把項目的復雜度抬高。第三個方向是系統(tǒng)集成能力。項目里可以接入第三方平臺的開放能力。前端做網(wǎng)頁版 H5 應用時經(jīng)常需要對接 IM 工具和內(nèi)部平臺的免登錄流程需要遵循對應的 OAuth 授權(quán)協(xié)議。開發(fā)方式大同小異拿到授權(quán)碼之后請求后端交換 token后端記錄用戶信息并生成自己的登錄態(tài)。整個項目從搭建到部署走下來我最大的體會是前后端分離項目真正的難點不在技術(shù)棧本身而在工程化意識。環(huán)境怎么統(tǒng)一、接口怎么約定、錯誤怎么排查、部署怎么做這些能力比單純會寫幾個組件和接口重要得多。希望這篇內(nèi)容能幫你把這條鏈路完整地走一遍后續(xù)不管換什么框架、換什么語言底層的思路都是相通的。最后分享一個我這些年一直在用的習慣每次新項目動工前先花半小時把接口文檔和目錄結(jié)構(gòu)定好本地能少熬兩天的夜。這個投入產(chǎn)出比是我踩過無數(shù)坑之后最想告訴你的。本文還有配套的精品資源點擊獲取