1. 項目概述1.1 核心需求解析做全棧開發(fā)這幾年我見過太多半路出家的開發(fā)者在 Spring Boot 和 Vue 的邊界線上反復橫跳——后端能寫接口但前端拿著 JSON 不知道往哪兒塞前端能把頁面畫出來但遇到跨域、鑒權、打包部署就抓瞎。這個實戰(zhàn)指南解決的就是這個問題把一條完整的前后端分離開發(fā)鏈路串起來從零開始搭建一個可直接運行的全棧項目。注意這里的關鍵詞是“全棧”不是“前后端各寫一半”。項目會包含一個完整的業(yè)務閉環(huán)前端 Vue 負責頁面交互和數(shù)據(jù)展示后端 Spring Boot 負責接口服務和數(shù)據(jù)持久化中間通過 RESTful API 通信最終打包部署到同一臺服務器上跑通整個流程。這個過程中涉及的技術點非常密集——Vue 的生命周期、Axios 的請求攔截、Spring Boot 的分層架構、MyBatis 的數(shù)據(jù)映射、JWT 的登錄態(tài)管理、Nginx 的反向代理——任何一個環(huán)節(jié)掉鏈子整個項目就跑不起來。這個項目的受眾其實很廣。剛入行的初級開發(fā)者可以通過它建立全棧思維知道前端發(fā)起的請求在后端到底經歷了什么寫了好幾年接口的后端開發(fā)可以補上前端技能獨立負責完整模塊做畢設或小團隊項目的同學可以直接拿這套骨架改業(yè)務邏輯就能上線。我的建議是無論你偏向前端還是后端都完整地把項目過一遍收獲最大的恰恰是你知識短板那部分的內容。1.2 技術棧全景與選型理由Spring Boot 3.x 搭配 Vue 3.x 是當前主流選擇我用的版本組合是 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ī)范默認使用 Java 17 及以上版本開發(fā)體驗和性能都有明顯提升。Vue 3 的組合式 API 寫起來比 Options API 更符合直覺配合 Vite 的開發(fā)服務器熱更新速度能縮短到一兩秒。數(shù)據(jù)庫我用 MySQL 8.0持久層框架選了 MyBatis Plus 而不是純 MyBatis原因很簡單——單表操作完全不需要手寫 SQL自帶的方法夠用復雜查詢再看情況寫 XML。鑒權方案采用 JWT Spring Security但做了簡化處理只用了 Spring Security 的加密工具類沒有引入完整的安全過濾鏈。很多全棧項目的通病是過度設計明明是個小項目卻把微服務、分布式那套全上了結果光搭建環(huán)境就花了大半時間。這次的實戰(zhàn)特意保持克制讓你能專注于理解核心鏈路。提示如果你的環(huán)境是 JDK 8暫時不想升級建議使用 Spring Boot 2.7.x 配合 Vue 2但同樣建議盡早升級。JDK 17 的垃圾回收性能和容器支持都比 8 好很多IntelliJ IDEA 2023 版本對 JDK 17 的支持也更順手。2. 整體設計與架構拆解2.1 前后端分離架構的邊界劃分全棧項目最容易犯的錯誤是職責混亂。前端代碼里塞后端邏輯后端代碼里混頁面模板時間一長代碼就成漿糊了。這次項目采用嚴格的前后端分離模式前端是純靜態(tài)資源通過 Axios 異步調用后端接口后端只負責提供 JSON 數(shù)據(jù)不做頁面渲染。簡單來說你可以把整套系統(tǒng)想象成一家餐廳前端是服務員負責記錄顧客需求、展示菜品渲染數(shù)據(jù)后端是后廚負責準備菜品處理業(yè)務數(shù)據(jù)庫就是儲藏室。服務員不需要知道菜怎么做后廚也不需要直接和顧客溝通兩者之間的點菜單就是 API 接口。拿一個具體的業(yè)務場景來說用戶在前端頁面上登錄填完表單點擊提交按鈕Vue 組件把表單數(shù)據(jù)通過 POST 請求發(fā)送到后端的/api/login接口后端 Controller 接收請求調 Service 層校驗用戶名密碼再調 Mapper 層查數(shù)據(jù)庫校驗通過后生成一個 JWT token 返回給前端。前端收到 token 后存在 localStorage 里之后每次請求都在請求頭帶上這個 token后端用攔截器驗證 token 是否有效。整個鏈路中前端和后端各自獨立開發(fā)、獨立測試、獨立部署契約就是接口文檔。2.2 后端分層設計的職責劃分后端項目的包結構按照經典的三層架構來組織Controller 層負責接收請求和參數(shù)校驗Service 層負責業(yè)務邏輯Mapper 層負責數(shù)據(jù)庫操作。在這個之上再加一個 Entity 包放實體類一個 DTO 包放數(shù)據(jù)傳輸對象一個 Config 包放配置類一個 Common 包放統(tǒng)一返回結果和異常處理。每個層之間通過接口和類來協(xié)作。Controller 不直接操作數(shù)據(jù)庫Service 不寫 SQLMapper 只做數(shù)據(jù)映射。剛入門的開發(fā)者容易把業(yè)務代碼全堆在 Controller 里一個方法寫上百行看起來很“高效”實際上后面需求一變更就得重寫。我曾經接手過一個項目登錄接口里直接拼 SQL 查數(shù)據(jù)庫后來要加驗證碼功能那叫一個費勁。打個比方三層架構就像公司的三級審批——Controller 是前臺接待負責接需求和判斷訴求是否合理Service 是部門主管負責制定處理方案并協(xié)調資源Mapper 是具體執(zhí)行人負責落實細節(jié)。每一層只做自己該做的事出問題時能快速定位是哪個環(huán)節(jié)的鍋。2.3 前端組件化設計的模塊劃分前端項目按功能模塊劃分目錄結構api目錄放接口請求封裝router目錄放路由配置stores目錄放 Pinia 狀態(tài)管理views目錄放頁面組件components目錄放公共組件。組件化設計的關鍵是找到合適的拆分粒度。舉個具體的例子后臺管理系統(tǒng)里常見的“用戶管理”頁面可以拆成搜索欄、表格、彈窗表單三個部分。搜索欄接收用戶輸入的查詢條件通過事件把條件拋給父組件父組件拿到條件后更新列表數(shù)據(jù)表格展示數(shù)據(jù)并監(jiān)聽行點擊彈窗表單負責新增和編輯。組件拆分有個度阿里推出的前端規(guī)范里提到一個原則如果一個組件太長超過合理范圍還沒法拆分出可復用的子組件可能就是職能不單一。反過來把組件拆得太碎也有問題——有一次我把一個簡單的列表頁拆成了十多個組件每個組件只有幾十行代碼結果傳參傳得頭暈調試一個 bug 得在文件間跳來跳去。一般的原則是只在組件被兩個以上地方復用或者單個組件的復雜度已經明顯影響可讀性時才需要拆分。3. 環(huá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 作為構建工具。IDE 方面我推薦后端用 IntelliJ IDEA前端用 VS Code兩個都裝也沒問題。幾個需要注意的坑先提前說JDK 版本必須和環(huán)境變量匹配。裝了多個 JDK 的機器上IDEA 里配置的 Project SDK 和系統(tǒng)環(huán)境變量最好統(tǒng)一否則 Maven 編譯時可能用錯版本。Node.js 盡量用偶數(shù)版本。Node 官方對奇數(shù)次版本的支持時間較短有些依賴可能不兼容。當年 Node 15 時代裝 Vite 就是各種問題后來學聰明了直接固定用最新 LTS 版本。MySQL 8.0 的認證插件。默認的caching_sha2_password在舊版連接驅動下會報錯Spring Boot 3.x 自帶的 MySQL Connector/J 8.x 沒問題但如果你的其他老項目還在用 5.x 驅動連接 MySQL 8 會失敗。安裝順序沒有硬性要求但建議先裝后端環(huán)境再裝前端環(huán)境。因為后端跑起來之后你可以先用 Postman 測試接口確認沒問題再寫前端頁面這樣排查問題時范圍更清晰。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 生成的項目默認帶一個mvnwMaven Wrapper它允許你在沒有全局安裝 Maven 的機器上直接執(zhí)行./mvnw命令來構建項目這對保證構建環(huán)境一致性很有幫助。如果你的機器沒有 Maven可以用它來代替mvn命令。項目生成后先別急著寫代碼把目錄補齊。基礎結構大概是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按以下內容配置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這里有個細節(jié)Jackson 的日期格式設置很重要。如果前端傳來的日期字符串是2024-05-20 10:30:00格式后端 LocalDateTime 字段不加JsonFormat注解或全局配置默認是 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 組件庫是國內全棧項目的常見選擇它對中文場景支持好表格、表單、分頁這些后臺管理常用的組件都有現(xiàn)成的。同時安裝它的圖標庫element-plus/icons-vue可以在全局注冊方便在菜單和按鈕里直接用圖標。依賴裝完之后先配置 Vite 的代理和構建選項。開發(fā)階段前端和后端分離運行需要把請求代理到后端服務生產階段前端構建后的靜態(tài)文件由 Nginx 托管也需要配置轉發(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 會把請求轉發(fā)到http://localhost:8080/api/login繞過了開發(fā)環(huán)境下的跨域限制。生產環(huán)境則交給 Nginx 配置 location 塊做反向代理。提示配置代理解決的是開發(fā)階段的跨域問題。如果你的前后端部署在同一臺服務器、同一個域名下生產環(huán)境一般不需要跨域處理但如果部署在不同域名或端口下則要在后端加 CORS 配置。這個細節(jié)等到部署章節(jié)詳細講。4. 核心功能開發(fā)實操4.1 用戶認證模塊的完整實現(xiàn)方案用戶認證是幾乎所有全棧系統(tǒng)的剛性需求。我用 JWT 實現(xiàn)了這套認證流程核心思路是用戶登錄成功后后端簽發(fā)一個有效期為一定時間的 token前端存儲這個 token在每次請求的 Authorization 請求頭里帶上來后端通過攔截器統(tǒng)一校驗。先說數(shù)據(jù)表結構用戶表設計為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);這里有一個很容易被忽略的安全細節(jié)matches方法第一個參數(shù)是明文密碼第二個是數(shù)據(jù)庫里取出來的密文。我第一次寫的時候參數(shù)順序搞反了調試了半小時才發(fā)現(xiàn)是參數(shù)順序問題。另外注意 BCrypt 的加密結果是隨機的同一個明文每次加密出來的密文都不一樣所以不能用常規(guī)字符串比較必須用matches方法校驗。登錄接口的邏輯不復雜偽代碼是這樣的Controller 接收LoginRequest用戶名密碼Service 層根據(jù)用戶名查用戶如果用戶不存在直接拋異常提示“用戶名或密碼錯誤”注意這里的提示不能太具體否則會暴露用戶是否存在存在則用 BCrypt 校驗密碼失敗同樣提示“用戶名或密碼錯誤”成功后用用戶 ID、用戶名和當前時間戳生成 JWT返回 token 用戶信息。4.2 JWT 攔截器的實現(xiàn)與請求鏈路JWT 攔截器是一個關鍵的“橫切關注點”。我用 Spring 的HandlerInterceptor實現(xiàn)配合 WebMvcConfigurer 注冊讓所有/api/**下的接口都經過校驗登錄接口本身要放行。核心邏輯如下Component public class JwtInterceptor implements HandlerInterceptor { Autowired private JwtUtils jwtUtils; Override public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception { // 放行預檢請求 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; } }注意一個細節(jié)預檢請求OPTIONS一定要放行。瀏覽器在跨域 POST 請求前會自動發(fā)送一個 OPTIONS 預檢請求如果你的攔截器把它攔下來了前端會報 CORS 錯誤而且這個錯誤在瀏覽器控制臺看起來像是后端 CORS 配置有問題實際上卻是攔截器沒放行 OPTIONS。攔截器只是一個粗粒度的路由守衛(wèi)對于不同接口的細粒度權限比如只有管理員能調用的接口可以在 Controller 方法上加自定義注解再在攔截器里讀取注解做二次判斷這個屬于權限系統(tǒng)的進階內容本次項目不做展開。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); // 轉 VO 返回不直接暴露實體 return Result.success(PageUtil.convert(userPage, UserVO.class)); } // 新增、編輯、刪除邏輯省略遵循同樣的模式 }細節(jié)問題來了新增用戶密碼需要加密存儲編輯用戶如果密碼為空說明不修改密碼。這些分情況討論的業(yè)務邏輯都放在 Service 層。Controller 里寫太多 if-else后面維護起來就想罵人。前端對應這個接口的調用也是固定套路封裝在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 請求封裝的幾個關鍵決策點Axios 封裝的好壞直接決定整個前端項目請求代碼的整潔程度。我的做法是單獨建一個utils/request.js文件生成一個配置了基礎 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) ) // 響應攔截器統(tǒng)一處理錯誤碼 request.interceptors.response.use( response { const res response.data // 如果后端返回了業(yè)務錯誤碼 if (res.code ! 200) { ElMessage.error(res.message || 請求失敗) if (res.code 401) { // token 過期跳轉登錄頁 localStorage.removeItem(token) router.push(/login) } return Promise.reject(new Error(res.message)) } return res.data }, error { ElMessage.error(error.message || 網絡錯誤) return Promise.reject(error) } ) export default request幾個決策點說一下。baseURL 設為/api配合 Vite 代理或 Nginx 反向代理前端代碼里就不用寫死后端地址環(huán)境切換時只需要改代理配置就行。響應攔截器里把后端的code/message/data統(tǒng)一解開前端調用接口時直接拿到業(yè)務數(shù)據(jù)不需要每個調用處都寫.then(res res.data)。還有一個細節(jié)上的選擇token 存 localStorage 還是 sessionStorage。有人建議存 sessionStorage因為關閉瀏覽器就自動清掉安全一些但用戶希望刷新頁面后保持登錄狀態(tài)所以我用 localStorage。另外邏輯上要區(qū)分業(yè)務錯誤碼比如 500和 HTTP 狀態(tài)碼比如 404上述封裝里對這兩類錯誤都做了處理。5. 前端關鍵頁面與交互實現(xiàn)5.1 登錄頁的實現(xiàn)與表單校驗登錄頁是系統(tǒng)的“門面”雖然邏輯簡單但涉及的交互細節(jié)并不少。我用 Element Plus 的el-form組件實現(xiàn)配合它的表單校驗規(guī)則用戶名必填格式校驗長度 3-20 個字符。密碼必填長度 6-32 個字符。點擊登錄時先校驗表單通過后才發(fā)請求。登錄成功后跳轉到首頁并提示“歡迎回來xxx”。登錄頁有一個容易被忽視的用戶體驗問題請求失敗時表單要保留用戶輸入不能整個頁面刷新重置。Vue 的單頁應用優(yōu)勢在這里體現(xiàn)得比較明顯。另外登錄按鈕在請求期間要處于 loading 狀態(tài)防止用戶重復提交。這些都是小細節(jié)但拿捏好才是專業(yè)的表現(xiàn)。關于“記住密碼”功能嚴謹?shù)拈_發(fā)不會把密碼存在前端通常只記住用戶名。這個項目我沒有做這個功能因為涉及敏感信息不做比做更安全。5.2 布局與路由守衛(wèi)后臺管理系統(tǒng)的典型布局是左側菜單欄 右側內容區(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)是前端鑒權的另一道防線。在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ù)結構大概是searchForm搜索條件的響應式數(shù)據(jù)tableData當前頁的數(shù)據(jù)列表pageInfo頁碼、每頁條數(shù)、總條數(shù)dialogVisible彈窗顯隱formModel表單數(shù)據(jù)formRules表單校驗規(guī)則交互邏輯是點擊搜索時把頁碼重置為 1然后調用列表接口把返回的數(shù)據(jù)和總條數(shù)賦值給響應式變量。前端代碼里分頁組件和表格的狀態(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 里事件名已經改成了change舊版是current-change和size-change兩個事件分別處理。如果團隊里有老手用新版時還寫舊事件表格點擊分頁沒反應排查老半天最后發(fā)現(xiàn)是事件名不對。彈出表單的編輯功能有一個常見坑編輯用戶時打開彈窗要把當前行的數(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。在登錄成功時調用userStore.setLoginInfo(...)然后在多個組件里通過userStore.username展示當前登錄用戶。示例代碼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è)務組件之間的通信其實用 props 和 emit 就夠。過度引入全局狀態(tài)管理會讓代碼難追蹤——某個字段不知道被誰修改了找起來很費勁。我的原則是跨頁面、跨層級深組件才考慮 Pinia父子組件之間能用 props/emit 就用 props/emit。6. 前后端聯(lián)調與常見問題排查6.1 聯(lián)調前的接口約定與準備前后端分離開發(fā)模式下聯(lián)調階段往往是問題集中爆發(fā)的時期。前端認為接口該這么返回后端認為前端該那么傳參經常對不上。經驗是先定接口文檔再動代碼哪怕是簡單的表格約定、字段類型、命名風格、錯誤碼都提前對齊。接口文檔我用 YApi 或者 Apifox 維護簡單項目也可以在項目根目錄放一個 Markdown 格式的接口說明文檔。文檔要約定如下內容請求方式GET/POST/PUT/DELETE請求路徑和參數(shù)路徑參數(shù)、查詢參數(shù)、請求體參數(shù)參數(shù)類型string/number/boolean/object/array返回格式code/message/data 的結構鑒權方式token 放在哪里怎么傳錯誤碼語義200 成功、401 未授權、500 服務器錯誤、業(yè)務錯誤從 400 開始聯(lián)調前先用 Postman 把后端接口全部測一遍。實測下來后端寫接口時引入一個全局性的統(tǒng)一返回結構ResultT聯(lián)調效率能提升不少。前端看到code/message/data就知道怎么處理省去了解析各種怪異結構的時間。我在項目里定義了一個通用返回體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)一轉成這個格式前端就永遠只需要處理一種結構代碼邏輯非常簡單。6.2 跨域問題的三種表現(xiàn)與對應解法跨域是全棧聯(lián)調最常遇到的問題但它有不同層次的原因癥狀相同解法不同。第一種開發(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 代理解決前端配置代理后前端請求的地址看起來是同源的。代理方式更好是因為它把跨域問題的處理留在了構建層后端不需要關心前端運行在哪個端口而且開發(fā)環(huán)境和生產環(huán)境的代理配置方式保持一致生產環(huán)境用 Nginx。第二種后端接口報 CORS 錯誤但后端沒有 CORS 配置。這種情況多半是瀏覽器請求直接打到了后端地址而請求方式是非簡單請求比如 PUT/DELETE或者帶了自定義請求頭比如 Authorization。這時候瀏覽器會先發(fā) OPTIONS 預檢請求如果后端攔截器沒放行 OPTIONS就會報 CORS 錯。解決辦法是攔截器放行 OPTIONS。第三種生產環(huán)境跨域。前端和后端部署在不同域名。這種情況下最穩(wěn)妥的做法是用 Nginx 做反向代理讓前后端在同一個域名下前端請求/api路徑時 Nginx 轉發(fā)給后端服務。6.3 開發(fā)過程中遇到的高頻報錯速查表下面整理一份聯(lián)調階段的常見報錯和解決建議都是實操中反復出現(xiàn)的問題報錯現(xiàn)象可能原因解決方法前端請求掛起很久后報 timeout后端服務未啟動或接口路徑不對檢查后端日志確認服務啟動檢查請求的路徑和 Controller 映射是否一致404 Not FoundURL 路徑寫錯或 Controller 方法沒有映射核對前端 api 模塊中的 URL 和后端RequestMapping是否有出入401 Unauthorizedtoken 缺失或無效確認登錄是否成功、token 是否在請求頭中被正確攜帶500 后端報 NullPointerException后端代碼對 null 值沒有處理看異常堆棧定位到具體行號檢查參數(shù)是否為空數(shù)據(jù)庫中文亂碼數(shù)據(jù)庫連接串沒有指定字符集或者表默認字符集錯誤在 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 配置不當按照上文跨域問題的三種表現(xiàn)依次排查6.4 前后端聯(lián)調中的時間同步與數(shù)據(jù)格式問題還有一種不報錯但結果不對的坑最典型的是時間字段。后端 LocalDateTime 序列化后得到的是2024-05-20T10:30:00而前端希望顯示的是2024-05-20 10:30:00。我見過不少項目因為時間格式對不上前端硬生生寫了個字符串替換函數(shù)來轉格式相當丑陋。正確做法是在后端做好全局配置讓所有時間字段統(tǒng)一輸出為固定格式前端直接拿到標準字符串后展示或傳給后端。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. 項目打包與生產環(huán)境部署7.1 前端構建與單頁應用路由配置生產部署的第一步是前端構建。執(zhí)行npm run buildVite 會生成dist目錄里面是壓縮后的靜態(tài)資源文件。這里要特別關注兩個點。第一構建產物的路徑問題。如果你把前端部署在域名根路徑/下那baseURL保持/api沒問題但如果部署在子路徑比如https://example.com/admin下Vite 構建時要在vite.config.js里配置base: /admin/否則靜態(tài)資源的引用路徑全部 404。第二前端路由的 history 模式需要服務端配合。Vue Router 的 history 模式URL 中不帶#刷新在子路由頁面比如/user時如果不配置服務端重寫規(guī)則Nginx 只會看文件系統(tǒng)里有沒有對應的user目錄結果就是 404。Nginx 配置如下location / { root /usr/share/nginx/html; index index.html; try_files $uri $uri/ /index.html; }try_files的$uri先看請求路徑對應的文件是否存在如果不存在就回退到/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生產環(huán)境的配置建議單獨建一個application-prod.yml里面配置生產環(huán)境用的數(shù)據(jù)庫地址、端口、日志級別等和開發(fā)環(huán)境區(qū)分開。日志輸出也建議配置到文件中不要只輸出到控制臺服務重啟后日志就丟了。一個典型的日志配置logging: level: com.example.fullstack: info file: name: logs/fullstack.log線上環(huán)境有個小建議用nohup啟動服務避免終端斷開時進程被殺掉?；蛘吒?guī)范的寫法是注冊為 systemd 服務讓操作系統(tǒng)管理進程生命周期開機自啟、崩潰重啟都能自動處理。7.3 Nginx 反向代理與服務部署細節(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; } }這里有個細節(jié)location /api/加尾斜杠proxy_pass http://127.0.0.1:8080;不帶尾斜杠那 請求/api/user/list會轉發(fā)到http://127.0.0.1:8080/api/user/list路徑和原來保持一致。如果把proxy_pass寫成http://127.0.0.1:8080/請求會被轉發(fā)到http://127.0.0.1:8080/user/list/api前綴會被吞掉。這個細節(jié)容易踩坑務必確認后端 Controller 的映射上有/api前綴否則會報 404。HTTPS 配置線上環(huán)境一般用 Certbot 自動申請證書并配置到 Nginx這里先不展開但強調一句生產環(huán)境不要裸奔 HTTP涉及登錄和 token 的接口不上 HTTPS 相當于把門鎖掛在門外面。7.4 數(shù)據(jù)庫初始化與遷移策略生產環(huán)境數(shù)據(jù)庫初始化不能靠手動一條條執(zhí)行 SQL。我用 Flyway 做數(shù)據(jù)庫版本管理每次 SQL 變更寫一個帶版本號的文件放到resources/db/migration目錄應用啟動時會自動執(zhí)行未執(zhí)行過的腳本。打比方說明一下Flyway 就像數(shù)據(jù)庫的 Git每次變更都是一個 commit版本號遞增它會在數(shù)據(jù)庫中建一張flyway_schema_history表來記錄已經執(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 有兩點要非常謹慎已經提交給團隊的遷移腳本不要修改哪怕里面 SQL 寫錯了也要靠新的遷移腳本來修正否則團隊的數(shù)據(jù)庫版本就對不上了。另外生產庫不要輕易執(zhí)行flyway clean它會重建整個數(shù)據(jù)庫操作前就算寫滿警告也不為過。8. 常用工具與效率提升清單8.1 接口調試工具的選擇聯(lián)調階段接口測試工具的作用很大。Postman 是最經典的選擇優(yōu)勢是功能齊全、支持 Collection 管理、環(huán)境變量設置。Apifox 是國內團隊常用的方案優(yōu)勢是集成了接口文檔管理、Mock 數(shù)據(jù)、自動化測試。如果項目中后端還沒有完全開發(fā)完Apifox 可以直接在接口文檔上生成 Mock 數(shù)據(jù)給前端先行開發(fā)這種前后端并行開發(fā)的模式能省不少時間。實際使用建議如果你是一個人做全棧直接用 IDEA 的 HTTP Client 就行不需要額外裝軟件。IDEA 里新建.http文件寫請求可以配合{{var}}使用環(huán)境變量還可以在后端代碼左側直接 Run 生成對應的測試請求效率很高。8.2 數(shù)據(jù)庫連接與查詢工具數(shù)據(jù)庫客戶端方面Navicat 和 DataGrip 都常用。Navicat 功能全面、界面友好DataGrip 更適合寫復雜 SQL它提供的智能提示和格式化功能非常好用。個人項目簡單查詢用 VS Code 的 MySQL 插件也可以湊合。我的建議是對于持久層查詢用 MyBatis Plus 的LambdaQueryWrapper寫條件查詢已經非常直觀大多數(shù)場景不需要打開數(shù)據(jù)庫客戶端。只有在排查數(shù)據(jù)問題時才需要連數(shù)據(jù)庫。遇到數(shù)據(jù)庫連接不上的情況先檢查服務是否啟動、端口是否被占用、認證插件版本是否匹配這三個點大多數(shù)問題都能解決。8.3 聯(lián)調排查常用的瀏覽器開發(fā)者工具前端調試離不開瀏覽器開發(fā)者工具。Network 面板能看到每個請求的狀態(tài)碼、耗時、請求頭和響應體Console 面板直接報錯信息Vue 專門有 Vue DevTools 插件可以查看組件樹、Pinia 狀態(tài)和路由信息。排查問題建議按照這個順序來看先在 Network 里確認請求發(fā)出去了沒有、狀態(tài)碼是多少再看請求頭里的 Content-Type 和 Authorization 對不對然后看響應體里的具體數(shù)據(jù)最后結合 Console 的報錯信息定位問題。有的開發(fā)者一上來就在代碼里打斷點其實大多數(shù)聯(lián)調問題在網絡請求這一層就能定位。8.4 代碼生成器的合理使用到了項目后期增刪改查的代碼寫多了會產生明顯的機械重復感。手動復制粘貼再改字段名容易出錯我保留了一條規(guī)則多表關聯(lián)、復雜業(yè)務邏輯的代碼必須手寫但單表 CRUD 的代碼交給生成器生成生成完再人工審查和微調。MyBatis Plus 官方提供了一個代碼生成器mybatis-plus-generator可以根據(jù)數(shù)據(jù)庫表自動生成 Entity、Mapper、Service、Controller 代碼。用它的時機設置在項目初始化階段把表結構設計好一鍵生成基礎代碼后面再在 Service 中補充業(yè)務邏輯。這能省去大量重復勞動但你一定要會改生成的代碼不然會陷入“低級錯誤看不出來”的局面。9. 項目擴展方向與進階建議9.1 從單體應用到模塊化演進當前項目的結構是單體應用這個結構適合大多數(shù)中小型項目。隨著業(yè)務量增長你可以按模塊拆分比如用戶模塊、訂單模塊、商品模塊每個模塊獨立成一個 Maven 模塊甚至獨立成一個 Spring Boot 服務。拆分的關鍵依據(jù)是團隊規(guī)模和部署復雜度不要因為趨勢而盲目拆分。如果項目超過 10 個接口、3 個以上開發(fā)人員合理的模塊化拆分能明顯減少合并沖突和協(xié)作成本。反過來如果就是一個人的項目拆成微服務純屬自找麻煩。9.2 引入 Redis 緩存與接口性能優(yōu)化項目中如果有熱點數(shù)據(jù)比如用戶信息、系統(tǒng)配置可以引入 Redis 做緩存層。實現(xiàn)方式是在原有的 Service 邏輯包一層先查緩存緩存未命中再查數(shù)據(jù)庫同時把結果寫入緩存并設置過期時間。用 Redis 的StringRedisTemplate就夠不需要引入復雜的緩存框架。這個實踐我建議放到項目穩(wěn)定之后再做第二個版本迭代。先保證功能正確再考慮性能。接口響應時間慢先看是不是數(shù)據(jù)庫查詢的問題有沒有索引、有沒有 N1 查詢再決定要不要加緩存。過早引入緩存會讓 bug 排查多一層維度代價不小。9.3 安全加固與權限模型的進階方向做全棧項目時很多人忽略了權限設計。目前項目只有“登錄/未登錄”兩層。如果你的系統(tǒng)需要不同角色管理員、普通用戶、訪客可以引入 RBAC 權限模型用戶-角色-權限三層結構。表設計上新建sys_role、sys_menu、sys_user_role、sys_role_menu四張表后端在攔截器或注解層面校驗是否有指定權限。前端對應地可以做動態(tài)路由用戶登錄后根據(jù)后端返回的權限列表動態(tài)生成可訪問的路由配置。這個是很多全棧項目的進階難點會接觸到更深的前后端正交互。建議把當前項目跑通后再往這個方向升級每一步都是新的技術內容。9.4 前端工程化的進一步打磨前端部分可以繼續(xù)打磨的點很多代碼規(guī)范ESLint Prettier、提交規(guī)范Commitlint husky、單元測試Vitest、自動化部署GitHub Actions。這些屬于前端工程化范疇。舉一個很實用的例子在項目里加 ESLint 和 Prettier 配置團隊協(xié)作時代碼風格統(tǒng)一少了無謂的爭吵。不建議一開始就上全量工程化配置先把項目跑通再逐步加上這些工具學習曲線更平滑。10. 完整的實操流程對照表下表整理了這個項目從零到上線的完整操作清單按順序執(zhí)行每完成一步打一個勾階段關鍵操作產出物耗時預估環(huán)境準備JDK 17、Maven、Node.js 20、MySQL 8開發(fā)環(huán)境跑通0.5 天數(shù)據(jù)庫設計創(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可運行前端基礎工程1 天前端頁面開發(fā)登錄頁、布局頁、用戶管理頁可交互的完整頁面2-3 天前后端聯(lián)調測試登錄流程、CRUD 流程、異常流程完整的業(yè)務閉環(huán)1 天打包部署前端 build、后端 jar、Nginx 配置生產環(huán)境可訪問系統(tǒng)1 天上線檢查安全、日志、備份、監(jiān)控穩(wěn)定運行的系統(tǒng)0.5 天這是一個典型的個人全棧項目的工期預估。如果你是第一次做時間會翻倍正?，F(xiàn)象。如果遇到卡殼超過半天的問題建議跳過去先把主流程跑通再回頭看卡住的部分。我個人的經驗是全棧開發(fā)能力的提升不是線性的而是靠一個個完整的項目串起來的。這個項目雖然從技術角度看每個環(huán)節(jié)都是“常用技術”但當它們組合在一起形成完整閉環(huán)時你對前端和后端協(xié)作模式的理解會上一個臺階。當你遇到任何業(yè)務需求時腦子里能浮現(xiàn)出完整的請求鏈路和數(shù)據(jù)流轉圖而不是只盯著自己熟悉的那一層這就算真正入門了。