前幾天把一套物資綜合管理系統(tǒng)重新整理了一遍從后端接口到前端頁面再到數(shù)據(jù)庫腳本全部跑通之后打包成了一份可以直接運(yùn)行的源碼。這套東西不是那種只有幾個(gè)空殼頁面的演示項(xiàng)目而是把企業(yè)里物資管理的真實(shí)流程都做了進(jìn)去物資分類、入庫登記、庫存查詢、領(lǐng)用審批、出庫記錄、統(tǒng)計(jì)報(bào)表該有的模塊基本都齊了。技術(shù)棧是SpringBoot做后端接口Vue做前端頁面MySQL存數(shù)據(jù)典型的前后端分離結(jié)構(gòu)。今天把整個(gè)項(xiàng)目的設(shè)計(jì)思路、核心實(shí)現(xiàn)、運(yùn)行步驟和踩坑記錄完整梳理出來希望能幫到正在做類似系統(tǒng)或者打算拿這種項(xiàng)目練手的朋友。這套源碼特別適合三類人一是正在準(zhǔn)備畢業(yè)設(shè)計(jì)的學(xué)生拿來改改就能用二是剛學(xué)完SpringBoot和Vue、想看一個(gè)完整真實(shí)項(xiàng)目長什么樣的初學(xué)者三是公司內(nèi)部確實(shí)需要一套輕量級(jí)物資管理工具、但不想買商業(yè)軟件的運(yùn)維或開發(fā)人員。比起那些只貼出幾個(gè)核心代碼片段、根本跑不起來的教程源碼這一套最大的特點(diǎn)就是開箱即用。下面我會(huì)從架構(gòu)拆解、后端設(shè)計(jì)、前端實(shí)現(xiàn)、數(shù)據(jù)庫腳本、運(yùn)行步驟和問題排查這幾個(gè)維度一層層講透。1. 項(xiàng)目整體設(shè)計(jì)與架構(gòu)拆解1.1 這套系統(tǒng)到底解決了什么問題先說說物資管理這個(gè)場景。很多中小型公司或者學(xué)校、事業(yè)單位物資管理還停留在Excel表格加微信群的階段。入庫登記靠手寫領(lǐng)用物資靠口頭招呼月底盤點(diǎn)發(fā)現(xiàn)庫存對不上新來的同事不知道倉庫里到底有什么。這些零散的痛點(diǎn)聚在一起就是物資管理系統(tǒng)存在的理由。一個(gè)完整的物資管理系統(tǒng)核心閉環(huán)就三條線物資進(jìn)來、庫存放量、物資出去。再往里拆就是物資的入庫單管理、庫存臺(tái)賬管理、領(lǐng)用申請與審批、出庫登記以及圍繞這些數(shù)據(jù)產(chǎn)生的統(tǒng)計(jì)報(bào)表。這套源碼正是按照這條主線來組織的沒有堆砌多余的社交功能、審批流引擎之類的重東西業(yè)務(wù)邊界很克制這對中小規(guī)模場景反而是優(yōu)勢。1.2 為什么選SpringBoot加Vue加MySQL這個(gè)組合先說后端。SpringBoot在這個(gè)領(lǐng)域已經(jīng)成為事實(shí)標(biāo)準(zhǔn)它解決的核心痛點(diǎn)是Spring傳統(tǒng)項(xiàng)目中那些繁瑣的XML配置、依賴管理沖突和部署流程。使用SpringBoot之后一個(gè)內(nèi)嵌的Tomcat、一套起步依賴、一個(gè)Application主類就能把后端服務(wù)跑起來這對維護(hù)和二次開發(fā)來說非常友好。前端選Vue的原因也很實(shí)在。Vue的數(shù)據(jù)雙向綁定和組件化開發(fā)特別適合管理后臺(tái)這類表單密集、列表密集、交互狀態(tài)多的頁面。填一個(gè)入庫表單時(shí)校驗(yàn)規(guī)則要即時(shí)反饋查庫存時(shí)表格列要?jiǎng)討B(tài)隱藏這些用jQuery那套手動(dòng)操作DOM的方式來做代碼量會(huì)膨脹幾倍。Vue的響應(yīng)式數(shù)據(jù)模型天然匹配這類需求。再加上Element UI這類成熟組件庫表格、彈窗、表單校驗(yàn)、分頁組件直接拿來用開發(fā)效率高很多。MySQL就更不用說了開源、穩(wěn)定、普及率高不管是本機(jī)部署還是上云都有大量現(xiàn)成經(jīng)驗(yàn)可參考。這套系統(tǒng)沒有用到Redis做緩存也沒有引入消息隊(duì)列全部依賴MySQL的關(guān)系型事務(wù)能力小團(tuán)隊(duì)的運(yùn)維成本可以壓到非常低。可能有人會(huì)問為什么不用更流行的前后端分離之外的單體架構(gòu)或者微服務(wù)架構(gòu)。這么看物資管理系統(tǒng)的用戶量級(jí)通常就是幾十到幾百人并發(fā)不高事務(wù)復(fù)雜度中等單體應(yīng)用配合前后端分離已經(jīng)是性價(jià)比最高的方案了。引入微服務(wù)只會(huì)增加運(yùn)維負(fù)擔(dān)沒有任何實(shí)際收益。技術(shù)選型不是越新越好是匹配場景才叫好。1.3 源碼的工程結(jié)構(gòu)一覽拿到源碼之后整個(gè)項(xiàng)目分兩個(gè)大目錄后端back-end或者叫server前端front-end或者叫web。我這邊習(xí)慣把后端命名為server、前端命名為ui方便區(qū)分。后端的工程結(jié)構(gòu)按Maven標(biāo)準(zhǔn)劃分你可能會(huì)看到這樣的布局server ├── src/main/java/com/example/wms │ ├── controller # 接收HTTP請求返回Result結(jié)果 │ ├── service # 業(yè)務(wù)邏輯層接口加實(shí)現(xiàn)類 │ ├── mapper # MyBatis的Mapper接口對應(yīng)XML或注解SQL │ ├── entity # 數(shù)據(jù)庫實(shí)體類 │ ├── dto # 前端傳輸對象用于參數(shù)接收與結(jié)果封裝 │ ├── config # 配置類跨域、攔截器、WebMvc配置 │ ├── common # 統(tǒng)一返回體、異常處理、工具類 │ └── WmsApplication.java # SpringBoot啟動(dòng)類 └── src/main/resources ├── application.yml # 數(shù)據(jù)源、端口、MyBatis配置 └── mapper # MyBatis XML文件前端的結(jié)構(gòu)就是標(biāo)準(zhǔn)的Vue工程ui ├── src │ ├── api # 按模塊封裝的接口請求 │ ├── assets # 靜態(tài)資源 │ ├── components # 公共組件分頁、彈窗等 │ ├── router # 路由配置與守衛(wèi) │ ├── store # Vuex狀態(tài)管理token、用戶信息 │ ├── views # 頁面登錄、物資、入庫、領(lǐng)用、統(tǒng)計(jì)等 │ ├── App.vue │ └── main.js ├── package.json └── vue.config.js # 開發(fā)服務(wù)器與代理配置這套結(jié)構(gòu)的優(yōu)點(diǎn)是職責(zé)清晰前端頁面找不到數(shù)據(jù)就去api目錄找接口后端接口出問題就去service層看邏輯排查問題路徑非常直接。2. 后端核心模塊設(shè)計(jì)與實(shí)現(xiàn)解析2.1 統(tǒng)一返回體與全局異常處理為什么是必需品后端接口不可能只返回?cái)?shù)據(jù)本身還得告訴前端這次請求成功沒有、如果失敗了是哪一類問題、提示信息應(yīng)該怎么展示。如果每個(gè)接口都自己拼返回值前端每個(gè)請求都要單獨(dú)做異常判斷代碼就亂套了。這套源碼里定義了一個(gè)Result類結(jié)構(gòu)大概是這樣的public class ResultT { private Integer code; // 200成功500業(yè)務(wù)失敗401未登錄取 private String message; // 提示信息 private T data; // 業(yè)務(wù)數(shù)據(jù) }所有Controller統(tǒng)一返回Result對象成功就Result.success(data)業(yè)務(wù)校驗(yàn)不通過就Result.error(庫存不足)。前端拿到響應(yīng)之后先看code再取data邏輯非常統(tǒng)一。這里有個(gè)關(guān)鍵設(shè)計(jì)業(yè)務(wù)異常和系統(tǒng)異常要分開處理。我見過很多項(xiàng)目把系統(tǒng)異常直接拋到前端用戶看到一堆OOM的堆棧信息這個(gè)體驗(yàn)是非常糟糕的。配合一個(gè)全局異常處理器RestControllerAdvice把系統(tǒng)異常統(tǒng)一轉(zhuǎn)換成系統(tǒng)繁忙請稍后再試把業(yè)務(wù)異常直接帶入提示信息這才是正經(jīng)做法。這套源碼里已經(jīng)把這一層做完了不需要你再自己去補(bǔ)。2.2 登錄認(rèn)證怎么做的為什么選這種方案企業(yè)系統(tǒng)基本都需要登錄物資管理系統(tǒng)也不例外。管理員難道要管庫存和用戶權(quán)限普通員工只能申請領(lǐng)用物資這個(gè)身份區(qū)分在數(shù)據(jù)庫層面就要體現(xiàn)出來。登錄認(rèn)證這塊源碼采用的是Token加攔截器的方式而不是傳統(tǒng)Session方案。每次用戶登錄成功后后端生成一個(gè)Token可以是UUID也可以是用JWT加密生成把用戶ID和角色信息寫進(jìn)Token里然后返回給前端。前端存在localStorage中每次請求在Header里帶上后端攔截器解析Token、讀取用戶身份。為什么不直接用Session因?yàn)榍昂蠖朔蛛x之后前端和后端往往不在同一個(gè)域名和端口下Session的Cookie跨域策略處理起來很麻煩。Token的方式天然支持跨域而且無狀態(tài)后端重啟也不會(huì)把用戶的登錄狀態(tài)沖掉這對本地開發(fā)和上線部署都省心很多。密碼存儲(chǔ)是個(gè)老生常談但必須強(qiáng)調(diào)的點(diǎn)。源碼里不會(huì)對密碼明文存儲(chǔ)用的是BCrypt加密也就是SpringSecurity自帶的那套加密工具。每次校驗(yàn)時(shí)把前端傳過來的明文密碼和數(shù)據(jù)庫里存的加密密碼做匹配而不是直接拼接SQL比對字符串。如果你拿到別的源碼發(fā)現(xiàn)密碼字段是明文請一定不要直接上線使用。2.3 核心業(yè)務(wù)表與接口設(shè)計(jì)思路物資管理系統(tǒng)的核心表通常是這幾張物資分類表、物資信息表或者叫物資檔案表、入庫單主表加明細(xì)表、領(lǐng)用單主表加明細(xì)表以及系統(tǒng)用戶表。拿入庫單來舉例一張入庫單需要記錄單號(hào)、經(jīng)手人、入庫時(shí)間、供應(yīng)商如果是采購入庫、備注這是一條主表記錄。入庫單下面可能同時(shí)包含多種物資每種物資入庫數(shù)量不同所以還需要一張明細(xì)表來存這次入庫了幾種物資、每種是多少。這種主表加明細(xì)表的設(shè)計(jì)在進(jìn)銷存系統(tǒng)里極其常見也是物資管理系統(tǒng)的地基。接口設(shè)計(jì)上用的是RESTful風(fēng)格各業(yè)務(wù)模塊的路徑劃分很清楚模塊接口路徑說明登錄認(rèn)證POST /api/auth/login登錄并返回Token物資分類GET/POST/PUT/DELETE /api/category分類的增刪改查物資檔案GET/POST/PUT/DELETE /api/material物資信息的維護(hù)入庫管理POST /api/stock/in創(chuàng)建入庫單并更新庫存領(lǐng)用管理POST /api/stock/out創(chuàng)建領(lǐng)用單并扣減庫存庫存查詢GET /api/stock/list分頁查詢各物資的當(dāng)前庫存統(tǒng)計(jì)報(bào)表GET /api/report/summary匯總?cè)霂炝?、出庫量、庫存余額這種按業(yè)務(wù)模塊切分接口的好處是擴(kuò)展性好。比如后面要加一個(gè)報(bào)廢功能那就增加一個(gè)/api/stock/scrap接口和現(xiàn)有的入庫、領(lǐng)用并列不會(huì)影響已經(jīng)穩(wěn)定的邏輯。加一個(gè)小提醒入庫和領(lǐng)用接口在源碼中都用事務(wù)Transactional包裹因?yàn)榻▎魏透膸齑姹仨毻瑫r(shí)成功或同時(shí)失敗。這一步如果沒做事務(wù)極端情況下會(huì)出現(xiàn)單據(jù)創(chuàng)建成功但庫存沒加上去的情況對業(yè)務(wù)來說就是重大數(shù)據(jù)事故。2.4 Mapper層與SQL的一些細(xì)節(jié)心得持久層這塊源碼用的是MyBatis而且建議直接用MyBatis-Plus來跑省去大量寫單表CRUD的重復(fù)勞動(dòng)。為什么要這么選因?yàn)槲镔Y管理系統(tǒng)里有大量的單表分頁查詢、條件過濾、增刪改查這些邏輯幾乎一模一樣的代碼用MyBatis-Plus的BaseMapper可以直接繼承現(xiàn)成的通用方法代碼量能減掉三分之一還多。報(bào)表類SQL是繞不開的坎。比如統(tǒng)計(jì)每種物資的累計(jì)入庫量、累計(jì)出庫量和當(dāng)前庫存SQL思路是用分組聚合加條件匯總SELECT material_id, SUM(CASE WHEN type IN THEN quantity ELSE 0 END) AS total_in, SUM(CASE WHEN type OUT THEN quantity ELSE 0 END) AS total_out, SUM(CASE WHEN type IN THEN quantity ELSE -quantity END) AS current_stock FROM stock_record GROUP BY material_id這里有一個(gè)容易踩的坑庫存字段到底用int還是decimal。如果物資按個(gè)、箱、瓶這類整數(shù)單位計(jì)算數(shù)量字段用int就夠了不要用decimal因?yàn)閐ecimal會(huì)引入精度問題后臺(tái)對賬會(huì)非常痛苦。但如果是金額、單價(jià)這類字段必須用decimal不能圖省事用doubledouble的浮點(diǎn)誤差在累加、匯總后會(huì)被無限放大。這個(gè)設(shè)計(jì)決策在前面的表結(jié)構(gòu)里就要定好不然后期改字段類型代價(jià)很大。3. 前端Vue工程核心實(shí)現(xiàn)解析3.1 前端工程初始化與頁面布局前端工程初始化用的Vue CLI或者Vite都行源碼里基于Vue的組件化機(jī)制搭建了一整套管理后臺(tái)布局左側(cè)是菜單欄物資管理、入庫管理、領(lǐng)用管理、系統(tǒng)管理之類的入口頂部是用戶信息和退出按鈕中間的內(nèi)容區(qū)用來承載各個(gè)頁面。這種布局是所有管理系統(tǒng)的標(biāo)配用戶進(jìn)入系統(tǒng)不用額外學(xué)習(xí)成本。組件庫這塊建議使用Element UI對應(yīng)Vue2或者Element Plus對應(yīng)Vue3。像物資信息表格、入庫單的彈窗表單、領(lǐng)用明細(xì)的級(jí)聯(lián)選擇器這些組件都有現(xiàn)成的封裝直接按文檔配置就好。這套源碼里應(yīng)該已經(jīng)做了一部分組件的二次封裝比如分頁組件、搜索表單組件目的是為了減少頁面之間的重復(fù)代碼。拿到源碼后你可以看一下components目錄下的封裝情況理解別人封裝組件的思路比自己從零開始寫要省力得多。3.2 路由權(quán)限控制到底怎么回事權(quán)限控制是前端設(shè)計(jì)里比較微妙的部分。常見的誤區(qū)是我只要把側(cè)邊欄菜單隱藏起來用戶就看不到?jīng)]權(quán)限的頁面了。這其實(shí)只是個(gè)花架子真正地控制在前端要配合路由守衛(wèi)在后端要配合接口權(quán)限校驗(yàn)。前端路由守衛(wèi)的典型邏輯是router.beforeEach((to, from, next) { const token localStorage.getItem(token); if (!token to.path ! /login) { next(/login); // 沒登錄只能去登錄頁 } else { next(); // 已登錄放行 } });這套源碼里在路由層面做了基本的Token守衛(wèi)同時(shí)在菜單渲染層面根據(jù)用戶角色動(dòng)態(tài)顯示或隱藏入口。注意前端的權(quán)限控制只是用戶體驗(yàn)的一部分真正的數(shù)據(jù)安全還得靠后端接口校驗(yàn)比如刪除物資檔案的接口必須判斷當(dāng)前用戶是否是管理員。把安全寄托在前端頁面隱藏上這是非常危險(xiǎn)的想法。3.3 Axios封裝與前后端聯(lián)調(diào)的細(xì)節(jié)前端的異步請求庫基本都是Axios但直接在每個(gè)頁面里調(diào)用this.$http.post容易導(dǎo)致代碼重復(fù)。更規(guī)范的做法是統(tǒng)一封裝一個(gè)Request實(shí)例把公共邏輯都做在攔截器里。源碼里的大致做法如下// api/request.js import axios from axios; const request axios.create({ baseURL: process.env.VUE_APP_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; }); // 響應(yīng)攔截器統(tǒng)一處理業(yè)務(wù)code碼 request.interceptors.response.use( response { const res response.data; if (res.code ! 200) { // 彈錯(cuò)誤提示并拋出異常中斷后續(xù)操作 return Promise.reject(new Error(res.message)); } return res.data; }, error { // 處理HTTP層錯(cuò)誤比如401跳登錄、500提示系統(tǒng)錯(cuò)誤 return Promise.reject(error); } ); export default request;這套封裝方案幾乎適用于所有管理后臺(tái)項(xiàng)目。把錯(cuò)誤提示統(tǒng)一放在攔截器里處理頁面里直接await調(diào)用接口拿數(shù)據(jù)就行大幅減少頁面級(jí)的重復(fù)try-catch?？缬騿栴}在本地開發(fā)時(shí)幾乎必現(xiàn)。前端跑在8080端口后端跑在8080端口通過Axios直接訪問時(shí)瀏覽器的同源策略會(huì)攔下跨域請求。最省事的本地跨域方案不用后端加CORS注解而是在vue.config.js里配置代理轉(zhuǎn)發(fā)所有/api開頭請求都被Vue的devServer轉(zhuǎn)發(fā)到localhost:8088瀏覽器視角下就沒有跨域概念了。部署到生產(chǎn)環(huán)境時(shí)則用Nginx把前端的靜態(tài)資源和后端的/api路徑配置到同一個(gè)域名下從根源上消除跨域。3.4 核心頁面的交互邏輯拆解前端頁面的核心交互可以分成三類表單操作、列表查詢、信息反饋。拿入庫管理頁面來說用戶點(diǎn)擊新增入庫彈出表單選擇物資、填數(shù)量、填供應(yīng)商、填備注提交后調(diào)用后端入庫接口成功后刷新庫存列表。這里最值得關(guān)注的是物資選擇器的設(shè)計(jì)。如果是一次入庫多種物資那頁面就需要一個(gè)動(dòng)態(tài)表格點(diǎn)一次添加一行就增加一條物資明細(xì)行每一行都能選擇物資和填數(shù)量。這個(gè)交互模式在Vue里用數(shù)組循環(huán)渲染就好。el-table :dataorderItems el-table-column label物資 template #default{ row } el-select v-modelrow.materialId filterable placeholder請選擇物資 el-option v-form in materialList :keym.id :labelm.name :valuem.id / /el-select /template /el-table-column el-table-column label數(shù)量 template #default{ row } el-input-number v-modelrow.quantity :min1 / /template /el-table-column /el-table這種動(dòng)態(tài)明細(xì)行的交互看似簡單但涉及一個(gè)要點(diǎn)新增行時(shí)需要給每行一個(gè)唯一標(biāo)識(shí)可以用時(shí)間戳拼隨機(jī)數(shù)方便Vue對行的增刪進(jìn)行追蹤避免刪錯(cuò)行。這類細(xì)節(jié)就是經(jīng)驗(yàn)積累出來的文檔上很少會(huì)寫。4. MySQL數(shù)據(jù)庫設(shè)計(jì)與初始化腳本要點(diǎn)4.1 核心表結(jié)構(gòu)設(shè)計(jì)與字段類型心得數(shù)據(jù)庫是這套系統(tǒng)最持久的部分。前端頁面可以換后端接口可以重構(gòu)但表結(jié)構(gòu)一旦跑偏改起來的成本極高。所以建表的時(shí)候一定要想清楚。用戶表的核心字段就是id、用戶名、密碼BCrypt加密后的字符串、真實(shí)姓名、角色admin/user、創(chuàng)建時(shí)間。物資檔案表的字段相對多一些物資編碼、物資名稱、分類ID、規(guī)格型號(hào)、單位、單價(jià)、備注、創(chuàng)建時(shí)間。庫存表可以是單獨(dú)的一張表也可以直接依賴庫存匯總視圖但更清晰的做法是維護(hù)一張庫存表每次出入庫后更新對應(yīng)物資的庫存值。這里分享一個(gè)字段命名和類型的經(jīng)驗(yàn)。主鍵統(tǒng)一用bigint自增或者雪花ID邏輯刪除字段用deleted0未刪1已刪不要物理刪除記錄創(chuàng)建時(shí)間和更新時(shí)間用datetime不要用timestamp因?yàn)閠imestamp的取值范圍到2038年就過期了雖然日常開發(fā)用不到那么遠(yuǎn)但一旦數(shù)據(jù)量大起來會(huì)非常麻煩。數(shù)量字段用int金額字段用decimal(10,2)文本字段用varchar并設(shè)置合理長度不要圖省事全部用texttext字段的索引和查詢性能都很差。4.2 初始化SQL腳本為什么是直接運(yùn)行的關(guān)鍵這套源碼能直接運(yùn)行很大程度上要?dú)w功于初始化腳本設(shè)計(jì)得當(dāng)。你的源碼包里應(yīng)該有一個(gè)database目錄里面放著init.sql內(nèi)容包含建庫語句、建表語句、默認(rèn)管理員賬號(hào)的插入語句以及一小批演示數(shù)據(jù)。為了避免首次運(yùn)行報(bào)數(shù)據(jù)庫不存在腳本開頭一般會(huì)有CREATE DATABASE IF NOT EXISTS wms DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci; USE wms;然后是一個(gè)一個(gè)的CREATE TABLE IF NOT EXISTS。這里要特別提醒的是字符集和排序規(guī)則必須統(tǒng)一。utf8mb4相比utf8多出來的部分是能夠正確存儲(chǔ)emoji和生僻字的而且它的索引兼容性更好。很多人在本地跑通后放到服務(wù)器上出現(xiàn)亂碼絕大多數(shù)原因是建庫時(shí)用了utf8不是utf8mb4連接字符串也沒指定字符集前端頁面本身是UTF-8編碼三方一交叉中文就變成問號(hào)了。這套腳本里已經(jīng)把字符集預(yù)設(shè)好你執(zhí)行的時(shí)候不要手賤去改成默認(rèn)值。4.3 SpringBoot數(shù)據(jù)源配置的幾個(gè)關(guān)鍵點(diǎn)后端application.yml里的數(shù)據(jù)源配置是整個(gè)項(xiàng)目能跑起來的生命線。核心配置包括server: port: 8088 spring: datasource: driver-class-name: com.mysql.cj.jdbc.Driver url: jdbc:mysql://localhost:3306/wms?useUnicodetruecharacterEncodingutf8serverTimezoneAsia/Shanghai username: root password: 你的數(shù)據(jù)庫密碼 mybatis-plus: mapper-locations: classpath*:mapper/**/*.xml type-aliases-package: com.example.wms.entity這里最少有三個(gè)坑。第一url中必須帶serverTimezone參數(shù)否則高版本MySQL驅(qū)動(dòng)會(huì)報(bào)時(shí)區(qū)相關(guān)的異常各種奇奇怪怪的時(shí)間錯(cuò)亂問題也會(huì)隨之而來。第二MySQL的驅(qū)動(dòng)類名在新老版本中不一樣舊版是com.mysql.jdbc.Driver新版是com.mysql.cj.jdbc.Driver用老配置去連新版驅(qū)動(dòng)會(huì)直接報(bào)ClassNotFound。第三application.yml里寫的數(shù)據(jù)庫密碼是模板占位符還是實(shí)際密碼要分清楚。源碼如果提交到公開倉庫一般會(huì)把真實(shí)密碼改成你本地要設(shè)置的密碼或者用${WMS_DB_PASSWORD}環(huán)境變量占位的方式。你本地運(yùn)行時(shí)需要把這個(gè)值改成你自己的MySQL密碼否則啟動(dòng)會(huì)一直報(bào)連接拒絕這是新手最容易卡住的地方。5. 本地直接運(yùn)行的完整操作步驟5.1 環(huán)境準(zhǔn)備到底需要哪些工具和版本根據(jù)我的實(shí)踐經(jīng)驗(yàn)一套穩(wěn)妥的組合是這樣的軟件推薦版本說明JDK1.8或11大多數(shù)SpringBoot項(xiàng)目基于Java 8版本太新也可能編譯報(bào)錯(cuò)Maven3.6及以上用IDEA內(nèi)置Maven也行Node.js14或16或18要看你這邊Vue是哪個(gè)版本Vue2一般建議16Vue3建議18MySQL5.7或8.05.7很穩(wěn)8.0要注意默認(rèn)加密規(guī)則差異IDEA2021以上社區(qū)版就夠用這里有個(gè)最常見的版本坑JDK版本太高而項(xiàng)目是老語法寫的編譯會(huì)遇到一堆問題。如果你的源碼寫的是Java 8的語法用JDK 17打開可能直接報(bào)編譯錯(cuò)誤。優(yōu)先按照源碼README里注明的版本組合來準(zhǔn)備環(huán)境。沒有任何環(huán)境適配能力的直接運(yùn)行是不存在的所以看到源碼包里帶README先讀它比看代碼事半功倍。5.2 數(shù)據(jù)庫初始化實(shí)操從新建庫到執(zhí)行腳本第一步連上你的本地MySQL?？梢杂妹钚幸部梢杂肗avicat如果已有就順手不建議為了跑項(xiàng)目特意去破解工具命令行那幾條命令足夠用。命令行方式創(chuàng)建一個(gè)數(shù)據(jù)庫并執(zhí)行腳本mysql -u root -p # 輸入密碼后 source /你的路徑/init.sql;執(zhí)行成功后查看數(shù)據(jù)庫是否建出來了SHOW DATABASES; USE wms; SHOW TABLES;正常情況下你會(huì)看到用戶表、物資表、入庫表、領(lǐng)用表等至少五六張表并且可以驗(yàn)證默認(rèn)管理員賬號(hào)是否存在SELECT * FROM sys_user;這里建議不要修改init.sql里的初始化數(shù)據(jù)。默認(rèn)管理員賬號(hào)一般就是admin密碼可能是admin123或者123456你先拿這個(gè)賬號(hào)登錄成功之后再進(jìn)系統(tǒng)到用戶管理里改密碼。直接改腳本容易造成后面的數(shù)據(jù)關(guān)聯(lián)問題。5.3 后端項(xiàng)目啟動(dòng)步驟與日志識(shí)別打開IDEAFile - Open選擇server目錄等待Maven把依賴都下載完。下載過程中如果網(wǎng)絡(luò)比較慢記得在Maven的settings.xml里配置國內(nèi)鏡像源比如阿里云鏡像這個(gè)細(xì)節(jié)能幫你省下大量等待時(shí)間。直接找到啟動(dòng)類就是在com.example.wms包下的xxxApplication類類上標(biāo)注SpringBootApplication。右鍵運(yùn)行這個(gè)主類控制臺(tái)開始刷日志。等到出現(xiàn)類似下面的日志時(shí)就說明后端啟動(dòng)成功了Tomcat started on port(s): 8088 (http) with context path Started WmsApplication in 5.231 seconds看到Started關(guān)鍵字的日志后可以先測試一下接口是否通了。瀏覽器訪問一個(gè)健康的接口地址比如http://localhost:8088/api/auth/login能返回JSON數(shù)據(jù)或者401之類的響應(yīng)就說明后端沒問題。如果啟動(dòng)過程報(bào)錯(cuò)先定位到最頂層的異常原因不要被下面幾百行堆棧嚇到九成以上是你在4.3小結(jié)里列出的那幾個(gè)原因。5.4 前端項(xiàng)目啟動(dòng)步驟與瀏覽器訪問打開前端項(xiàng)目同樣用IDEA或者直接在終端里進(jìn)入ui目錄。首次運(yùn)行需要安裝依賴npm install如果npm install的速度無法忍受可以采用國內(nèi)源npm config set registry https://registry.npmmirror.com然后啟動(dòng)開發(fā)服務(wù)器npm run serve看到這樣的日志就說明前端跑通了App running at: - Local: http://localhost:8080/ 編譯成功瀏覽器打開http://localhost:8080正常會(huì)跳轉(zhuǎn)到登錄頁面輸入默認(rèn)管理員賬號(hào)密碼登錄成功后就能看到一個(gè)帶側(cè)邊欄的物資管理后臺(tái)。到這里整套系統(tǒng)就算完全跑起來了?？梢栽谙到y(tǒng)里試著創(chuàng)建一條物資分類、錄入一份入庫單、然后發(fā)起一個(gè)領(lǐng)用申請把整個(gè)流程走一遍你會(huì)對這個(gè)系統(tǒng)以及它背后的技術(shù)架構(gòu)有一個(gè)完整的感知。5.5 前后端聯(lián)調(diào)配置核對清單如果頁面打開了但登錄一直轉(zhuǎn)圈或者提示請求失敗先不要懷疑代碼先檢查聯(lián)調(diào)配置。我整理了一份排查清單后端是否已經(jīng)啟動(dòng)端口是否是8088日志里有沒有Started標(biāo)記。前端請求的baseURL是否指向正確。開發(fā)環(huán)境一般是通過代理轉(zhuǎn)發(fā)所以看vue.config.js里devServer.proxy配置是否正確。數(shù)據(jù)庫里的用戶賬號(hào)密碼是否真的存在檢查sys_user表內(nèi)容。瀏覽器F12打開Network面板看登錄請求是否返回了Respones。如果是404檢查后端Controller的路徑和前端api文件里的路徑是否一致。做完這四項(xiàng)檢查90%以上的聯(lián)調(diào)問題都能解決。剩下的基本就是代碼本身需要調(diào)試的問題了。6. 常見問題與排查技巧實(shí)錄6.1 問題速查表上線運(yùn)行和本地開發(fā)中常見的問題我整理了一張表每個(gè)問題基本都遇到過對應(yīng)的解決方式也是經(jīng)過驗(yàn)證的現(xiàn)象根本原因排查與解決辦法后端啟動(dòng)報(bào)數(shù)據(jù)庫連接失敗MySQL沒開、密碼錯(cuò)誤、數(shù)據(jù)庫不存在確認(rèn)mysql服務(wù)已啟動(dòng)檢查application.yml密碼確認(rèn)init.sql已執(zhí)行npm install報(bào)錯(cuò)Node版本過高或過低、網(wǎng)絡(luò)不通查看報(bào)錯(cuò)提示切換到推薦Node版本換國內(nèi)npm鏡像源登錄后頁面一直在轉(zhuǎn)圈前端請求沒到后端確認(rèn)后端端口啟動(dòng)成功檢查代理配置用F12看請求是否404頁面能打開但驗(yàn)證碼不顯示驗(yàn)證碼接口被攔截器攔截后端加白名單把驗(yàn)證碼接口排除在登錄攔截之外后端啟動(dòng)報(bào)時(shí)區(qū)錯(cuò)誤MySQL連接串沒加serverTimezone按4.3節(jié)的url加上serverTimezoneAsia/Shanghai前端打包后部署到服務(wù)器刷新頁面404前端路由用history模式Nginx配置try_files $uri $uri/ /index.html6.2 幾個(gè)值得反復(fù)強(qiáng)調(diào)的避坑指南第一不要在源碼上直接改數(shù)據(jù)庫密碼并提交到公開倉庫。即使是在學(xué)習(xí)階段也應(yīng)該養(yǎng)成把敏感配置從代碼里剝離的習(xí)慣。數(shù)據(jù)庫密碼、密鑰這類東西要么放在環(huán)境變量里要么放在獨(dú)立的配置文件中并加入gitignore。第二錄入領(lǐng)用單時(shí)一定要先驗(yàn)證庫存夠不夠。后端在扣減庫存前必須做一次判斷當(dāng)前庫存是否大于等于本次領(lǐng)用數(shù)量。如果不夠直接返回業(yè)務(wù)異常庫存不足。這個(gè)判斷不能只依賴前端表單校驗(yàn)因?yàn)橛脩敉耆梢岳@過前端直接調(diào)接口。第三不要輕易刪除歷史出入庫記錄。如果你需要調(diào)整某筆錯(cuò)誤的入庫或領(lǐng)用比較穩(wěn)妥的做法是新增一條與之相反的沖抵記錄比如多入庫了10個(gè)就再登記一條出庫10而不是直接delete原始記錄。保留完整的流水是進(jìn)銷存系統(tǒng)的審計(jì)底線一旦刪除后期對賬基本無法挽回。第四做報(bào)表查詢的時(shí)候盡量不要在頁面加載時(shí)把所有數(shù)據(jù)全查出來。數(shù)據(jù)量小的時(shí)候感覺不出來等到幾十萬條記錄的時(shí)候?yàn)g覽器會(huì)直接卡死。無論是庫存列表還是出入庫明細(xì)都要分頁查詢后端用MyBatis-Plus自帶的分頁插件就行。表格分頁在前端是標(biāo)配但很多人初學(xué)時(shí)會(huì)漏掉這一步。6.3 接手陌生源碼時(shí)的快速上手方法論如果這套源碼不是你自己從零寫的拿到手的第一時(shí)間不要急著跑代碼。我自己的習(xí)慣是先看三樣?xùn)|西README文件、init.sql腳本和application.yml配置。README會(huì)告訴你作者聲明的環(huán)境要求和運(yùn)行步驟init.sql讓你知道數(shù)據(jù)庫里有哪些表和初始數(shù)據(jù)application.yml讓你了解端口、數(shù)據(jù)源和可能的外部依賴。這三樣?xùn)|西看完你心里對項(xiàng)目的全貌就有了七成把握。接下來再去看代碼優(yōu)先看Controller層把所有接口在腦子里過一遍知道這個(gè)系統(tǒng)提供了哪些能力。然后再看Service層把核心業(yè)務(wù)邏輯入庫、庫存扣減整理一遍。最后再看前端頁面長什么樣和接口一一對應(yīng)。這個(gè)順序是從外到內(nèi)的比直接一頭扎進(jìn)細(xì)節(jié)要高效得多。7. 這套源碼后續(xù)還能怎么擴(kuò)展這套系統(tǒng)當(dāng)前的功能已經(jīng)能解決日常物資管理需求但距離大型企業(yè)級(jí)系統(tǒng)還有一段路。如果后面有時(shí)間我會(huì)在這個(gè)基礎(chǔ)上逐步做一些擴(kuò)展。給幾個(gè)我看好且實(shí)踐過的方向供拿到源碼的朋友參考。第一個(gè)方向是引入對象存儲(chǔ)來做附件管理?，F(xiàn)在的物資系統(tǒng)里入庫單常常需要關(guān)聯(lián)采購合同、質(zhì)檢報(bào)告、物資照片這些附件。這些二進(jìn)制文件放在數(shù)據(jù)庫里不合適最有性價(jià)比的方式是接入MinIO或者云對象存儲(chǔ)。把附件的訪問路徑存到數(shù)據(jù)庫文件本身放到對象存儲(chǔ)這是企業(yè)系統(tǒng)的常規(guī)操作。庫表設(shè)計(jì)上也只需要增加附件表、在入庫單主表加一個(gè)附件關(guān)聯(lián)字段。第二個(gè)方向是增加消息通知能力。當(dāng)員工提交了領(lǐng)用申請管理員需要及時(shí)審批目前如果管理員不在系統(tǒng)里這個(gè)申請就晾在那里。接入消息通知之后申請?zhí)峤粫r(shí)自動(dòng)給管理員推送一個(gè)站內(nèi)信或者企業(yè)微信消息管理效率會(huì)提升很多。極簡的情況下可以用WebSocket做站內(nèi)通知不需要引入完整的工作流引擎。第三個(gè)方向是報(bào)表增強(qiáng)。當(dāng)前系統(tǒng)有基本的出入庫匯總但業(yè)務(wù)負(fù)責(zé)人往往需要看到更多維度的數(shù)據(jù)一個(gè)月內(nèi)各分類物資的領(lǐng)取趨勢、不同部門或員工領(lǐng)用物資的排行、庫存周轉(zhuǎn)率等。這些場景非常適合接ECharts圖表庫前端畫折線圖、柱狀圖、餅圖后端寫對應(yīng)的分組聚合SQL。視覺效果一旦做出來系統(tǒng)的完成度會(huì)有質(zhì)的提升。第四個(gè)方向是接口文檔自動(dòng)化。如果你準(zhǔn)備把這個(gè)項(xiàng)目作為多人協(xié)作的起點(diǎn)手動(dòng)維護(hù)接口文檔很容易過時(shí)。建議接入Knife4j或者SpringDoc讓后端啟動(dòng)后自動(dòng)生成接口文檔頁面前端照著文檔聯(lián)調(diào)減少溝通成本。最后說點(diǎn)實(shí)操中的個(gè)人體會(huì)這套系統(tǒng)我前后帶過不少同學(xué)跑通過最大的坑從來都不是代碼本身的邏輯而是環(huán)境不一致帶來的各種幺蛾子。比如有人MySQL用了8.0有人用了5.7兩個(gè)版本在驅(qū)動(dòng)連接時(shí)表現(xiàn)就是不一樣再比如有人Node裝的是20跑Vue2老項(xiàng)目直接報(bào)OpenSSL錯(cuò)誤換成Node16就好了。所以真的建議拿到源碼后第一步先看README把環(huán)境對齊了再動(dòng)手很多源碼有問題跑不起來的結(jié)論其實(shí)都是環(huán)境問題。另外很多初學(xué)者拿到這種源碼之后喜歡到處復(fù)制代碼把每個(gè)文件都打開一遍看不懂就慌。實(shí)際上你不用急著全部看懂先把系統(tǒng)跑起來從用戶視角在界面上點(diǎn)一遍對系統(tǒng)有了真實(shí)感受之后再帶著這個(gè)功能是怎么實(shí)現(xiàn)的這樣的問題去看代碼理解效率會(huì)高很多。這套物資綜合管理系統(tǒng)拿來練手還是做基礎(chǔ)二次開發(fā)都很合適。后面我會(huì)繼續(xù)整理一些針對性更強(qiáng)的拆解文章比如把某一條入庫流程從前端到后端到數(shù)據(jù)庫的完整數(shù)據(jù)流串講一遍或者講講報(bào)表模塊里的SQL優(yōu)化有興趣的朋友可以繼續(xù)關(guān)注。