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