1. 項目概述1.1 核心需求解析做全棧開發(fā)這幾年我見過太多半路出家的開發(fā)者在 Spring Boot 和 Vue 的邊界線上反復(fù)橫跳——后端能寫接口但前端拿著 JSON 不知道往哪兒塞前端能把頁面畫出來但遇到跨域、鑒權(quán)、打包部署就抓瞎。這個實戰(zhàn)指南解決的就是這個問題把一條完整的前后端分離開發(fā)鏈路串起來從零開始搭建一個可直接運行的全棧項目。注意這里的關(guān)鍵詞是“全?！辈皇恰扒昂蠖烁鲗懸话搿?。項目會包含一個完整的業(yè)務(wù)閉環(huán)前端 Vue 負(fù)責(zé)頁面交互和數(shù)據(jù)展示后端 Spring Boot 負(fù)責(zé)接口服務(wù)和數(shù)據(jù)持久化中間通過 RESTful API 通信最終打包部署到同一臺服務(wù)器上跑通整個流程。這個過程中涉及的技術(shù)點非常密集——Vue 的生命周期、Axios 的請求攔截、Spring Boot 的分層架構(gòu)、MyBatis 的數(shù)據(jù)映射、JWT 的登錄態(tài)管理、Nginx 的反向代理——任何一個環(huán)節(jié)掉鏈子整個項目就跑不起來。這個項目的受眾其實很廣。剛?cè)胄械某跫夐_發(fā)者可以通過它建立全棧思維知道前端發(fā)起的請求在后端到底經(jīng)歷了什么寫了好幾年接口的后端開發(fā)可以補上前端技能獨立負(fù)責(zé)完整模塊做畢設(shè)或小團隊項目的同學(xué)可以直接拿這套骨架改業(yè)務(wù)邏輯就能上線。我的建議是無論你偏向前端還是后端都完整地把項目過一遍收獲最大的恰恰是你知識短板那部分的內(nèi)容。1.2 技術(shù)棧全景與選型理由Spring Boot 3.x 搭配 Vue 3.x 是當(dāng)前主流選擇我用的版本組合是 Spring Boot 3.2.5 Vue 3.4.21 Vite 5.2.0。這套組合的好處是生態(tài)成熟遇到問題搜一下基本都是現(xiàn)成的答案。Spring Boot 3.x 相比 2.x 最大的變化是底層基于 Spring Framework 6支持 Jakarta EE 規(guī)范默認(rèn)使用 Java 17 及以上版本開發(fā)體驗和性能都有明顯提升。Vue 3 的組合式 API 寫起來比 Options API 更符合直覺配合 Vite 的開發(fā)服務(wù)器熱更新速度能縮短到一兩秒。數(shù)據(jù)庫我用 MySQL 8.0持久層框架選了 MyBatis Plus 而不是純 MyBatis原因很簡單——單表操作完全不需要手寫 SQL自帶的方法夠用復(fù)雜查詢再看情況寫 XML。鑒權(quán)方案采用 JWT Spring Security但做了簡化處理只用了 Spring Security 的加密工具類沒有引入完整的安全過濾鏈。很多全棧項目的通病是過度設(shè)計明明是個小項目卻把微服務(wù)、分布式那套全上了結(jié)果光搭建環(huán)境就花了大半時間。這次的實戰(zhàn)特意保持克制讓你能專注于理解核心鏈路。提示如果你的環(huán)境是 JDK 8暫時不想升級建議使用 Spring Boot 2.7.x 配合 Vue 2但同樣建議盡早升級。JDK 17 的垃圾回收性能和容器支持都比 8 好很多IntelliJ IDEA 2023 版本對 JDK 17 的支持也更順手。2. 整體設(shè)計與架構(gòu)拆解2.1 前后端分離架構(gòu)的邊界劃分全棧項目最容易犯的錯誤是職責(zé)混亂。前端代碼里塞后端邏輯后端代碼里混頁面模板時間一長代碼就成漿糊了。這次項目采用嚴(yán)格的前后端分離模式前端是純靜態(tài)資源通過 Axios 異步調(diào)用后端接口后端只負(fù)責(zé)提供 JSON 數(shù)據(jù)不做頁面渲染。簡單來說你可以把整套系統(tǒng)想象成一家餐廳前端是服務(wù)員負(fù)責(zé)記錄顧客需求、展示菜品渲染數(shù)據(jù)后端是后廚負(fù)責(zé)準(zhǔn)備菜品處理業(yè)務(wù)數(shù)據(jù)庫就是儲藏室。服務(wù)員不需要知道菜怎么做后廚也不需要直接和顧客溝通兩者之間的點菜單就是 API 接口。拿一個具體的業(yè)務(wù)場景來說用戶在前端頁面上登錄填完表單點擊提交按鈕Vue 組件把表單數(shù)據(jù)通過 POST 請求發(fā)送到后端的/api/login接口后端 Controller 接收請求調(diào) Service 層校驗用戶名密碼再調(diào) Mapper 層查數(shù)據(jù)庫校驗通過后生成一個 JWT token 返回給前端。前端收到 token 后存在 localStorage 里之后每次請求都在請求頭帶上這個 token后端用攔截器驗證 token 是否有效。整個鏈路中前端和后端各自獨立開發(fā)、獨立測試、獨立部署契約就是接口文檔。2.2 后端分層設(shè)計的職責(zé)劃分后端項目的包結(jié)構(gòu)按照經(jīng)典的三層架構(gòu)來組織Controller 層負(fù)責(zé)接收請求和參數(shù)校驗Service 層負(fù)責(zé)業(yè)務(wù)邏輯Mapper 層負(fù)責(zé)數(shù)據(jù)庫操作。在這個之上再加一個 Entity 包放實體類一個 DTO 包放數(shù)據(jù)傳輸對象一個 Config 包放配置類一個 Common 包放統(tǒng)一返回結(jié)果和異常處理。每個層之間通過接口和類來協(xié)作。Controller 不直接操作數(shù)據(jù)庫Service 不寫 SQLMapper 只做數(shù)據(jù)映射。剛?cè)腴T的開發(fā)者容易把業(yè)務(wù)代碼全堆在 Controller 里一個方法寫上百行看起來很“高效”實際上后面需求一變更就得重寫。我曾經(jīng)接手過一個項目登錄接口里直接拼 SQL 查數(shù)據(jù)庫后來要加驗證碼功能那叫一個費勁。打個比方三層架構(gòu)就像公司的三級審批——Controller 是前臺接待負(fù)責(zé)接需求和判斷訴求是否合理Service 是部門主管負(fù)責(zé)制定處理方案并協(xié)調(diào)資源Mapper 是具體執(zhí)行人負(fù)責(zé)落實細(xì)節(jié)。每一層只做自己該做的事出問題時能快速定位是哪個環(huán)節(jié)的鍋。2.3 前端組件化設(shè)計的模塊劃分前端項目按功能模塊劃分目錄結(jié)構(gòu)api目錄放接口請求封裝router目錄放路由配置stores目錄放 Pinia 狀態(tài)管理views目錄放頁面組件components目錄放公共組件。組件化設(shè)計的關(guān)鍵是找到合適的拆分粒度。舉個具體的例子后臺管理系統(tǒng)里常見的“用戶管理”頁面可以拆成搜索欄、表格、彈窗表單三個部分。搜索欄接收用戶輸入的查詢條件通過事件把條件拋給父組件父組件拿到條件后更新列表數(shù)據(jù)表格展示數(shù)據(jù)并監(jiān)聽行點擊彈窗表單負(fù)責(zé)新增和編輯。組件拆分有個度阿里推出的前端規(guī)范里提到一個原則如果一個組件太長超過合理范圍還沒法拆分出可復(fù)用的子組件可能就是職能不單一。反過來把組件拆得太碎也有問題——有一次我把一個簡單的列表頁拆成了十多個組件每個組件只有幾十行代碼結(jié)果傳參傳得頭暈調(diào)試一個 bug 得在文件間跳來跳去。一般的原則是只在組件被兩個以上地方復(fù)用或者單個組件的復(fù)雜度已經(jīng)明顯影響可讀性時才需要拆分。3. 環(huán)境準(zhǔn)備與項目初始化3.1 開發(fā)環(huán)境的版本選型與安裝清單先過一遍環(huán)境清單。后端需要 JDK 17、Maven 3.9、MySQL 8.0前端需要 Node.js 18我用的 20.12.0、npm或 pnpm/yarn這里用 npm、Vite 作為構(gòu)建工具。IDE 方面我推薦后端用 IntelliJ IDEA前端用 VS Code兩個都裝也沒問題。幾個需要注意的坑先提前說JDK 版本必須和環(huán)境變量匹配。裝了多個 JDK 的機器上IDEA 里配置的 Project SDK 和系統(tǒng)環(huán)境變量最好統(tǒng)一否則 Maven 編譯時可能用錯版本。Node.js 盡量用偶數(shù)版本。Node 官方對奇數(shù)次版本的支持時間較短有些依賴可能不兼容。當(dāng)年 Node 15 時代裝 Vite 就是各種問題后來學(xué)聰明了直接固定用最新 LTS 版本。MySQL 8.0 的認(rèn)證插件。默認(rèn)的caching_sha2_password在舊版連接驅(qū)動下會報錯Spring Boot 3.x 自帶的 MySQL Connector/J 8.x 沒問題但如果你的其他老項目還在用 5.x 驅(qū)動連接 MySQL 8 會失敗。安裝順序沒有硬性要求但建議先裝后端環(huán)境再裝前端環(huán)境。因為后端跑起來之后你可以先用 Postman 測試接口確認(rèn)沒問題再寫前端頁面這樣排查問題時范圍更清晰。3.2 后端項目初始化三步走先用 IntelliJ IDEA 創(chuàng)建 Spring Boot 項目。如果你用的是 IDEA 2023 版本可以直接在 New Project 里選 Spring InitializrGroup 填com.exampleArtifact 填fullstackJava 版本選 17依賴勾選 Spring Web、Spring Security可選也可以后面手動加、MySQL Driver、Lombok、Validation。需要補充說明的是Spring Initializr 生成的項目默認(rèn)帶一個mvnwMaven Wrapper它允許你在沒有全局安裝 Maven 的機器上直接執(zhí)行./mvnw命令來構(gòu)建項目這對保證構(gòu)建環(huán)境一致性很有幫助。如果你的機器沒有 Maven可以用它來代替mvn命令。項目生成后先別急著寫代碼把目錄補齊?；A(chǔ)結(jié)構(gòu)大概是src/main/java/com/example/fullstack ├── controller ├── service │ ├── impl ├── mapper ├── entity ├── dto ├── config └── common然后在pom.xml里加入 MyBatis Plus 的依賴。有個地方容易踩坑MyBatis Plus 在 Spring Boot 3.x 下需要引入mybatis-plus-spring-boot3-starter而不是mybatis-plus-boot-starter那是給 Spring Boot 2.x 用的。如果你用錯版本啟動時大概率會報Invalid value type for attribute factoryBeanObjectType之類的錯誤。配置文件application.yml按以下內(nèi)容配置server: port: 8080 spring: datasource: driver-class-name: com.mysql.cj.jdbc.Driver url: jdbc:mysql://localhost:3306/fullstack_db?useUnicodetruecharacterEncodingutf8serverTimezoneAsia/ShanghaiuseSSLfalse username: root password: your_password jackson: date-format: yyyy-MM-dd HH:mm:ss time-zone: Asia/Shanghai mybatis-plus: configuration: map-underscore-to-camel-case: true log-impl: org.apache.ibatis.logging.stdout.StdOutImpl global-config: db-config: id-type: auto這里有個細(xì)節(jié)Jackson 的日期格式設(shè)置很重要。如果前端傳來的日期字符串是2024-05-20 10:30:00格式后端 LocalDateTime 字段不加JsonFormat注解或全局配置默認(rèn)是 ISO 格式反序列化時就會報錯。全局配好省得每個字段都寫注解。3.3 前端項目初始化與依賴配置前端我用 Vite 創(chuàng)建項目命令如下npm create vitelatest frontend -- --template vue cd frontend npm install然后安裝項目需要的依賴npm install vue-router4 pinia axios element-plus選 Element Plus 做 UI 組件庫是國內(nèi)全棧項目的常見選擇它對中文場景支持好表格、表單、分頁這些后臺管理常用的組件都有現(xiàn)成的。同時安裝它的圖標(biāo)庫element-plus/icons-vue可以在全局注冊方便在菜單和按鈕里直接用圖標(biāo)。依賴裝完之后先配置 Vite 的代理和構(gòu)建選項。開發(fā)階段前端和后端分離運行需要把請求代理到后端服務(wù)生產(chǎn)階段前端構(gòu)建后的靜態(tài)文件由 Nginx 托管也需要配置轉(zhuǎn)發(fā)規(guī)則。在開發(fā)環(huán)境vite.config.js里加代理import { defineConfig } from vite import vue from vitejs/plugin-vue export default defineConfig({ plugins: [vue()], server: { port: 3000, proxy: { /api: { target: http://localhost:8080, changeOrigin: true } } } })這樣前端代碼里請求/api/login時Vite 會把請求轉(zhuǎn)發(fā)到http://localhost:8080/api/login繞過了開發(fā)環(huán)境下的跨域限制。生產(chǎn)環(huán)境則交給 Nginx 配置 location 塊做反向代理。提示配置代理解決的是開發(fā)階段的跨域問題。如果你的前后端部署在同一臺服務(wù)器、同一個域名下生產(chǎn)環(huán)境一般不需要跨域處理但如果部署在不同域名或端口下則要在后端加 CORS 配置。這個細(xì)節(jié)等到部署章節(jié)詳細(xì)講。4. 核心功能開發(fā)實操4.1 用戶認(rèn)證模塊的完整實現(xiàn)方案用戶認(rèn)證是幾乎所有全棧系統(tǒng)的剛性需求。我用 JWT 實現(xiàn)了這套認(rèn)證流程核心思路是用戶登錄成功后后端簽發(fā)一個有效期為一定時間的 token前端存儲這個 token在每次請求的 Authorization 請求頭里帶上來后端通過攔截器統(tǒng)一校驗。先說數(shù)據(jù)表結(jié)構(gòu)用戶表設(shè)計為CREATE TABLE sys_user ( id bigint(20) NOT NULL AUTO_INCREMENT, username varchar(50) NOT NULL COMMENT 用戶名, password varchar(100) NOT NULL COMMENT 加密后的密碼, nickname varchar(50) DEFAULT NULL COMMENT 昵稱, email varchar(100) DEFAULT NULL COMMENT 郵箱, status tinyint(4) DEFAULT 1 COMMENT 狀態(tài)1啟用 0禁用, create_time datetime DEFAULT NULL, update_time datetime DEFAULT NULL, PRIMARY KEY (id) ) ENGINEInnoDB AUTO_INCREMENT1 DEFAULT CHARSETutf8mb4;密碼存儲用的是 BCrypt 加密算法這是 Spring Security 里自帶的工具類不需要額外引依賴// 加密 String encodedPassword BCryptPasswordEncoder().encode(rawPassword); // 校驗 boolean matches encoder.matches(rawPassword, encodedPassword);這里有一個很容易被忽略的安全細(xì)節(jié)matches方法第一個參數(shù)是明文密碼第二個是數(shù)據(jù)庫里取出來的密文。我第一次寫的時候參數(shù)順序搞反了調(diào)試了半小時才發(fā)現(xiàn)是參數(shù)順序問題。另外注意 BCrypt 的加密結(jié)果是隨機的同一個明文每次加密出來的密文都不一樣所以不能用常規(guī)字符串比較必須用matches方法校驗。登錄接口的邏輯不復(fù)雜偽代碼是這樣的Controller 接收LoginRequest用戶名密碼Service 層根據(jù)用戶名查用戶如果用戶不存在直接拋異常提示“用戶名或密碼錯誤”注意這里的提示不能太具體否則會暴露用戶是否存在存在則用 BCrypt 校驗密碼失敗同樣提示“用戶名或密碼錯誤”成功后用用戶 ID、用戶名和當(dāng)前時間戳生成 JWT返回 token 用戶信息。4.2 JWT 攔截器的實現(xiàn)與請求鏈路JWT 攔截器是一個關(guān)鍵的“橫切關(guān)注點”。我用 Spring 的HandlerInterceptor實現(xiàn)配合 WebMvcConfigurer 注冊讓所有/api/**下的接口都經(jīng)過校驗登錄接口本身要放行。核心邏輯如下Component public class JwtInterceptor implements HandlerInterceptor { Autowired private JwtUtils jwtUtils; Override public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception { // 放行預(yù)檢請求 if (request.getMethod().equals(OPTIONS)) { return true; } // 前端約定 token 放在請求頭的 Authorization 字段中 String token request.getHeader(Authorization); if (token null || token.isEmpty()) { return this.unauthorized(response, 未登錄或登錄已過期); } // 校驗 token 合法性 try { String userId jwtUtils.getUserIdFromToken(token); request.setAttribute(userId, userId); return true; } catch (Exception e) { return this.unauthorized(response, token 無效或已過期); } } private boolean unauthorized(HttpServletResponse response, String msg) throws IOException { response.setStatus(401); response.setContentType(application/json;charsetutf-8); response.getWriter().write(JSON.toJSONString(Result.error(401, msg))); return false; } }注意一個細(xì)節(jié)預(yù)檢請求OPTIONS一定要放行。瀏覽器在跨域 POST 請求前會自動發(fā)送一個 OPTIONS 預(yù)檢請求如果你的攔截器把它攔下來了前端會報 CORS 錯誤而且這個錯誤在瀏覽器控制臺看起來像是后端 CORS 配置有問題實際上卻是攔截器沒放行 OPTIONS。攔截器只是一個粗粒度的路由守衛(wèi)對于不同接口的細(xì)粒度權(quán)限比如只有管理員能調(diào)用的接口可以在 Controller 方法上加自定義注解再在攔截器里讀取注解做二次判斷這個屬于權(quán)限系統(tǒng)的進(jìn)階內(nèi)容本次項目不做展開。4.3 用戶管理模塊的 CRUD 與分頁查詢用戶管理模塊雖然簡單但把前后端交互的典型模式都覆蓋了查詢列表、新增、編輯、刪除。我用 MyBatis Plus 的IService和BaseMapper框架代碼量比傳統(tǒng) MyBatis 少很多。Controller 層代碼示例RestController RequestMapping(/api/user) public class UserController { Autowired private UserService userService; GetMapping(/list) public ResultIPageUserVO list(RequestParam(defaultValue 1) Integer pageNum, RequestParam(defaultValue 10) Integer pageSize, String keyword) { PageUser page new Page(pageNum, pageSize); LambdaQueryWrapperUser wrapper new LambdaQueryWrapper(); if (StringUtils.hasText(keyword)) { wrapper.like(User::getUsername, keyword).or().like(User::getNickname, keyword); } wrapper.orderByDesc(User::getCreateTime); IPageUser userPage userService.page(page, wrapper); // 轉(zhuǎn) VO 返回不直接暴露實體 return Result.success(PageUtil.convert(userPage, UserVO.class)); } // 新增、編輯、刪除邏輯省略遵循同樣的模式 }細(xì)節(jié)問題來了新增用戶密碼需要加密存儲編輯用戶如果密碼為空說明不修改密碼。這些分情況討論的業(yè)務(wù)邏輯都放在 Service 層。Controller 里寫太多 if-else后面維護起來就想罵人。前端對應(yīng)這個接口的調(diào)用也是固定套路封裝在api/user.js模塊里import request from ../utils/request export function getUserList(data) { return request({ url: /user/list, method: get, params: data }) } export function addUser(data) { return request({ url: /user/add, method: post, data }) } // ...4.4 Axios 請求封裝的幾個關(guān)鍵決策點Axios 封裝的好壞直接決定整個前端項目請求代碼的整潔程度。我的做法是單獨建一個utils/request.js文件生成一個配置了基礎(chǔ) URL、超時時間和攔截器的 Axios 實例。核心代碼import axios from axios import { ElMessage } from element-plus import router from ../router const request axios.create({ baseURL: /api, timeout: 10000 }) // 請求攔截器自動附加 token request.interceptors.request.use( config { const token localStorage.getItem(token) if (token) { config.headers.Authorization token } return config }, error Promise.reject(error) ) // 響應(yīng)攔截器統(tǒng)一處理錯誤碼 request.interceptors.response.use( response { const res response.data // 如果后端返回了業(yè)務(wù)錯誤碼 if (res.code ! 200) { ElMessage.error(res.message || 請求失敗) if (res.code 401) { // token 過期跳轉(zhuǎn)登錄頁 localStorage.removeItem(token) router.push(/login) } return Promise.reject(new Error(res.message)) } return res.data }, error { ElMessage.error(error.message || 網(wǎng)絡(luò)錯誤) return Promise.reject(error) } ) export default request幾個決策點說一下。baseURL 設(shè)為/api配合 Vite 代理或 Nginx 反向代理前端代碼里就不用寫死后端地址環(huán)境切換時只需要改代理配置就行。響應(yīng)攔截器里把后端的code/message/data統(tǒng)一解開前端調(diào)用接口時直接拿到業(yè)務(wù)數(shù)據(jù)不需要每個調(diào)用處都寫.then(res res.data)。還有一個細(xì)節(jié)上的選擇token 存 localStorage 還是 sessionStorage。有人建議存 sessionStorage因為關(guān)閉瀏覽器就自動清掉安全一些但用戶希望刷新頁面后保持登錄狀態(tài)所以我用 localStorage。另外邏輯上要區(qū)分業(yè)務(wù)錯誤碼比如 500和 HTTP 狀態(tài)碼比如 404上述封裝里對這兩類錯誤都做了處理。5. 前端關(guān)鍵頁面與交互實現(xiàn)5.1 登錄頁的實現(xiàn)與表單校驗登錄頁是系統(tǒng)的“門面”雖然邏輯簡單但涉及的交互細(xì)節(jié)并不少。我用 Element Plus 的el-form組件實現(xiàn)配合它的表單校驗規(guī)則用戶名必填格式校驗長度 3-20 個字符。密碼必填長度 6-32 個字符。點擊登錄時先校驗表單通過后才發(fā)請求。登錄成功后跳轉(zhuǎn)到首頁并提示“歡迎回來xxx”。登錄頁有一個容易被忽視的用戶體驗問題請求失敗時表單要保留用戶輸入不能整個頁面刷新重置。Vue 的單頁應(yīng)用優(yōu)勢在這里體現(xiàn)得比較明顯。另外登錄按鈕在請求期間要處于 loading 狀態(tài)防止用戶重復(fù)提交。這些都是小細(xì)節(jié)但拿捏好才是專業(yè)的表現(xiàn)。關(guān)于“記住密碼”功能嚴(yán)謹(jǐn)?shù)拈_發(fā)不會把密碼存在前端通常只記住用戶名。這個項目我沒有做這個功能因為涉及敏感信息不做比做更安全。5.2 布局與路由守衛(wèi)后臺管理系統(tǒng)的典型布局是左側(cè)菜單欄 右側(cè)內(nèi)容區(qū)。我用 Element Plus 的el-container組件實現(xiàn)菜單數(shù)據(jù)直接寫死在路由配置里通過v-for循環(huán)渲染。路由配置的要點是嵌套路由const routes [ { path: /login, component: Login }, { path: /, component: Layout, redirect: /dashboard, children: [ { path: dashboard, name: Dashboard, component: Dashboard, meta: { title: 首頁, icon: HomeFilled } }, { path: user, name: User, component: UserManagement, meta: { title: 用戶管理, icon: User } } ] } ]路由守衛(wèi)是前端鑒權(quán)的另一道防線。在router.beforeEach里檢查是否登錄未登錄則重定向到登錄頁router.beforeEach((to, from, next) { const token localStorage.getItem(token) if (to.path /login) { next() } else { if (!token) { next({ path: /login }) } else { next() } } })提醒一句前端路由守衛(wèi)只是提升用戶體驗的手段不是安全措施。真正校驗 token 的有效性還得靠后端的攔截器因為用戶可以直接改前端代碼繞過路由守衛(wèi)。一切前端校驗都是“防君子不防小人”。5.3 表格、分頁與表單的聯(lián)動模式用戶管理頁面的核心交互是搜索欄輸入條件 → 點擊查詢 → 表格展示數(shù)據(jù) → 點擊編輯彈出表單 → 保存后刷新列表。這是后臺管理系統(tǒng)最高頻的交互模式。頁面數(shù)據(jù)結(jié)構(gòu)大概是searchForm搜索條件的響應(yīng)式數(shù)據(jù)tableData當(dāng)前頁的數(shù)據(jù)列表pageInfo頁碼、每頁條數(shù)、總條數(shù)dialogVisible彈窗顯隱formModel表單數(shù)據(jù)formRules表單校驗規(guī)則交互邏輯是點擊搜索時把頁碼重置為 1然后調(diào)用列表接口把返回的數(shù)據(jù)和總條數(shù)賦值給響應(yīng)式變量。前端代碼里分頁組件和表格的狀態(tài)同步是需要注意的地方el-pagination v-model:current-pagepageInfo.pageNum v-model:page-sizepageInfo.pageSize :totalpageInfo.total layouttotal, prev, pager, next, sizes changeloadData /需要注意el-pagination在 Element Plus 3.x 里事件名已經(jīng)改成了change舊版是current-change和size-change兩個事件分別處理。如果團隊里有老手用新版時還寫舊事件表格點擊分頁沒反應(yīng)排查老半天最后發(fā)現(xiàn)是事件名不對。彈出表單的編輯功能有一個常見坑編輯用戶時打開彈窗要把當(dāng)前行的數(shù)據(jù)深拷貝到表單模型里避免直接修改表格數(shù)據(jù)源。如果不做深拷貝彈窗里改字段時表格數(shù)據(jù)也會跟著變因為引用的是同一個對象。用JSON.parse(JSON.stringify(...))做深拷貝最簡單或者用展開運算符新建對象。5.4 狀態(tài)管理與跨組件通信的方案選擇Vue 3 中狀態(tài)管理的選擇比 Vue 2 時代豐富多了。Pinia 是官方推薦方案用它替代 Vuex 寫起來舒服得多沒有 mutations、actions 那套冗余的流程store 里定義的 state 直接用actions 就是一個普通函數(shù)。這個項目用到 Pinia 的場景用戶登錄后存基本信息和 token。在登錄成功時調(diào)用userStore.setLoginInfo(...)然后在多個組件里通過userStore.username展示當(dāng)前登錄用戶。示例代碼import { defineStore } from pinia export const useUserStore defineStore(user, { state: () ({ token: localStorage.getItem(token) || , userId: null, username: , nickname: }), actions: { setLoginInfo(data) { this.token data.token this.userId data.userId this.username data.username this.nickname data.nickname localStorage.setItem(token, data.token) }, logout() { this.token this.userId null this.username this.nickname localStorage.removeItem(token) } } })在這個系統(tǒng)里用戶信息需要全局共享但很多業(yè)務(wù)組件之間的通信其實用 props 和 emit 就夠。過度引入全局狀態(tài)管理會讓代碼難追蹤——某個字段不知道被誰修改了找起來很費勁。我的原則是跨頁面、跨層級深組件才考慮 Pinia父子組件之間能用 props/emit 就用 props/emit。6. 前后端聯(lián)調(diào)與常見問題排查6.1 聯(lián)調(diào)前的接口約定與準(zhǔn)備前后端分離開發(fā)模式下聯(lián)調(diào)階段往往是問題集中爆發(fā)的時期。前端認(rèn)為接口該這么返回后端認(rèn)為前端該那么傳參經(jīng)常對不上。經(jīng)驗是先定接口文檔再動代碼哪怕是簡單的表格約定、字段類型、命名風(fēng)格、錯誤碼都提前對齊。接口文檔我用 YApi 或者 Apifox 維護簡單項目也可以在項目根目錄放一個 Markdown 格式的接口說明文檔。文檔要約定如下內(nèi)容請求方式GET/POST/PUT/DELETE請求路徑和參數(shù)路徑參數(shù)、查詢參數(shù)、請求體參數(shù)參數(shù)類型string/number/boolean/object/array返回格式code/message/data 的結(jié)構(gòu)鑒權(quán)方式token 放在哪里怎么傳錯誤碼語義200 成功、401 未授權(quán)、500 服務(wù)器錯誤、業(yè)務(wù)錯誤從 400 開始聯(lián)調(diào)前先用 Postman 把后端接口全部測一遍。實測下來后端寫接口時引入一個全局性的統(tǒng)一返回結(jié)構(gòu)ResultT聯(lián)調(diào)效率能提升不少。前端看到code/message/data就知道怎么處理省去了解析各種怪異結(jié)構(gòu)的時間。我在項目里定義了一個通用返回體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(Integer code, String message) { ResultT result new Result(); result.setCode(code); result.setMessage(message); return result; } }任何接口都返回Result包裝后的對象異常處理用全局RestControllerAdvice捕獲并統(tǒng)一轉(zhuǎn)成這個格式前端就永遠(yuǎn)只需要處理一種結(jié)構(gòu)代碼邏輯非常簡單。6.2 跨域問題的三種表現(xiàn)與對應(yīng)解法跨域是全棧聯(lián)調(diào)最常遇到的問題但它有不同層次的原因癥狀相同解法不同。第一種開發(fā)環(huán)境跨域。前端在http://localhost:3000后端在http://localhost:8080。瀏覽器攔截了跨域請求。通用的解法是后端加 CORS 配置讓后端允許前端來源訪問。Configuration public class CorsConfig implements WebMvcConfigurer { Override public void addCorsMappings(CorsRegistry registry) { registry.addMapping(/**) .allowedOrigins(http://localhost:3000) .allowedMethods(GET, POST, PUT, DELETE, OPTIONS) .allowedHeaders(*) .allowCredentials(true) .maxAge(3600); } }但更推薦用 Vite 代理解決前端配置代理后前端請求的地址看起來是同源的。代理方式更好是因為它把跨域問題的處理留在了構(gòu)建層后端不需要關(guān)心前端運行在哪個端口而且開發(fā)環(huán)境和生產(chǎn)環(huán)境的代理配置方式保持一致生產(chǎn)環(huán)境用 Nginx。第二種后端接口報 CORS 錯誤但后端沒有 CORS 配置。這種情況多半是瀏覽器請求直接打到了后端地址而請求方式是非簡單請求比如 PUT/DELETE或者帶了自定義請求頭比如 Authorization。這時候瀏覽器會先發(fā) OPTIONS 預(yù)檢請求如果后端攔截器沒放行 OPTIONS就會報 CORS 錯。解決辦法是攔截器放行 OPTIONS。第三種生產(chǎn)環(huán)境跨域。前端和后端部署在不同域名。這種情況下最穩(wěn)妥的做法是用 Nginx 做反向代理讓前后端在同一個域名下前端請求/api路徑時 Nginx 轉(zhuǎn)發(fā)給后端服務(wù)。6.3 開發(fā)過程中遇到的高頻報錯速查表下面整理一份聯(lián)調(diào)階段的常見報錯和解決建議都是實操中反復(fù)出現(xiàn)的問題報錯現(xiàn)象可能原因解決方法前端請求掛起很久后報 timeout后端服務(wù)未啟動或接口路徑不對檢查后端日志確認(rèn)服務(wù)啟動檢查請求的路徑和 Controller 映射是否一致404 Not FoundURL 路徑寫錯或 Controller 方法沒有映射核對前端 api 模塊中的 URL 和后端RequestMapping是否有出入401 Unauthorizedtoken 缺失或無效確認(rèn)登錄是否成功、token 是否在請求頭中被正確攜帶500 后端報 NullPointerException后端代碼對 null 值沒有處理看異常堆棧定位到具體行號檢查參數(shù)是否為空數(shù)據(jù)庫中文亂碼數(shù)據(jù)庫連接串沒有指定字符集或者表默認(rèn)字符集錯誤在 JDBC URL 后加characterEncodingutf8建表時指定DEFAULT CHARSETutf8mb4MySQL 連接失敗 Public Key Retrieval is not allowed連接串缺少 allowPublicKeyRetrieval 參數(shù)JDBC URL 中加入allowPublicKeyRetrievaltrue打包前端后訪問頁面空白路由模式或靜態(tài)資源路徑配置問題如果使用 history 模式Nginx 要配置 try_files 重寫規(guī)則跨域報 Access-Control-Allow-OriginCORS 配置不當(dāng)按照上文跨域問題的三種表現(xiàn)依次排查6.4 前后端聯(lián)調(diào)中的時間同步與數(shù)據(jù)格式問題還有一種不報錯但結(jié)果不對的坑最典型的是時間字段。后端 LocalDateTime 序列化后得到的是2024-05-20T10:30:00而前端希望顯示的是2024-05-20 10:30:00。我見過不少項目因為時間格式對不上前端硬生生寫了個字符串替換函數(shù)來轉(zhuǎn)格式相當(dāng)丑陋。正確做法是在后端做好全局配置讓所有時間字段統(tǒng)一輸出為固定格式前端直接拿到標(biāo)準(zhǔn)字符串后展示或傳給后端。JSON 序列化這里再提一次在application.yml里加 Jackson 的時間格式配置代碼里不需要再給每個LocalDateTime字段加JsonFormat注解。不過要注意的是如果分頁返回的數(shù)據(jù)里包含時間排序序列化后的字符串格式影響不大只要保證比較的邏輯放在數(shù)據(jù)庫層面做就行。另一個常見問題是前端傳日期字符串給后端時后端用DateTimeFormat注解或全局配置 Jackson 的LocalDateTime反序列化格式來接收。我遇到過前端傳2024-05-20 10:30:00后端接收后解析失敗報 400 錯誤。這是因為 Fastjson 和 Jackson 對 LocalDateTime 支持有差異解決方式是統(tǒng)一用 Jackson并在全局配置里聲明日期格式。7. 項目打包與生產(chǎn)環(huán)境部署7.1 前端構(gòu)建與單頁應(yīng)用路由配置生產(chǎn)部署的第一步是前端構(gòu)建。執(zhí)行npm run buildVite 會生成dist目錄里面是壓縮后的靜態(tài)資源文件。這里要特別關(guān)注兩個點。第一構(gòu)建產(chǎn)物的路徑問題。如果你把前端部署在域名根路徑/下那baseURL保持/api沒問題但如果部署在子路徑比如https://example.com/admin下Vite 構(gòu)建時要在vite.config.js里配置base: /admin/否則靜態(tài)資源的引用路徑全部 404。第二前端路由的 history 模式需要服務(wù)端配合。Vue Router 的 history 模式URL 中不帶#刷新在子路由頁面比如/user時如果不配置服務(wù)端重寫規(guī)則Nginx 只會看文件系統(tǒng)里有沒有對應(yīng)的user目錄結(jié)果就是 404。Nginx 配置如下location / { root /usr/share/nginx/html; index index.html; try_files $uri $uri/ /index.html; }try_files的$uri先看請求路徑對應(yīng)的文件是否存在如果不存在就回退到/index.html由前端路由接管。7.2 后端打包與啟動腳本后端用 Maven 打包mvn clean package -DskipTests命令執(zhí)行完會在target目錄下生成fullstack-0.0.1-SNAPSHOT.jar。如果你用的是 Java 17 和 Spring Boot 3.x還有一個可執(zhí)行 jar 的特性Spring Boot 的 Maven 插件會自動配置 Main-Class你不需要額外配置直接java -jar就能運行。啟動命令java -jar fullstack-0.0.1-SNAPSHOT.jar --spring.profiles.activeprod生產(chǎn)環(huán)境的配置建議單獨建一個application-prod.yml里面配置生產(chǎn)環(huán)境用的數(shù)據(jù)庫地址、端口、日志級別等和開發(fā)環(huán)境區(qū)分開。日志輸出也建議配置到文件中不要只輸出到控制臺服務(wù)重啟后日志就丟了。一個典型的日志配置logging: level: com.example.fullstack: info file: name: logs/fullstack.log線上環(huán)境有個小建議用nohup啟動服務(wù)避免終端斷開時進(jìn)程被殺掉?；蛘吒?guī)范的寫法是注冊為 systemd 服務(wù)讓操作系統(tǒng)管理進(jìn)程生命周期開機自啟、崩潰重啟都能自動處理。7.3 Nginx 反向代理與服務(wù)部署細(xì)節(jié)Nginx 在這套系統(tǒng)中的角色是托管前端靜態(tài)文件 反向代理后端 API。完整配置參考如下server { listen 80; server_name your-domain.com; # 前端靜態(tài)資源 location / { root /var/www/frontend/dist; index index.html; try_files $uri $uri/ /index.html; } # 后端 API 反向代理 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; proxy_set_header X-Forwarded-Proto $scheme; } }這里有個細(xì)節(jié)location /api/加尾斜杠proxy_pass http://127.0.0.1:8080;不帶尾斜杠那 請求/api/user/list會轉(zhuǎn)發(fā)到http://127.0.0.1:8080/api/user/list路徑和原來保持一致。如果把proxy_pass寫成http://127.0.0.1:8080/請求會被轉(zhuǎn)發(fā)到http://127.0.0.1:8080/user/list/api前綴會被吞掉。這個細(xì)節(jié)容易踩坑務(wù)必確認(rèn)后端 Controller 的映射上有/api前綴否則會報 404。HTTPS 配置線上環(huán)境一般用 Certbot 自動申請證書并配置到 Nginx這里先不展開但強調(diào)一句生產(chǎn)環(huán)境不要裸奔 HTTP涉及登錄和 token 的接口不上 HTTPS 相當(dāng)于把門鎖掛在門外面。7.4 數(shù)據(jù)庫初始化與遷移策略生產(chǎn)環(huán)境數(shù)據(jù)庫初始化不能靠手動一條條執(zhí)行 SQL。我用 Flyway 做數(shù)據(jù)庫版本管理每次 SQL 變更寫一個帶版本號的文件放到resources/db/migration目錄應(yīng)用啟動時會自動執(zhí)行未執(zhí)行過的腳本。打比方說明一下Flyway 就像數(shù)據(jù)庫的 Git每次變更都是一個 commit版本號遞增它會在數(shù)據(jù)庫中建一張flyway_schema_history表來記錄已經(jīng)執(zhí)行過的版本下次啟動時自動跳過已執(zhí)行的只執(zhí)行新增的遷移腳本。示例遷移文件-- V1__create_user_table.sql CREATE TABLE sys_user ( id bigint(20) NOT NULL AUTO_INCREMENT, username varchar(50) NOT NULL COMMENT 用戶名, password varchar(100) NOT NULL COMMENT 加密后的密碼, nickname varchar(50) DEFAULT NULL COMMENT 昵稱, email varchar(100) DEFAULT NULL COMMENT 郵箱, status tinyint(4) DEFAULT 1 COMMENT 狀態(tài)1啟用 0禁用, create_time datetime DEFAULT NULL, update_time datetime DEFAULT NULL, PRIMARY KEY (id) ) ENGINEInnoDB AUTO_INCREMENT1 DEFAULT CHARSETutf8mb4;使用 Flyway 有兩點要非常謹(jǐn)慎已經(jīng)提交給團隊的遷移腳本不要修改哪怕里面 SQL 寫錯了也要靠新的遷移腳本來修正否則團隊的數(shù)據(jù)庫版本就對不上了。另外生產(chǎn)庫不要輕易執(zhí)行flyway clean它會重建整個數(shù)據(jù)庫操作前就算寫滿警告也不為過。8. 常用工具與效率提升清單8.1 接口調(diào)試工具的選擇聯(lián)調(diào)階段接口測試工具的作用很大。Postman 是最經(jīng)典的選擇優(yōu)勢是功能齊全、支持 Collection 管理、環(huán)境變量設(shè)置。Apifox 是國內(nèi)團隊常用的方案優(yōu)勢是集成了接口文檔管理、Mock 數(shù)據(jù)、自動化測試。如果項目中后端還沒有完全開發(fā)完Apifox 可以直接在接口文檔上生成 Mock 數(shù)據(jù)給前端先行開發(fā)這種前后端并行開發(fā)的模式能省不少時間。實際使用建議如果你是一個人做全棧直接用 IDEA 的 HTTP Client 就行不需要額外裝軟件。IDEA 里新建.http文件寫請求可以配合{{var}}使用環(huán)境變量還可以在后端代碼左側(cè)直接 Run 生成對應(yīng)的測試請求效率很高。8.2 數(shù)據(jù)庫連接與查詢工具數(shù)據(jù)庫客戶端方面Navicat 和 DataGrip 都常用。Navicat 功能全面、界面友好DataGrip 更適合寫復(fù)雜 SQL它提供的智能提示和格式化功能非常好用。個人項目簡單查詢用 VS Code 的 MySQL 插件也可以湊合。我的建議是對于持久層查詢用 MyBatis Plus 的LambdaQueryWrapper寫條件查詢已經(jīng)非常直觀大多數(shù)場景不需要打開數(shù)據(jù)庫客戶端。只有在排查數(shù)據(jù)問題時才需要連數(shù)據(jù)庫。遇到數(shù)據(jù)庫連接不上的情況先檢查服務(wù)是否啟動、端口是否被占用、認(rèn)證插件版本是否匹配這三個點大多數(shù)問題都能解決。8.3 聯(lián)調(diào)排查常用的瀏覽器開發(fā)者工具前端調(diào)試離不開瀏覽器開發(fā)者工具。Network 面板能看到每個請求的狀態(tài)碼、耗時、請求頭和響應(yīng)體Console 面板直接報錯信息Vue 專門有 Vue DevTools 插件可以查看組件樹、Pinia 狀態(tài)和路由信息。排查問題建議按照這個順序來看先在 Network 里確認(rèn)請求發(fā)出去了沒有、狀態(tài)碼是多少再看請求頭里的 Content-Type 和 Authorization 對不對然后看響應(yīng)體里的具體數(shù)據(jù)最后結(jié)合 Console 的報錯信息定位問題。有的開發(fā)者一上來就在代碼里打斷點其實大多數(shù)聯(lián)調(diào)問題在網(wǎng)絡(luò)請求這一層就能定位。8.4 代碼生成器的合理使用到了項目后期增刪改查的代碼寫多了會產(chǎn)生明顯的機械重復(fù)感。手動復(fù)制粘貼再改字段名容易出錯我保留了一條規(guī)則多表關(guān)聯(lián)、復(fù)雜業(yè)務(wù)邏輯的代碼必須手寫但單表 CRUD 的代碼交給生成器生成生成完再人工審查和微調(diào)。MyBatis Plus 官方提供了一個代碼生成器mybatis-plus-generator可以根據(jù)數(shù)據(jù)庫表自動生成 Entity、Mapper、Service、Controller 代碼。用它的時機設(shè)置在項目初始化階段把表結(jié)構(gòu)設(shè)計好一鍵生成基礎(chǔ)代碼后面再在 Service 中補充業(yè)務(wù)邏輯。這能省去大量重復(fù)勞動但你一定要會改生成的代碼不然會陷入“低級錯誤看不出來”的局面。9. 項目擴展方向與進(jìn)階建議9.1 從單體應(yīng)用到模塊化演進(jìn)當(dāng)前項目的結(jié)構(gòu)是單體應(yīng)用這個結(jié)構(gòu)適合大多數(shù)中小型項目。隨著業(yè)務(wù)量增長你可以按模塊拆分比如用戶模塊、訂單模塊、商品模塊每個模塊獨立成一個 Maven 模塊甚至獨立成一個 Spring Boot 服務(wù)。拆分的關(guān)鍵依據(jù)是團隊規(guī)模和部署復(fù)雜度不要因為趨勢而盲目拆分。如果項目超過 10 個接口、3 個以上開發(fā)人員合理的模塊化拆分能明顯減少合并沖突和協(xié)作成本。反過來如果就是一個人的項目拆成微服務(wù)純屬自找麻煩。9.2 引入 Redis 緩存與接口性能優(yōu)化項目中如果有熱點數(shù)據(jù)比如用戶信息、系統(tǒng)配置可以引入 Redis 做緩存層。實現(xiàn)方式是在原有的 Service 邏輯包一層先查緩存緩存未命中再查數(shù)據(jù)庫同時把結(jié)果寫入緩存并設(shè)置過期時間。用 Redis 的StringRedisTemplate就夠不需要引入復(fù)雜的緩存框架。這個實踐我建議放到項目穩(wěn)定之后再做第二個版本迭代。先保證功能正確再考慮性能。接口響應(yīng)時間慢先看是不是數(shù)據(jù)庫查詢的問題有沒有索引、有沒有 N1 查詢再決定要不要加緩存。過早引入緩存會讓 bug 排查多一層維度代價不小。9.3 安全加固與權(quán)限模型的進(jìn)階方向做全棧項目時很多人忽略了權(quán)限設(shè)計。目前項目只有“登錄/未登錄”兩層。如果你的系統(tǒng)需要不同角色管理員、普通用戶、訪客可以引入 RBAC 權(quán)限模型用戶-角色-權(quán)限三層結(jié)構(gòu)。表設(shè)計上新建sys_role、sys_menu、sys_user_role、sys_role_menu四張表后端在攔截器或注解層面校驗是否有指定權(quán)限。前端對應(yīng)地可以做動態(tài)路由用戶登錄后根據(jù)后端返回的權(quán)限列表動態(tài)生成可訪問的路由配置。這個是很多全棧項目的進(jìn)階難點會接觸到更深的前后端正交互。建議把當(dāng)前項目跑通后再往這個方向升級每一步都是新的技術(shù)內(nèi)容。9.4 前端工程化的進(jìn)一步打磨前端部分可以繼續(xù)打磨的點很多代碼規(guī)范ESLint Prettier、提交規(guī)范Commitlint husky、單元測試Vitest、自動化部署GitHub Actions。這些屬于前端工程化范疇。舉一個很實用的例子在項目里加 ESLint 和 Prettier 配置團隊協(xié)作時代碼風(fēng)格統(tǒng)一少了無謂的爭吵。不建議一開始就上全量工程化配置先把項目跑通再逐步加上這些工具學(xué)習(xí)曲線更平滑。10. 完整的實操流程對照表下表整理了這個項目從零到上線的完整操作清單按順序執(zhí)行每完成一步打一個勾階段關(guān)鍵操作產(chǎn)出物耗時預(yù)估環(huán)境準(zhǔn)備JDK 17、Maven、Node.js 20、MySQL 8開發(fā)環(huán)境跑通0.5 天數(shù)據(jù)庫設(shè)計創(chuàng)建數(shù)據(jù)庫和表、初始化測試數(shù)據(jù)SQL 腳本0.5 天后端骨架創(chuàng)建 Spring Boot 項目、MyBatis Plus 配置可啟動空項目0.5 天后端核心接口登錄、CRUD、攔截器、全局異常處理可測試的 REST API2-3 天前端骨架Vite 創(chuàng)建項目、配置路由、Pinia、Axios可運行前端基礎(chǔ)工程1 天前端頁面開發(fā)登錄頁、布局頁、用戶管理頁可交互的完整頁面2-3 天前后端聯(lián)調(diào)測試登錄流程、CRUD 流程、異常流程完整的業(yè)務(wù)閉環(huán)1 天打包部署前端 build、后端 jar、Nginx 配置生產(chǎn)環(huán)境可訪問系統(tǒng)1 天上線檢查安全、日志、備份、監(jiān)控穩(wěn)定運行的系統(tǒng)0.5 天這是一個典型的個人全棧項目的工期預(yù)估。如果你是第一次做時間會翻倍正常現(xiàn)象。如果遇到卡殼超過半天的問題建議跳過去先把主流程跑通再回頭看卡住的部分。我個人的經(jīng)驗是全棧開發(fā)能力的提升不是線性的而是靠一個個完整的項目串起來的。這個項目雖然從技術(shù)角度看每個環(huán)節(jié)都是“常用技術(shù)”但當(dāng)它們組合在一起形成完整閉環(huán)時你對前端和后端協(xié)作模式的理解會上一個臺階。當(dāng)你遇到任何業(yè)務(wù)需求時腦子里能浮現(xiàn)出完整的請求鏈路和數(shù)據(jù)流轉(zhuǎn)圖而不是只盯著自己熟悉的那一層這就算真正入門了。