設(shè)計(jì)與實(shí)現(xiàn)：從任務(wù)書到部署全流程解析)
做過文檔管理系統(tǒng)的人都知道這類項(xiàng)目表面上就是一個(gè)文件的CRUD但真正把需求理清楚、把權(quán)限和流程落地難度一點(diǎn)都不低。尤其是以任務(wù)書形式給出的SSM版本文檔管理系統(tǒng)既要滿足基礎(chǔ)的文件存取又要體現(xiàn)三層架構(gòu)的工程化能力還要在答辯或驗(yàn)收時(shí)講清楚每一個(gè)設(shè)計(jì)決策。這篇博文我就以自己從任務(wù)書到交付的完整過程為例把里面的設(shè)計(jì)思路、表結(jié)構(gòu)、核心代碼、部署細(xì)節(jié)和踩坑記錄都翻出來給正準(zhǔn)備動(dòng)手或者寫技術(shù)文檔的同學(xué)一點(diǎn)參考。項(xiàng)目標(biāo)題: 基于SSM的文檔管理系統(tǒng)的設(shè)計(jì)與實(shí)現(xiàn)任務(wù)書——這句話里真正重要的關(guān)鍵詞是任務(wù)書意味著你拿到的不是一句做個(gè)文檔系統(tǒng)的模糊需求而是一份有功能邊界、有技術(shù)指標(biāo)、有驗(yàn)收標(biāo)準(zhǔn)的約束文件。SSM是SpringSpringMVCMyBatis的組合在目前Spring Boot大行其道的環(huán)境下依然有很多課程設(shè)計(jì)和中小型企業(yè)內(nèi)部項(xiàng)目在用這套組合原因無非兩個(gè)一是Spring的核心IoC與AOP思想必須通過SSM這種手動(dòng)裝配的方式才能理解得更透二是大量存量系統(tǒng)仍然是SSM架構(gòu)維護(hù)和二次開發(fā)的需求長(zhǎng)期存在。我的經(jīng)驗(yàn)是拿到任務(wù)書先別急著寫代碼花兩天時(shí)間把數(shù)據(jù)庫(kù)表和接口設(shè)計(jì)定下來后面能省一半的返工時(shí)間。下面我從頭到尾拆解這個(gè)項(xiàng)目的完整落地過程。1. 項(xiàng)目定位與整體設(shè)計(jì)思路1.1 這類項(xiàng)目要解決的核心痛點(diǎn)是什么文檔管理系統(tǒng)的本質(zhì)不是把文件存起來而是解決三個(gè)現(xiàn)實(shí)問題文件散落、權(quán)限失控、操作無痕。先說說使用場(chǎng)景。一個(gè)小團(tuán)隊(duì)或者一個(gè)部門日常產(chǎn)生的合同、制度、技術(shù)資料、會(huì)議紀(jì)要往往散落在各人的電腦和共享文件夾里。共享文件夾最大的問題是沒有權(quán)限粒度要么大家都能刪要么配起來極其麻煩。誰(shuí)在什么時(shí)間修改過哪個(gè)文件完全沒有記錄。文檔管理系統(tǒng)要做的就是把散落的文件收攏到一個(gè)統(tǒng)一入口按組織架構(gòu)和角色控制誰(shuí)能看、誰(shuí)能傳、誰(shuí)能刪同時(shí)對(duì)關(guān)鍵操作留下日志。從任務(wù)書常見的要求來看功能模塊一般繞不開這幾個(gè)用戶登錄與角色權(quán)限、文檔分類管理、文檔上傳下載、文檔檢索、操作日志、回收站機(jī)制。有些任務(wù)書還會(huì)加上在線預(yù)覽、版本管理、收藏與分享但核心永遠(yuǎn)是權(quán)限和流程。我接手過的模擬項(xiàng)目X就是典型的中小規(guī)模需求用戶分管理員和普通用戶兩級(jí)管理員可以管理所有文檔和分類普通用戶只能管理自己上傳的文檔所有用戶共享一個(gè)公共文檔庫(kù)。就這么一條簡(jiǎn)單的規(guī)則直接決定了后面用戶表、角色表和文檔表的關(guān)聯(lián)方式。1.2 為什么選SSM而不是Spring Boot這個(gè)問題幾乎每輪答辯都會(huì)被問到也是任務(wù)書如此設(shè)計(jì)技術(shù)棧的核心用意。SSM是一個(gè)典型的三層架構(gòu)技術(shù)組合Spring負(fù)責(zé)對(duì)象管理和事務(wù)控制SpringMVC負(fù)責(zé)HTTP請(qǐng)求的路由與參數(shù)綁定MyBatis負(fù)責(zé)SQL與對(duì)象映射。這三層各司其職邊界非常清晰。而Spring Boot把大量配置自動(dòng)化了你只需要引入依賴就能跑起來但底層的DispatcherServlet、HandlerMapping、SqlSessionFactory這些核心機(jī)制反而被隱藏了。對(duì)于以學(xué)習(xí)和教學(xué)為目的的任務(wù)書項(xiàng)目選SSM的意義在于你必須自己配置數(shù)據(jù)源、自己聲明事務(wù)管理器、自己寫攔截器、自己管理SQL映射這個(gè)過程能把框架的核心原理串起來。換句話說SSM版本做一遍Spring Boot版本就是水到渠成的事情。另外從實(shí)際運(yùn)維角度看很多公司在2015到2020年間沉淀的內(nèi)部系統(tǒng)就是SSM架構(gòu)目前依然在線運(yùn)行。一個(gè)能基于SSM做二次開發(fā)的工程師在老系統(tǒng)維護(hù)這個(gè)維度上是有實(shí)際價(jià)值的。1.3 功能模塊的拆解與邊界劃分動(dòng)手設(shè)計(jì)之前我會(huì)把任務(wù)書里的每一條功能要求拆成四層表現(xiàn)層、接口層、服務(wù)層、數(shù)據(jù)層。這是SSM項(xiàng)目的天然分層也是寫技術(shù)文檔時(shí)最直觀的結(jié)構(gòu)。以文檔檢索為例表現(xiàn)層是一個(gè)帶搜索框的列表頁(yè)接口層接收keyword、categoryId、pageNum、pageSize這些參數(shù)服務(wù)層負(fù)責(zé)拼接查詢條件并調(diào)用MyBatis的Mapper接口數(shù)據(jù)層則是動(dòng)態(tài)SQL的查詢語(yǔ)句。每一層只干自己的事后面排查問題的時(shí)候一層一層看效率很高。功能邊界同樣重要。任務(wù)書如果寫了回收站就要定義清楚用戶刪除文檔是邏輯刪除還是物理刪除回收站里的文檔保留多久徹底刪除是否需要管理員權(quán)限這些邊界問題如果不提前想清楚代碼寫到最后很容易陷進(jìn)改不完的狀態(tài)流轉(zhuǎn)。我的建議是畫一張角色權(quán)限矩陣橫軸是功能操作縱軸是角色類型單元格里標(biāo)注允許或不允許。這張表后面既是寫代碼的依據(jù)也是測(cè)試用例的來源。2. 數(shù)據(jù)庫(kù)設(shè)計(jì)與核心表結(jié)構(gòu)2.1 表結(jié)構(gòu)設(shè)計(jì)的原則與典型拆分文檔管理系統(tǒng)的數(shù)據(jù)庫(kù)表不會(huì)特別多但表與表之間的關(guān)聯(lián)關(guān)系很考驗(yàn)設(shè)計(jì)功底。一個(gè)典型的SSM文檔管理系統(tǒng)核心表包括用戶表、角色表、用戶角色關(guān)聯(lián)表、文檔分類表、文檔信息表、操作日志表。用戶表的核心字段是id、用戶名、密碼、真實(shí)姓名、郵箱、手機(jī)號(hào)、狀態(tài)、創(chuàng)建時(shí)間。密碼一定不要存明文用MD5加鹽或者BCrypt散列這是底線問題。角色表相對(duì)簡(jiǎn)單就是id、角色名、角色編碼和描述。用戶和角色是多對(duì)多關(guān)系所以需要一張中間關(guān)聯(lián)表。文檔信息表是整個(gè)系統(tǒng)最關(guān)鍵的一張表字段設(shè)計(jì)我后面單獨(dú)展開。分類表是自關(guān)聯(lián)結(jié)構(gòu)用parentId字段實(shí)現(xiàn)樹形目錄比如技術(shù)資料/后端/框架這就是兩層的父子關(guān)系。操作日志表記錄關(guān)鍵行為字段包括操作人、操作類型、操作對(duì)象、操作詳情、IP地址、操作時(shí)間。這張表的價(jià)值在于審計(jì)追溯屬于平時(shí)沒人看、出事必須查的表設(shè)計(jì)時(shí)寧可多存字段不要事后補(bǔ)字段。2.2 文件存儲(chǔ)方式數(shù)據(jù)庫(kù)BLOB還是磁盤路徑這是文檔管理系統(tǒng)里最容易糾結(jié)的決定。我見過有人把文件轉(zhuǎn)成byte[]直接塞進(jìn)數(shù)據(jù)庫(kù)的BLOB字段也見過只存文件路徑的做法。我的結(jié)論很明確主流可靠方案是文件存磁盤數(shù)據(jù)庫(kù)存元數(shù)據(jù)和路徑。用一個(gè)維度來對(duì)比會(huì)非常直觀對(duì)比項(xiàng)數(shù)據(jù)庫(kù)BLOB磁盤路徑元數(shù)據(jù)數(shù)據(jù)庫(kù)備份體積非常大備份恢復(fù)都很慢數(shù)據(jù)庫(kù)體積小備份快文件讀取性能每次讀取走數(shù)據(jù)庫(kù)連接高頻下載時(shí)是災(zāi)難文件流直接從磁盤讀或交給靜態(tài)資源服務(wù)器處理文件預(yù)覽支持需要額外寫二進(jìn)制流輸出邏輯配合Nginx映射目錄即可支持?jǐn)U展性數(shù)據(jù)庫(kù)擴(kuò)容成本高文件可遷移到OSS或分布式存儲(chǔ)如果任務(wù)書明確要求使用BLOB那說明這個(gè)項(xiàng)目是教學(xué)演示級(jí)重點(diǎn)是展示MyBatis對(duì)大字段的處理能力這種情況可以按照任務(wù)書執(zhí)行但也要在文檔里說明方案的局限性。如果任務(wù)書沒有強(qiáng)制要求存儲(chǔ)方式選磁盤路徑方案更合理也更符合企業(yè)真實(shí)做法。文件存儲(chǔ)目錄的規(guī)劃同樣重要。在應(yīng)用所在磁盤建立一個(gè)專用目錄比如/data/docfiles下面按日期或者按分類分子目錄存儲(chǔ)時(shí)給文件生成一個(gè)新的隨機(jī)文件名擴(kuò)展名保留原文件擴(kuò)展名。這樣做的好處是避免重名覆蓋同時(shí)避免特殊字符和中文名在文件系統(tǒng)層面的兼容問題。2.3 權(quán)限設(shè)計(jì)從簡(jiǎn)到繁的兩檔實(shí)現(xiàn)權(quán)限模型是文檔管理系統(tǒng)和普通文件目錄最本質(zhì)的區(qū)別。任務(wù)書通常會(huì)給兩種權(quán)限要求對(duì)應(yīng)的實(shí)現(xiàn)復(fù)雜度差別很大。第一檔是粗粒度權(quán)限只有管理員和普通用戶兩種角色管理員能做所有操作普通用戶只能操作自己上傳的文檔。這種模型不需要菜單表只需要在service層判斷當(dāng)前登錄用戶的角色和資源歸屬即可。第二檔是細(xì)粒度RBAC任務(wù)書可能要求不同角色看到不同菜單、不同按鈕這時(shí)候就要引入菜單表和角色菜單關(guān)聯(lián)表。登錄成功后查詢當(dāng)前角色的菜單列表動(dòng)態(tài)渲染左側(cè)導(dǎo)航欄。后端每個(gè)接口通過攔截器和注解雙重校驗(yàn)權(quán)限比第一檔復(fù)雜不少。我的建議是如果任務(wù)書沒有明確要求權(quán)限細(xì)分先做第一檔把核心業(yè)務(wù)流程跑通有余力再升級(jí)到第二檔。權(quán)限這東西最容易陷入過度設(shè)計(jì)一套系統(tǒng)如果一共就三個(gè)角色硬生生做五張權(quán)限表純屬給自己挖坑。3. 核心技術(shù)實(shí)現(xiàn)與實(shí)操要點(diǎn)3.1 登錄認(rèn)證與攔截器的完整實(shí)現(xiàn)登錄認(rèn)證幾乎是每一個(gè)SSM項(xiàng)目的第一個(gè)硬骨頭。流程不復(fù)雜但細(xì)節(jié)很多。登錄接口接收用戶名和密碼調(diào)用service層根據(jù)用戶名查詢用戶比對(duì)密碼時(shí)用MD5加鹽的方式前端提交明文密碼后端用固定鹽值拼上密碼再做MD5與數(shù)據(jù)庫(kù)存儲(chǔ)的散列值比對(duì)。成功之后將用戶對(duì)象放入session同時(shí)放入角色編碼后續(xù)每個(gè)請(qǐng)求通過攔截器從session中判斷登錄狀態(tài)。SpringMVC的攔截器需要實(shí)現(xiàn)HandlerInterceptor接口核心在preHandle方法里public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception { HttpSession session request.getSession(); Object user session.getAttribute(loginUser); if (user null) { response.sendRedirect(request.getContextPath() /login); return false; } return true; }這里有幾個(gè)關(guān)鍵配置需要注意。攔截器要排除登錄接口、注冊(cè)接口和靜態(tài)資源路徑否則CSS、JS、圖片全部被攔頁(yè)面會(huì)變成裸HTML。在spring-mvc.xml配置攔截器路徑時(shí)我用的是/*還是/**這點(diǎn)非常容易搞錯(cuò)。/*只匹配一級(jí)路徑/doc/detail/1這種多級(jí)URL會(huì)直接繞過攔截必須用/**才能匹配所有層級(jí)。還有一個(gè)隱患是session超時(shí)。Tomcat默認(rèn)session過期時(shí)間是30分鐘用戶在上傳大文件或長(zhǎng)時(shí)間停留后提交請(qǐng)求時(shí)session已經(jīng)失效會(huì)被攔截器踢回登錄頁(yè)。這個(gè)情況要在任務(wù)書文檔的異常處理部分提及生產(chǎn)環(huán)境可以適當(dāng)調(diào)大session超時(shí)時(shí)間或者配合記住我的Cookie機(jī)制做自動(dòng)登錄。3.2 文件上傳與下載的實(shí)現(xiàn)細(xì)節(jié)文件上傳是文檔管理系統(tǒng)的核心操作也是坑最多的地方。SpringMVC處理文件上傳依賴commons-fileupload和commons-io兩個(gè)庫(kù)在spring-mvc.xml中配置MultipartResolver。核心配置如下bean idmultipartResolver classorg.springframework.web.multipart.commons.CommonsMultipartResolver property namemaxUploadSize value104857600/ property namemaxInMemorySize value1048576/ property namedefaultEncoding valueUTF-8/ /beanmaxUploadSize是總上傳大小上限這里設(shè)置100MB單位是字節(jié)。maxInMemorySize是內(nèi)存緩沖閾值超過1MB的文件會(huì)先寫入臨時(shí)文件再處理避免大文件撐爆內(nèi)存。這兩個(gè)參數(shù)如果不設(shè)置Tomcat默認(rèn)單次請(qǐng)求最大數(shù)據(jù)量可能是2MB或者2048KB用戶傳個(gè)稍大的PDF就會(huì)報(bào)錯(cuò)。接收文件的Controller層方法簽名是MultipartFile參數(shù)PostMapping(/upload) ResponseBody public Result upload(RequestParam(file) MultipartFile file, RequestParam(categoryId) Integer categoryId) { if (file.isEmpty()) { return Result.error(請(qǐng)選擇文件); } String originalFilename file.getOriginalFilename(); String ext originalFilename.substring(originalFilename.lastIndexOf(.)); String newFileName UUID.randomUUID().toString().replace(-, ) ext; // 保存到磁盤 File dest new File(fileDir File.separator newFileName); file.transferTo(dest); // 插入文檔表記錄 docService.addDoc(...); }保存文件前一定要做擴(kuò)展名校驗(yàn)。任務(wù)書里通常會(huì)寫支持常見辦公文檔格式那就定義一個(gè)白名單doc、docx、xls、xlsx、ppt、pptx、pdf、txt、zip。不要用黑名單攔截exe、bat這種可執(zhí)行文件因?yàn)楹诿麊斡肋h(yuǎn)漏白名單才是可靠方案。下載文件有兩種寫法。一種是返回ResponseEntitybyte[]代碼簡(jiǎn)潔但大文件會(huì)把整個(gè)文件讀進(jìn)內(nèi)存另一種是直接用HttpServletResponse獲取OutputStream流式寫入這種方法對(duì)大文件更友好。流式下載核心代碼如下File file new File(filePath); response.setContentType(application/octet-stream); String fileName URLEncoder.encode(doc.getFileName(), UTF-8); response.setHeader(Content-Disposition, attachment;filename fileName); FileInputStream fis new FileInputStream(file); OutputStream os response.getOutputStream(); byte[] buffer new byte[1024 * 8]; int len; while ((len fis.read(buffer)) ! -1) { os.write(buffer, 0, len); } os.flush(); fis.close();這里最大的坑是下載文件名中文亂碼。HTTP協(xié)議頭不支持非ASCII字符必須用URLEncoder轉(zhuǎn)碼瀏覽器收到后會(huì)自動(dòng)解碼。如果不做這步文件名是中文的文檔下載下來全是亂碼。下載完成后還要回寫一條操作日志記錄哪個(gè)用戶在什么時(shí)間下載了哪個(gè)文件同時(shí)把數(shù)據(jù)庫(kù)里的下載數(shù)字段加一。這一步很多人會(huì)漏而操作日志恰恰是任務(wù)書評(píng)分的加分項(xiàng)。3.3 MyBatis動(dòng)態(tài)SQL與分頁(yè)查詢的最佳實(shí)踐文檔管理系統(tǒng)的查詢條件通常不固定用戶可能只按文件名搜也可能同時(shí)按分類和文件名搜還可能按上傳時(shí)間范圍搜。這種場(chǎng)景正是MyBatis動(dòng)態(tài)SQL發(fā)揮威力的地方。Mapper XML里用where和if標(biāo)簽拼接條件select idsearchDocs resultTypecom.example.pojo.Document select * from doc_info where if testkeyword ! null and keyword ! and file_name like concat(%, #{keyword}, %) /if if testcategoryId ! null and category_id #{categoryId} /if if testuploaderId ! null and uploader_id #{uploaderId} /if if teststartTime ! null and create_time gt; #{startTime} /if /where order by create_time desc /selectwhere標(biāo)簽會(huì)自動(dòng)處理第一個(gè)條件前面的and不用手動(dòng)加where 11這種寫法看起來不優(yōu)雅但在MyBatis里確實(shí)很多人還在用只是不建議因?yàn)闀?huì)影響查詢優(yōu)化器對(duì)索引的使用。分頁(yè)查詢我推薦使用PageHelper插件引入依賴后在service層調(diào)用PageHelper.startPage(pageNum, pageSize)緊接著的查詢就是分頁(yè)查詢?cè)偻ㄟ^PageInfo對(duì)象獲取總記錄數(shù)。用法如下PageHelper.startPage(pageNum, pageSize); ListDocument list docMapper.searchDocs(condition); PageInfoDocument pageInfo new PageInfo(list);PageHelper的原理是攔截MyBatis的Executor在查詢前自動(dòng)拼接LIMIT語(yǔ)句。優(yōu)點(diǎn)是代碼侵入性小缺點(diǎn)是有時(shí)候容易忘掉它只能在第一次查詢前調(diào)用如果Mapper里有兩個(gè)查詢它只對(duì)第一個(gè)生效。如果不想引入額外依賴也可以手寫LIMIT分頁(yè)自己算偏移量再單獨(dú)寫一條count查詢。這種方式更可控但代碼量大一些。課程設(shè)計(jì)階段用PageHelper完全足夠。還有一個(gè)MyBatis高頻坑插入文檔后要立刻拿到自增主鍵用于回填文檔ID和后續(xù)操作。配置起來很簡(jiǎn)單insert idaddDoc parameterTypecom.example.pojo.Document useGeneratedKeystrue keyPropertyid如果沒有這行配置你插入后拿到的id永遠(yuǎn)是0后面要做根據(jù)ID綁定分類、生成日志關(guān)聯(lián)ID時(shí)全都會(huì)出問題。4. 關(guān)鍵配置與部署實(shí)操4.1 環(huán)境準(zhǔn)備與依賴管理一個(gè)標(biāo)準(zhǔn)的SSM項(xiàng)目環(huán)境我這邊用的是JDK 1.8、Maven 3.6、Tomcat 8.5、MySQL 5.7。JDK 1.8在SSM生態(tài)里兼容性最好MyBatis和Spring的老版本都能正常跑Tomcat 8.5對(duì)應(yīng)Servlet 3.1規(guī)范支持SpringMVC的注解驅(qū)動(dòng)方式。Maven依賴是SSM項(xiàng)目里最容易出錯(cuò)的部分。常見問題是版本沖突spring-webmvc用的是5.xspring-jdbc卻引成一個(gè)4.x啟動(dòng)時(shí)各種NoSuchMethodError。建議所有Spring相關(guān)依賴統(tǒng)一版本屬性在pom.xml中定義properties spring.version5.3.28/spring.version /properties核心依賴清單如下用途依賴名說明Spring核心spring-context, spring-webmvc版本統(tǒng)一數(shù)據(jù)訪問mybatis, mybatis-springMyBatis和Spring整合連接池druid阿里連接池監(jiān)控方便文件上傳commons-fileupload, commons-ioMultipart支持JSON處理jackson-databind前后端交互分頁(yè)插件pagehelper分頁(yè)查詢JSTLjstl, taglibs-standard-implJSP頁(yè)面使用JDK 1.8對(duì)應(yīng)Tomcat版本不能太新Tomcat 10把javax改名成了jakartaSpring老版本的包全都找不到類這是新手常踩的坑。我推薦直接用Tomcat 8.5減少不必要的適配。4.2 SSM整合配置的三個(gè)關(guān)鍵文件SSM項(xiàng)目需要三份配置文件web.xml、spring-mvc.xml、spring-mybatis.xml。這三份文件的職責(zé)劃分清晰配置時(shí)各管各的。web.xml配置編碼過濾器、Spring容器監(jiān)聽器和DispatcherServletfilter filter-nameencodingFilter/filter-name filter-classorg.springframework.web.filter.CharacterEncodingFilter/filter-class init-param param-nameencoding/param-name param-valueUTF-8/param-value /init-param init-param param-nameforceEncoding/param-name param-valuetrue/param-value /init-param /filterCharacterEncodingFilter放在所有過濾器最前面而且forceEncoding要設(shè)為true否則只影響請(qǐng)求編碼不影響響應(yīng)編碼頁(yè)面會(huì)亂碼得很均勻。spring-mvc.xml配置掃描Controller包、注解驅(qū)動(dòng)、視圖解析器、攔截器和MultipartResolver。spring-mybatis.xml配置掃描service、配置數(shù)據(jù)源、配置SqlSessionFactory、配置Mapper掃描、配置事務(wù)管理器。DataSource用Druid連接池的核心參數(shù)是initialSize5、maxActive20、minIdle5這些參數(shù)要根據(jù)實(shí)際并發(fā)量調(diào)整不要默認(rèn)值跑天下。事務(wù)管理是我特別想強(qiáng)調(diào)的一點(diǎn)。文檔系統(tǒng)中刪除分類、批量搬移文件、更新文檔狀態(tài)這些操作涉及多張表如果沒有事務(wù)中間一步失敗會(huì)導(dǎo)致數(shù)據(jù)不一致。配置事務(wù)管理器后在Service實(shí)現(xiàn)類或方法上使用Transactional注解即可。4.3 部署到Tomcat的完整流程部署階段的任務(wù)是打包成war包丟進(jìn)Tomcat的webapps目錄。Maven打包前要先做幾個(gè)檢查數(shù)據(jù)庫(kù)連接URL的IP是不是生產(chǎn)庫(kù)的IP上傳文件目錄在服務(wù)器上是否存在磁盤權(quán)限是否可寫。war包部署后同樣有一個(gè)約束要提前規(guī)避上傳文件目錄不能放在Tomcat部署目錄內(nèi)部。如果文件存到webapps/upload下一次重新部署war包時(shí)整個(gè)目錄會(huì)被覆蓋用戶上傳的文件全部丟失。正確做法是把上傳目錄配置到Tomcat之外比如/data/docfiles通過配置文件注入路徑這樣重新部署也不會(huì)丟文件。生產(chǎn)環(huán)境的數(shù)據(jù)庫(kù)初始化腳本建議在部署文檔中單獨(dú)提供。建庫(kù)語(yǔ)句、建表語(yǔ)句、初始管理員賬號(hào)的插入語(yǔ)句都要寫成SQL腳本。初始化時(shí)要注意字符集設(shè)置建庫(kù)語(yǔ)句帶上DEFAULT CHARSETutf8mb4否則存emoji或生僻字時(shí)數(shù)據(jù)庫(kù)直接報(bào)錯(cuò)。5. 常見問題與排查技巧實(shí)錄5.1 文件上傳失敗的幾種典型場(chǎng)景上傳功能是這個(gè)項(xiàng)目問題重災(zāi)區(qū)我把常見問題匯總成表格排查時(shí)對(duì)照著看效率很高。報(bào)錯(cuò)現(xiàn)象根本原因解決方案請(qǐng)求被拒絕超出大小限制maxUploadSize未配置或太小設(shè)置CommonsMultipartResolver的maxUploadSize空文件也能上傳成功未判空file.isEmpty()Controller層加判空和擴(kuò)展名校驗(yàn)上傳中文文件名保存后亂碼編碼過濾器未設(shè)置或順序不對(duì)web.xml放最前forceEncodingtrue傳到本地目錄出現(xiàn)重復(fù)文件直接用原文件名改用UUID隨機(jī)名存儲(chǔ)大文件上傳內(nèi)存溢出maxInMemorySize過大設(shè)為1MB左右觸發(fā)臨時(shí)文件機(jī)制還有一個(gè)很容易被忽略的問題如果項(xiàng)目配置了Spring Security或自定義的過濾器它可能會(huì)讀取并消費(fèi)請(qǐng)求體導(dǎo)致MultipartResolver拿不到文件數(shù)據(jù)。雖然SSM項(xiàng)目一般不引入Security但如果遇到上傳接口無響應(yīng)的情況優(yōu)先檢查過濾器鏈有沒有攔請(qǐng)求體。5.2 中文亂碼的一次排查實(shí)錄亂碼問題在SSM項(xiàng)目中幾乎不可避免我實(shí)際排查過的案例里亂碼往往不是單一原因而是多層疊加的結(jié)果。假設(shè)上傳一個(gè)名為產(chǎn)品需求說明書.docx的文件下載后文件名變成亂碼。第一層檢查URL編碼Content-Disposition頭里必須用URLEncoder.encode轉(zhuǎn)碼第二層檢查瀏覽器解碼方式不同瀏覽器對(duì)RFC 5987格式的支持有差異我最終用了一個(gè)簡(jiǎn)單粗暴且兼容的方案文件名轉(zhuǎn)碼成UTF-8后再按ISO-8859-1重新編碼再用URLEncoder處理雖然繞了一點(diǎn)但對(duì)主流瀏覽器都有效。如果列表頁(yè)顯示的文件名亂碼那是數(shù)據(jù)庫(kù)層面或者前端頁(yè)面編碼的問題。數(shù)據(jù)庫(kù)連接URL要加characterEncodingutf8頁(yè)面JSP的pageEncoding要設(shè)置為UTF-8Tomcat的URIEncoding也要設(shè)為UTF-8。這三個(gè)地方只要有一個(gè)漏了中文就會(huì)在某個(gè)環(huán)節(jié)變成問號(hào)。排查思路永遠(yuǎn)是從源頭到展示一步步試不要瞎改配置。先用數(shù)據(jù)庫(kù)客戶端直接查庫(kù)判斷數(shù)據(jù)本身是否正常再判斷是后端返回前就已經(jīng)亂碼還是瀏覽器顯示時(shí)亂碼。定位到具體環(huán)節(jié)修復(fù)就很快了。5.3 前端與后端聯(lián)調(diào)中的隱藏坑前后端分離不是SSM的主流用法但很多任務(wù)書要求頁(yè)面顯示結(jié)果和接口分開測(cè)試。用AJAX請(qǐng)求JSON數(shù)據(jù)時(shí)有幾個(gè)坑不可避免。Jackson默認(rèn)序列化Date類型的結(jié)果是一長(zhǎng)串時(shí)間戳數(shù)字前端顯示很丑陋。解決辦法是在實(shí)體類的日期字段上加注解JsonFormat(pattern yyyy-MM-dd HH:mm:ss, timezone GMT8) private Date createTime;另一個(gè)是static靜態(tài)資源被攔截的問題。如果spring-mvc.xml里沒有放行靜態(tài)資源瀏覽器打開頁(yè)面時(shí)CSS和JS全部加載失敗頁(yè)面光禿禿的。配置方式有兩種要么用mvc:default-servlet-handler/交給默認(rèn)Servlet處理要么用mvc:resources mapping/static/** location/static//指定資源路徑映射。我推薦使用mapping方式匹配規(guī)則更明確。JSON字符串中文亂碼也比較常見。SpringMVC的ResponseBody默認(rèn)StringHttpMessageConverter編碼是ISO-8859-1需要在spring-mvc.xml配置消息轉(zhuǎn)換器使用UTF-8否則通過AJAX返回的中文全是問號(hào)。5.4 性能與安全的基本加固文檔管理系統(tǒng)的并發(fā)量一般不高但也不能完全不考慮性能和建議層面的安全加固尤其是任務(wù)書如果涉及系統(tǒng)的非功能需求這一節(jié)。查詢性能的重中之重是索引。doc_info表的file_name字段如果經(jīng)常被模糊查詢可以建立前綴索引create_time字段用于排序建普通索引即可category_id是外鍵關(guān)聯(lián)字段頻繁做等值查詢必須建索引。安全方面有兩個(gè)底線操作必須做。一是密碼加密二是SQL注入防護(hù)。MyBatis的#{}預(yù)編譯天然防止SQL注入但那種手寫拼接${}的地方要特別小心一旦出現(xiàn)在用戶可控參數(shù)的場(chǎng)景就存在注入風(fēng)險(xiǎn)。上傳文件的存儲(chǔ)路徑也要做合法性校驗(yàn)嚴(yán)禁用戶通過路徑穿越等方式訪問系統(tǒng)目錄。我一般在保存文件時(shí)直接使用數(shù)據(jù)庫(kù)生成的ID和時(shí)間戳重構(gòu)文件名完全不用原始文件名這樣可以最大化降低這類風(fēng)險(xiǎn)。還有一個(gè)經(jīng)驗(yàn)是備份策略。文檔系統(tǒng)的數(shù)據(jù)價(jià)值主要在文件本身數(shù)據(jù)庫(kù)可以每天備份一次但文件目錄最好采用增量同步方案。我在模擬項(xiàng)目X中寫過一個(gè)簡(jiǎn)單的Shell腳本每天凌晨將當(dāng)日新增文件同步到備份盤這個(gè)操作成本極低關(guān)鍵時(shí)候能救命。6. 從任務(wù)書到交付的項(xiàng)目管理心得6.1 任務(wù)書的驗(yàn)收標(biāo)準(zhǔn)如何落實(shí)到開發(fā)計(jì)劃任務(wù)書在結(jié)尾部分通常會(huì)有成果要求比如系統(tǒng)運(yùn)行截圖、核心代碼說明、數(shù)據(jù)庫(kù)設(shè)計(jì)文檔、操作手冊(cè)、測(cè)試報(bào)告。這些文檔不是最后一天能趕出來的最好開發(fā)過程中同步積累。我習(xí)慣在項(xiàng)目目錄下維護(hù)三個(gè)文檔技術(shù)方案書、數(shù)據(jù)庫(kù)設(shè)計(jì)說明、測(cè)試記錄表。技術(shù)方案書寫框架選型理由和模塊劃分?jǐn)?shù)據(jù)庫(kù)設(shè)計(jì)說明標(biāo)注每張表每個(gè)字段的業(yè)務(wù)含義測(cè)試記錄表把每個(gè)功能點(diǎn)的操作步驟和結(jié)果截圖存檔。這份資料往任務(wù)書里一貼就是一份非常完整的項(xiàng)目材料。時(shí)間分配上前期設(shè)計(jì)占30%編碼占50%測(cè)試和文檔占20%。新手最常犯的錯(cuò)誤是一上來就寫代碼寫到一半發(fā)現(xiàn)表結(jié)構(gòu)不合理返工成本極高。6.2 答辯和評(píng)審環(huán)節(jié)的講解重點(diǎn)如果這個(gè)項(xiàng)目最終要答辯講解的邏輯主線應(yīng)該是需求分析到表設(shè)計(jì)表設(shè)計(jì)到代碼實(shí)現(xiàn)代碼實(shí)現(xiàn)到功能演示。不要一上來就念代碼要先講清楚為什么這樣設(shè)計(jì)。我建議準(zhǔn)備一個(gè)設(shè)計(jì)決策表把任務(wù)書中每個(gè)關(guān)鍵要求對(duì)應(yīng)到具體的實(shí)現(xiàn)方案和技術(shù)點(diǎn)。比如任務(wù)書寫了支持多條件組合檢索就對(duì)應(yīng)MyBatis動(dòng)態(tài)SQL寫不同角色對(duì)文檔操作權(quán)限不同就對(duì)應(yīng)攔截器和角色判斷邏輯。答辯時(shí)評(píng)委問什么就從這張表里找答案。演示環(huán)節(jié)一定要用自己的測(cè)試數(shù)據(jù)不要用空的數(shù)據(jù)庫(kù)或者只有兩三條記錄的庫(kù)演示。提前準(zhǔn)備好十來份不同格式的測(cè)試文檔把搜索、分類、權(quán)限切換、回收站恢復(fù)這些操作連貫演示一遍效果比說一百句話都強(qiáng)。6.3 拓展思路與后續(xù)升級(jí)方向SSM版本的文檔管理系統(tǒng)做完后往下的升級(jí)路徑很清晰如果團(tuán)隊(duì)規(guī)模變大可以替換成Spring Boot來降低維護(hù)成本配合Spring Security做更細(xì)粒度的權(quán)限控制如果文件量繼續(xù)增長(zhǎng)可以對(duì)接對(duì)象存儲(chǔ)服務(wù)把文件從本地磁盤搬遷到云端數(shù)據(jù)庫(kù)只存訪問地址如果要做在線預(yù)覽可以通過中間件把Office文件轉(zhuǎn)換成PDF后再展示這也是企業(yè)版文檔系統(tǒng)最常見的功能。技術(shù)選型從來不是追新而是合適。SSM這套組合雖然在配置上比Spring Boot繁瑣但它的每一行配置都在幫你理解Web開發(fā)底層發(fā)生了什么。這個(gè)理解在排查線上問題時(shí)非常值錢。我個(gè)人在多次做過類似系統(tǒng)后最大的體會(huì)是文檔管理系統(tǒng)的難點(diǎn)不在存取文件而在定義清楚誰(shuí)能做什么。任務(wù)書限定SSM反而是件好事它強(qiáng)迫你把權(quán)限、流程、狀態(tài)這些業(yè)務(wù)規(guī)則用最傳統(tǒng)但最扎實(shí)的三層結(jié)構(gòu)寫出來。把這份功課做扎實(shí)了以后不管換成什么框架、什么存儲(chǔ)、什么部署方式核心的業(yè)務(wù)建模能力都是通用的。 基于SSM的文檔管理系統(tǒng)設(shè)計(jì)與實(shí)現(xiàn)：從任務(wù)書到部署全流程解析
做過文檔管理系統(tǒng)的人都知道這類項(xiàng)目表面上就是一個(gè)文件的CRUD但真正把需求理清楚、把權(quán)限和流程落地難度一點(diǎn)都不低。尤其是以任務(wù)書形式給出的SSM版本文檔管理系統(tǒng)既要滿足基礎(chǔ)的文件存取又要體現(xiàn)三層架構(gòu)的工程化能力還要在答辯或驗(yàn)收時(shí)講清楚每一個(gè)設(shè)計(jì)決策。這篇博文我就以自己從任務(wù)書到交付的完整過程為例把里面的設(shè)計(jì)思路、表結(jié)構(gòu)、核心代碼、部署細(xì)節(jié)和踩坑記錄都翻出來給正準(zhǔn)備動(dòng)手或者寫技術(shù)文檔的同學(xué)一點(diǎn)參考。項(xiàng)目標(biāo)題: 基于SSM的文檔管理系統(tǒng)的設(shè)計(jì)與實(shí)現(xiàn)任務(wù)書——這句話里真正重要的關(guān)鍵詞是任務(wù)書意味著你拿到的不是一句做個(gè)文檔系統(tǒng)的模糊需求而是一份有功能邊界、有技術(shù)指標(biāo)、有驗(yàn)收標(biāo)準(zhǔn)的約束文件。SSM是SpringSpringMVCMyBatis的組合在目前Spring Boot大行其道的環(huán)境下依然有很多課程設(shè)計(jì)和中小型企業(yè)內(nèi)部項(xiàng)目在用這套組合原因無非兩個(gè)一是Spring的核心IoC與AOP思想必須通過SSM這種手動(dòng)裝配的方式才能理解得更透二是大量存量系統(tǒng)仍然是SSM架構(gòu)維護(hù)和二次開發(fā)的需求長(zhǎng)期存在。我的經(jīng)驗(yàn)是拿到任務(wù)書先別急著寫代碼花兩天時(shí)間把數(shù)據(jù)庫(kù)表和接口設(shè)計(jì)定下來后面能省一半的返工時(shí)間。下面我從頭到尾拆解這個(gè)項(xiàng)目的完整落地過程。1. 項(xiàng)目定位與整體設(shè)計(jì)思路1.1 這類項(xiàng)目要解決的核心痛點(diǎn)是什么文檔管理系統(tǒng)的本質(zhì)不是把文件存起來而是解決三個(gè)現(xiàn)實(shí)問題文件散落、權(quán)限失控、操作無痕。先說說使用場(chǎng)景。一個(gè)小團(tuán)隊(duì)或者一個(gè)部門日常產(chǎn)生的合同、制度、技術(shù)資料、會(huì)議紀(jì)要往往散落在各人的電腦和共享文件夾里。共享文件夾最大的問題是沒有權(quán)限粒度要么大家都能刪要么配起來極其麻煩。誰(shuí)在什么時(shí)間修改過哪個(gè)文件完全沒有記錄。文檔管理系統(tǒng)要做的就是把散落的文件收攏到一個(gè)統(tǒng)一入口按組織架構(gòu)和角色控制誰(shuí)能看、誰(shuí)能傳、誰(shuí)能刪同時(shí)對(duì)關(guān)鍵操作留下日志。從任務(wù)書常見的要求來看功能模塊一般繞不開這幾個(gè)用戶登錄與角色權(quán)限、文檔分類管理、文檔上傳下載、文檔檢索、操作日志、回收站機(jī)制。有些任務(wù)書還會(huì)加上在線預(yù)覽、版本管理、收藏與分享但核心永遠(yuǎn)是權(quán)限和流程。我接手過的模擬項(xiàng)目X就是典型的中小規(guī)模需求用戶分管理員和普通用戶兩級(jí)管理員可以管理所有文檔和分類普通用戶只能管理自己上傳的文檔所有用戶共享一個(gè)公共文檔庫(kù)。就這么一條簡(jiǎn)單的規(guī)則直接決定了后面用戶表、角色表和文檔表的關(guān)聯(lián)方式。1.2 為什么選SSM而不是Spring Boot這個(gè)問題幾乎每輪答辯都會(huì)被問到也是任務(wù)書如此設(shè)計(jì)技術(shù)棧的核心用意。SSM是一個(gè)典型的三層架構(gòu)技術(shù)組合Spring負(fù)責(zé)對(duì)象管理和事務(wù)控制SpringMVC負(fù)責(zé)HTTP請(qǐng)求的路由與參數(shù)綁定MyBatis負(fù)責(zé)SQL與對(duì)象映射。這三層各司其職邊界非常清晰。而Spring Boot把大量配置自動(dòng)化了你只需要引入依賴就能跑起來但底層的DispatcherServlet、HandlerMapping、SqlSessionFactory這些核心機(jī)制反而被隱藏了。對(duì)于以學(xué)習(xí)和教學(xué)為目的的任務(wù)書項(xiàng)目選SSM的意義在于你必須自己配置數(shù)據(jù)源、自己聲明事務(wù)管理器、自己寫攔截器、自己管理SQL映射這個(gè)過程能把框架的核心原理串起來。換句話說SSM版本做一遍Spring Boot版本就是水到渠成的事情。另外從實(shí)際運(yùn)維角度看很多公司在2015到2020年間沉淀的內(nèi)部系統(tǒng)就是SSM架構(gòu)目前依然在線運(yùn)行。一個(gè)能基于SSM做二次開發(fā)的工程師在老系統(tǒng)維護(hù)這個(gè)維度上是有實(shí)際價(jià)值的。1.3 功能模塊的拆解與邊界劃分動(dòng)手設(shè)計(jì)之前我會(huì)把任務(wù)書里的每一條功能要求拆成四層表現(xiàn)層、接口層、服務(wù)層、數(shù)據(jù)層。這是SSM項(xiàng)目的天然分層也是寫技術(shù)文檔時(shí)最直觀的結(jié)構(gòu)。以文檔檢索為例表現(xiàn)層是一個(gè)帶搜索框的列表頁(yè)接口層接收keyword、categoryId、pageNum、pageSize這些參數(shù)服務(wù)層負(fù)責(zé)拼接查詢條件并調(diào)用MyBatis的Mapper接口數(shù)據(jù)層則是動(dòng)態(tài)SQL的查詢語(yǔ)句。每一層只干自己的事后面排查問題的時(shí)候一層一層看效率很高。功能邊界同樣重要。任務(wù)書如果寫了回收站就要定義清楚用戶刪除文檔是邏輯刪除還是物理刪除回收站里的文檔保留多久徹底刪除是否需要管理員權(quán)限這些邊界問題如果不提前想清楚代碼寫到最后很容易陷進(jìn)改不完的狀態(tài)流轉(zhuǎn)。我的建議是畫一張角色權(quán)限矩陣橫軸是功能操作縱軸是角色類型單元格里標(biāo)注允許或不允許。這張表后面既是寫代碼的依據(jù)也是測(cè)試用例的來源。2. 數(shù)據(jù)庫(kù)設(shè)計(jì)與核心表結(jié)構(gòu)2.1 表結(jié)構(gòu)設(shè)計(jì)的原則與典型拆分文檔管理系統(tǒng)的數(shù)據(jù)庫(kù)表不會(huì)特別多但表與表之間的關(guān)聯(lián)關(guān)系很考驗(yàn)設(shè)計(jì)功底。一個(gè)典型的SSM文檔管理系統(tǒng)核心表包括用戶表、角色表、用戶角色關(guān)聯(lián)表、文檔分類表、文檔信息表、操作日志表。用戶表的核心字段是id、用戶名、密碼、真實(shí)姓名、郵箱、手機(jī)號(hào)、狀態(tài)、創(chuàng)建時(shí)間。密碼一定不要存明文用MD5加鹽或者BCrypt散列這是底線問題。角色表相對(duì)簡(jiǎn)單就是id、角色名、角色編碼和描述。用戶和角色是多對(duì)多關(guān)系所以需要一張中間關(guān)聯(lián)表。文檔信息表是整個(gè)系統(tǒng)最關(guān)鍵的一張表字段設(shè)計(jì)我后面單獨(dú)展開。分類表是自關(guān)聯(lián)結(jié)構(gòu)用parentId字段實(shí)現(xiàn)樹形目錄比如技術(shù)資料/后端/框架這就是兩層的父子關(guān)系。操作日志表記錄關(guān)鍵行為字段包括操作人、操作類型、操作對(duì)象、操作詳情、IP地址、操作時(shí)間。這張表的價(jià)值在于審計(jì)追溯屬于平時(shí)沒人看、出事必須查的表設(shè)計(jì)時(shí)寧可多存字段不要事后補(bǔ)字段。2.2 文件存儲(chǔ)方式數(shù)據(jù)庫(kù)BLOB還是磁盤路徑這是文檔管理系統(tǒng)里最容易糾結(jié)的決定。我見過有人把文件轉(zhuǎn)成byte[]直接塞進(jìn)數(shù)據(jù)庫(kù)的BLOB字段也見過只存文件路徑的做法。我的結(jié)論很明確主流可靠方案是文件存磁盤數(shù)據(jù)庫(kù)存元數(shù)據(jù)和路徑。用一個(gè)維度來對(duì)比會(huì)非常直觀對(duì)比項(xiàng)數(shù)據(jù)庫(kù)BLOB磁盤路徑元數(shù)據(jù)數(shù)據(jù)庫(kù)備份體積非常大備份恢復(fù)都很慢數(shù)據(jù)庫(kù)體積小備份快文件讀取性能每次讀取走數(shù)據(jù)庫(kù)連接高頻下載時(shí)是災(zāi)難文件流直接從磁盤讀或交給靜態(tài)資源服務(wù)器處理文件預(yù)覽支持需要額外寫二進(jìn)制流輸出邏輯配合Nginx映射目錄即可支持?jǐn)U展性數(shù)據(jù)庫(kù)擴(kuò)容成本高文件可遷移到OSS或分布式存儲(chǔ)如果任務(wù)書明確要求使用BLOB那說明這個(gè)項(xiàng)目是教學(xué)演示級(jí)重點(diǎn)是展示MyBatis對(duì)大字段的處理能力這種情況可以按照任務(wù)書執(zhí)行但也要在文檔里說明方案的局限性。如果任務(wù)書沒有強(qiáng)制要求存儲(chǔ)方式選磁盤路徑方案更合理也更符合企業(yè)真實(shí)做法。文件存儲(chǔ)目錄的規(guī)劃同樣重要。在應(yīng)用所在磁盤建立一個(gè)專用目錄比如/data/docfiles下面按日期或者按分類分子目錄存儲(chǔ)時(shí)給文件生成一個(gè)新的隨機(jī)文件名擴(kuò)展名保留原文件擴(kuò)展名。這樣做的好處是避免重名覆蓋同時(shí)避免特殊字符和中文名在文件系統(tǒng)層面的兼容問題。2.3 權(quán)限設(shè)計(jì)從簡(jiǎn)到繁的兩檔實(shí)現(xiàn)權(quán)限模型是文檔管理系統(tǒng)和普通文件目錄最本質(zhì)的區(qū)別。任務(wù)書通常會(huì)給兩種權(quán)限要求對(duì)應(yīng)的實(shí)現(xiàn)復(fù)雜度差別很大。第一檔是粗粒度權(quán)限只有管理員和普通用戶兩種角色管理員能做所有操作普通用戶只能操作自己上傳的文檔。這種模型不需要菜單表只需要在service層判斷當(dāng)前登錄用戶的角色和資源歸屬即可。第二檔是細(xì)粒度RBAC任務(wù)書可能要求不同角色看到不同菜單、不同按鈕這時(shí)候就要引入菜單表和角色菜單關(guān)聯(lián)表。登錄成功后查詢當(dāng)前角色的菜單列表動(dòng)態(tài)渲染左側(cè)導(dǎo)航欄。后端每個(gè)接口通過攔截器和注解雙重校驗(yàn)權(quán)限比第一檔復(fù)雜不少。我的建議是如果任務(wù)書沒有明確要求權(quán)限細(xì)分先做第一檔把核心業(yè)務(wù)流程跑通有余力再升級(jí)到第二檔。權(quán)限這東西最容易陷入過度設(shè)計(jì)一套系統(tǒng)如果一共就三個(gè)角色硬生生做五張權(quán)限表純屬給自己挖坑。3. 核心技術(shù)實(shí)現(xiàn)與實(shí)操要點(diǎn)3.1 登錄認(rèn)證與攔截器的完整實(shí)現(xiàn)登錄認(rèn)證幾乎是每一個(gè)SSM項(xiàng)目的第一個(gè)硬骨頭。流程不復(fù)雜但細(xì)節(jié)很多。登錄接口接收用戶名和密碼調(diào)用service層根據(jù)用戶名查詢用戶比對(duì)密碼時(shí)用MD5加鹽的方式前端提交明文密碼后端用固定鹽值拼上密碼再做MD5與數(shù)據(jù)庫(kù)存儲(chǔ)的散列值比對(duì)。成功之后將用戶對(duì)象放入session同時(shí)放入角色編碼后續(xù)每個(gè)請(qǐng)求通過攔截器從session中判斷登錄狀態(tài)。SpringMVC的攔截器需要實(shí)現(xiàn)HandlerInterceptor接口核心在preHandle方法里public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception { HttpSession session request.getSession(); Object user session.getAttribute(loginUser); if (user null) { response.sendRedirect(request.getContextPath() /login); return false; } return true; }這里有幾個(gè)關(guān)鍵配置需要注意。攔截器要排除登錄接口、注冊(cè)接口和靜態(tài)資源路徑否則CSS、JS、圖片全部被攔頁(yè)面會(huì)變成裸HTML。在spring-mvc.xml配置攔截器路徑時(shí)我用的是/*還是/**這點(diǎn)非常容易搞錯(cuò)。/*只匹配一級(jí)路徑/doc/detail/1這種多級(jí)URL會(huì)直接繞過攔截必須用/**才能匹配所有層級(jí)。還有一個(gè)隱患是session超時(shí)。Tomcat默認(rèn)session過期時(shí)間是30分鐘用戶在上傳大文件或長(zhǎng)時(shí)間停留后提交請(qǐng)求時(shí)session已經(jīng)失效會(huì)被攔截器踢回登錄頁(yè)。這個(gè)情況要在任務(wù)書文檔的異常處理部分提及生產(chǎn)環(huán)境可以適當(dāng)調(diào)大session超時(shí)時(shí)間或者配合記住我的Cookie機(jī)制做自動(dòng)登錄。3.2 文件上傳與下載的實(shí)現(xiàn)細(xì)節(jié)文件上傳是文檔管理系統(tǒng)的核心操作也是坑最多的地方。SpringMVC處理文件上傳依賴commons-fileupload和commons-io兩個(gè)庫(kù)在spring-mvc.xml中配置MultipartResolver。核心配置如下bean idmultipartResolver classorg.springframework.web.multipart.commons.CommonsMultipartResolver property namemaxUploadSize value104857600/ property namemaxInMemorySize value1048576/ property namedefaultEncoding valueUTF-8/ /beanmaxUploadSize是總上傳大小上限這里設(shè)置100MB單位是字節(jié)。maxInMemorySize是內(nèi)存緩沖閾值超過1MB的文件會(huì)先寫入臨時(shí)文件再處理避免大文件撐爆內(nèi)存。這兩個(gè)參數(shù)如果不設(shè)置Tomcat默認(rèn)單次請(qǐng)求最大數(shù)據(jù)量可能是2MB或者2048KB用戶傳個(gè)稍大的PDF就會(huì)報(bào)錯(cuò)。接收文件的Controller層方法簽名是MultipartFile參數(shù)PostMapping(/upload) ResponseBody public Result upload(RequestParam(file) MultipartFile file, RequestParam(categoryId) Integer categoryId) { if (file.isEmpty()) { return Result.error(請(qǐng)選擇文件); } String originalFilename file.getOriginalFilename(); String ext originalFilename.substring(originalFilename.lastIndexOf(.)); String newFileName UUID.randomUUID().toString().replace(-, ) ext; // 保存到磁盤 File dest new File(fileDir File.separator newFileName); file.transferTo(dest); // 插入文檔表記錄 docService.addDoc(...); }保存文件前一定要做擴(kuò)展名校驗(yàn)。任務(wù)書里通常會(huì)寫支持常見辦公文檔格式那就定義一個(gè)白名單doc、docx、xls、xlsx、ppt、pptx、pdf、txt、zip。不要用黑名單攔截exe、bat這種可執(zhí)行文件因?yàn)楹诿麊斡肋h(yuǎn)漏白名單才是可靠方案。下載文件有兩種寫法。一種是返回ResponseEntitybyte[]代碼簡(jiǎn)潔但大文件會(huì)把整個(gè)文件讀進(jìn)內(nèi)存另一種是直接用HttpServletResponse獲取OutputStream流式寫入這種方法對(duì)大文件更友好。流式下載核心代碼如下File file new File(filePath); response.setContentType(application/octet-stream); String fileName URLEncoder.encode(doc.getFileName(), UTF-8); response.setHeader(Content-Disposition, attachment;filename fileName); FileInputStream fis new FileInputStream(file); OutputStream os response.getOutputStream(); byte[] buffer new byte[1024 * 8]; int len; while ((len fis.read(buffer)) ! -1) { os.write(buffer, 0, len); } os.flush(); fis.close();這里最大的坑是下載文件名中文亂碼。HTTP協(xié)議頭不支持非ASCII字符必須用URLEncoder轉(zhuǎn)碼瀏覽器收到后會(huì)自動(dòng)解碼。如果不做這步文件名是中文的文檔下載下來全是亂碼。下載完成后還要回寫一條操作日志記錄哪個(gè)用戶在什么時(shí)間下載了哪個(gè)文件同時(shí)把數(shù)據(jù)庫(kù)里的下載數(shù)字段加一。這一步很多人會(huì)漏而操作日志恰恰是任務(wù)書評(píng)分的加分項(xiàng)。3.3 MyBatis動(dòng)態(tài)SQL與分頁(yè)查詢的最佳實(shí)踐文檔管理系統(tǒng)的查詢條件通常不固定用戶可能只按文件名搜也可能同時(shí)按分類和文件名搜還可能按上傳時(shí)間范圍搜。這種場(chǎng)景正是MyBatis動(dòng)態(tài)SQL發(fā)揮威力的地方。Mapper XML里用where和if標(biāo)簽拼接條件select idsearchDocs resultTypecom.example.pojo.Document select * from doc_info where if testkeyword ! null and keyword ! and file_name like concat(%, #{keyword}, %) /if if testcategoryId ! null and category_id #{categoryId} /if if testuploaderId ! null and uploader_id #{uploaderId} /if if teststartTime ! null and create_time gt; #{startTime} /if /where order by create_time desc /selectwhere標(biāo)簽會(huì)自動(dòng)處理第一個(gè)條件前面的and不用手動(dòng)加where 11這種寫法看起來不優(yōu)雅但在MyBatis里確實(shí)很多人還在用只是不建議因?yàn)闀?huì)影響查詢優(yōu)化器對(duì)索引的使用。分頁(yè)查詢我推薦使用PageHelper插件引入依賴后在service層調(diào)用PageHelper.startPage(pageNum, pageSize)緊接著的查詢就是分頁(yè)查詢?cè)偻ㄟ^PageInfo對(duì)象獲取總記錄數(shù)。用法如下PageHelper.startPage(pageNum, pageSize); ListDocument list docMapper.searchDocs(condition); PageInfoDocument pageInfo new PageInfo(list);PageHelper的原理是攔截MyBatis的Executor在查詢前自動(dòng)拼接LIMIT語(yǔ)句。優(yōu)點(diǎn)是代碼侵入性小缺點(diǎn)是有時(shí)候容易忘掉它只能在第一次查詢前調(diào)用如果Mapper里有兩個(gè)查詢它只對(duì)第一個(gè)生效。如果不想引入額外依賴也可以手寫LIMIT分頁(yè)自己算偏移量再單獨(dú)寫一條count查詢。這種方式更可控但代碼量大一些。課程設(shè)計(jì)階段用PageHelper完全足夠。還有一個(gè)MyBatis高頻坑插入文檔后要立刻拿到自增主鍵用于回填文檔ID和后續(xù)操作。配置起來很簡(jiǎn)單insert idaddDoc parameterTypecom.example.pojo.Document useGeneratedKeystrue keyPropertyid如果沒有這行配置你插入后拿到的id永遠(yuǎn)是0后面要做根據(jù)ID綁定分類、生成日志關(guān)聯(lián)ID時(shí)全都會(huì)出問題。4. 關(guān)鍵配置與部署實(shí)操4.1 環(huán)境準(zhǔn)備與依賴管理一個(gè)標(biāo)準(zhǔn)的SSM項(xiàng)目環(huán)境我這邊用的是JDK 1.8、Maven 3.6、Tomcat 8.5、MySQL 5.7。JDK 1.8在SSM生態(tài)里兼容性最好MyBatis和Spring的老版本都能正常跑Tomcat 8.5對(duì)應(yīng)Servlet 3.1規(guī)范支持SpringMVC的注解驅(qū)動(dòng)方式。Maven依賴是SSM項(xiàng)目里最容易出錯(cuò)的部分。常見問題是版本沖突spring-webmvc用的是5.xspring-jdbc卻引成一個(gè)4.x啟動(dòng)時(shí)各種NoSuchMethodError。建議所有Spring相關(guān)依賴統(tǒng)一版本屬性在pom.xml中定義properties spring.version5.3.28/spring.version /properties核心依賴清單如下用途依賴名說明Spring核心spring-context, spring-webmvc版本統(tǒng)一數(shù)據(jù)訪問mybatis, mybatis-springMyBatis和Spring整合連接池druid阿里連接池監(jiān)控方便文件上傳commons-fileupload, commons-ioMultipart支持JSON處理jackson-databind前后端交互分頁(yè)插件pagehelper分頁(yè)查詢JSTLjstl, taglibs-standard-implJSP頁(yè)面使用JDK 1.8對(duì)應(yīng)Tomcat版本不能太新Tomcat 10把javax改名成了jakartaSpring老版本的包全都找不到類這是新手常踩的坑。我推薦直接用Tomcat 8.5減少不必要的適配。4.2 SSM整合配置的三個(gè)關(guān)鍵文件SSM項(xiàng)目需要三份配置文件web.xml、spring-mvc.xml、spring-mybatis.xml。這三份文件的職責(zé)劃分清晰配置時(shí)各管各的。web.xml配置編碼過濾器、Spring容器監(jiān)聽器和DispatcherServletfilter filter-nameencodingFilter/filter-name filter-classorg.springframework.web.filter.CharacterEncodingFilter/filter-class init-param param-nameencoding/param-name param-valueUTF-8/param-value /init-param init-param param-nameforceEncoding/param-name param-valuetrue/param-value /init-param /filterCharacterEncodingFilter放在所有過濾器最前面而且forceEncoding要設(shè)為true否則只影響請(qǐng)求編碼不影響響應(yīng)編碼頁(yè)面會(huì)亂碼得很均勻。spring-mvc.xml配置掃描Controller包、注解驅(qū)動(dòng)、視圖解析器、攔截器和MultipartResolver。spring-mybatis.xml配置掃描service、配置數(shù)據(jù)源、配置SqlSessionFactory、配置Mapper掃描、配置事務(wù)管理器。DataSource用Druid連接池的核心參數(shù)是initialSize5、maxActive20、minIdle5這些參數(shù)要根據(jù)實(shí)際并發(fā)量調(diào)整不要默認(rèn)值跑天下。事務(wù)管理是我特別想強(qiáng)調(diào)的一點(diǎn)。文檔系統(tǒng)中刪除分類、批量搬移文件、更新文檔狀態(tài)這些操作涉及多張表如果沒有事務(wù)中間一步失敗會(huì)導(dǎo)致數(shù)據(jù)不一致。配置事務(wù)管理器后在Service實(shí)現(xiàn)類或方法上使用Transactional注解即可。4.3 部署到Tomcat的完整流程部署階段的任務(wù)是打包成war包丟進(jìn)Tomcat的webapps目錄。Maven打包前要先做幾個(gè)檢查數(shù)據(jù)庫(kù)連接URL的IP是不是生產(chǎn)庫(kù)的IP上傳文件目錄在服務(wù)器上是否存在磁盤權(quán)限是否可寫。war包部署后同樣有一個(gè)約束要提前規(guī)避上傳文件目錄不能放在Tomcat部署目錄內(nèi)部。如果文件存到webapps/upload下一次重新部署war包時(shí)整個(gè)目錄會(huì)被覆蓋用戶上傳的文件全部丟失。正確做法是把上傳目錄配置到Tomcat之外比如/data/docfiles通過配置文件注入路徑這樣重新部署也不會(huì)丟文件。生產(chǎn)環(huán)境的數(shù)據(jù)庫(kù)初始化腳本建議在部署文檔中單獨(dú)提供。建庫(kù)語(yǔ)句、建表語(yǔ)句、初始管理員賬號(hào)的插入語(yǔ)句都要寫成SQL腳本。初始化時(shí)要注意字符集設(shè)置建庫(kù)語(yǔ)句帶上DEFAULT CHARSETutf8mb4否則存emoji或生僻字時(shí)數(shù)據(jù)庫(kù)直接報(bào)錯(cuò)。5. 常見問題與排查技巧實(shí)錄5.1 文件上傳失敗的幾種典型場(chǎng)景上傳功能是這個(gè)項(xiàng)目問題重災(zāi)區(qū)我把常見問題匯總成表格排查時(shí)對(duì)照著看效率很高。報(bào)錯(cuò)現(xiàn)象根本原因解決方案請(qǐng)求被拒絕超出大小限制maxUploadSize未配置或太小設(shè)置CommonsMultipartResolver的maxUploadSize空文件也能上傳成功未判空file.isEmpty()Controller層加判空和擴(kuò)展名校驗(yàn)上傳中文文件名保存后亂碼編碼過濾器未設(shè)置或順序不對(duì)web.xml放最前forceEncodingtrue傳到本地目錄出現(xiàn)重復(fù)文件直接用原文件名改用UUID隨機(jī)名存儲(chǔ)大文件上傳內(nèi)存溢出maxInMemorySize過大設(shè)為1MB左右觸發(fā)臨時(shí)文件機(jī)制還有一個(gè)很容易被忽略的問題如果項(xiàng)目配置了Spring Security或自定義的過濾器它可能會(huì)讀取并消費(fèi)請(qǐng)求體導(dǎo)致MultipartResolver拿不到文件數(shù)據(jù)。雖然SSM項(xiàng)目一般不引入Security但如果遇到上傳接口無響應(yīng)的情況優(yōu)先檢查過濾器鏈有沒有攔請(qǐng)求體。5.2 中文亂碼的一次排查實(shí)錄亂碼問題在SSM項(xiàng)目中幾乎不可避免我實(shí)際排查過的案例里亂碼往往不是單一原因而是多層疊加的結(jié)果。假設(shè)上傳一個(gè)名為產(chǎn)品需求說明書.docx的文件下載后文件名變成亂碼。第一層檢查URL編碼Content-Disposition頭里必須用URLEncoder.encode轉(zhuǎn)碼第二層檢查瀏覽器解碼方式不同瀏覽器對(duì)RFC 5987格式的支持有差異我最終用了一個(gè)簡(jiǎn)單粗暴且兼容的方案文件名轉(zhuǎn)碼成UTF-8后再按ISO-8859-1重新編碼再用URLEncoder處理雖然繞了一點(diǎn)但對(duì)主流瀏覽器都有效。如果列表頁(yè)顯示的文件名亂碼那是數(shù)據(jù)庫(kù)層面或者前端頁(yè)面編碼的問題。數(shù)據(jù)庫(kù)連接URL要加characterEncodingutf8頁(yè)面JSP的pageEncoding要設(shè)置為UTF-8Tomcat的URIEncoding也要設(shè)為UTF-8。這三個(gè)地方只要有一個(gè)漏了中文就會(huì)在某個(gè)環(huán)節(jié)變成問號(hào)。排查思路永遠(yuǎn)是從源頭到展示一步步試不要瞎改配置。先用數(shù)據(jù)庫(kù)客戶端直接查庫(kù)判斷數(shù)據(jù)本身是否正常再判斷是后端返回前就已經(jīng)亂碼還是瀏覽器顯示時(shí)亂碼。定位到具體環(huán)節(jié)修復(fù)就很快了。5.3 前端與后端聯(lián)調(diào)中的隱藏坑前后端分離不是SSM的主流用法但很多任務(wù)書要求頁(yè)面顯示結(jié)果和接口分開測(cè)試。用AJAX請(qǐng)求JSON數(shù)據(jù)時(shí)有幾個(gè)坑不可避免。Jackson默認(rèn)序列化Date類型的結(jié)果是一長(zhǎng)串時(shí)間戳數(shù)字前端顯示很丑陋。解決辦法是在實(shí)體類的日期字段上加注解JsonFormat(pattern yyyy-MM-dd HH:mm:ss, timezone GMT8) private Date createTime;另一個(gè)是static靜態(tài)資源被攔截的問題。如果spring-mvc.xml里沒有放行靜態(tài)資源瀏覽器打開頁(yè)面時(shí)CSS和JS全部加載失敗頁(yè)面光禿禿的。配置方式有兩種要么用mvc:default-servlet-handler/交給默認(rèn)Servlet處理要么用mvc:resources mapping/static/** location/static//指定資源路徑映射。我推薦使用mapping方式匹配規(guī)則更明確。JSON字符串中文亂碼也比較常見。SpringMVC的ResponseBody默認(rèn)StringHttpMessageConverter編碼是ISO-8859-1需要在spring-mvc.xml配置消息轉(zhuǎn)換器使用UTF-8否則通過AJAX返回的中文全是問號(hào)。5.4 性能與安全的基本加固文檔管理系統(tǒng)的并發(fā)量一般不高但也不能完全不考慮性能和建議層面的安全加固尤其是任務(wù)書如果涉及系統(tǒng)的非功能需求這一節(jié)。查詢性能的重中之重是索引。doc_info表的file_name字段如果經(jīng)常被模糊查詢可以建立前綴索引create_time字段用于排序建普通索引即可category_id是外鍵關(guān)聯(lián)字段頻繁做等值查詢必須建索引。安全方面有兩個(gè)底線操作必須做。一是密碼加密二是SQL注入防護(hù)。MyBatis的#{}預(yù)編譯天然防止SQL注入但那種手寫拼接${}的地方要特別小心一旦出現(xiàn)在用戶可控參數(shù)的場(chǎng)景就存在注入風(fēng)險(xiǎn)。上傳文件的存儲(chǔ)路徑也要做合法性校驗(yàn)嚴(yán)禁用戶通過路徑穿越等方式訪問系統(tǒng)目錄。我一般在保存文件時(shí)直接使用數(shù)據(jù)庫(kù)生成的ID和時(shí)間戳重構(gòu)文件名完全不用原始文件名這樣可以最大化降低這類風(fēng)險(xiǎn)。還有一個(gè)經(jīng)驗(yàn)是備份策略。文檔系統(tǒng)的數(shù)據(jù)價(jià)值主要在文件本身數(shù)據(jù)庫(kù)可以每天備份一次但文件目錄最好采用增量同步方案。我在模擬項(xiàng)目X中寫過一個(gè)簡(jiǎn)單的Shell腳本每天凌晨將當(dāng)日新增文件同步到備份盤這個(gè)操作成本極低關(guān)鍵時(shí)候能救命。6. 從任務(wù)書到交付的項(xiàng)目管理心得6.1 任務(wù)書的驗(yàn)收標(biāo)準(zhǔn)如何落實(shí)到開發(fā)計(jì)劃任務(wù)書在結(jié)尾部分通常會(huì)有成果要求比如系統(tǒng)運(yùn)行截圖、核心代碼說明、數(shù)據(jù)庫(kù)設(shè)計(jì)文檔、操作手冊(cè)、測(cè)試報(bào)告。這些文檔不是最后一天能趕出來的最好開發(fā)過程中同步積累。我習(xí)慣在項(xiàng)目目錄下維護(hù)三個(gè)文檔技術(shù)方案書、數(shù)據(jù)庫(kù)設(shè)計(jì)說明、測(cè)試記錄表。技術(shù)方案書寫框架選型理由和模塊劃分?jǐn)?shù)據(jù)庫(kù)設(shè)計(jì)說明標(biāo)注每張表每個(gè)字段的業(yè)務(wù)含義測(cè)試記錄表把每個(gè)功能點(diǎn)的操作步驟和結(jié)果截圖存檔。這份資料往任務(wù)書里一貼就是一份非常完整的項(xiàng)目材料。時(shí)間分配上前期設(shè)計(jì)占30%編碼占50%測(cè)試和文檔占20%。新手最常犯的錯(cuò)誤是一上來就寫代碼寫到一半發(fā)現(xiàn)表結(jié)構(gòu)不合理返工成本極高。6.2 答辯和評(píng)審環(huán)節(jié)的講解重點(diǎn)如果這個(gè)項(xiàng)目最終要答辯講解的邏輯主線應(yīng)該是需求分析到表設(shè)計(jì)表設(shè)計(jì)到代碼實(shí)現(xiàn)代碼實(shí)現(xiàn)到功能演示。不要一上來就念代碼要先講清楚為什么這樣設(shè)計(jì)。我建議準(zhǔn)備一個(gè)設(shè)計(jì)決策表把任務(wù)書中每個(gè)關(guān)鍵要求對(duì)應(yīng)到具體的實(shí)現(xiàn)方案和技術(shù)點(diǎn)。比如任務(wù)書寫了支持多條件組合檢索就對(duì)應(yīng)MyBatis動(dòng)態(tài)SQL寫不同角色對(duì)文檔操作權(quán)限不同就對(duì)應(yīng)攔截器和角色判斷邏輯。答辯時(shí)評(píng)委問什么就從這張表里找答案。演示環(huán)節(jié)一定要用自己的測(cè)試數(shù)據(jù)不要用空的數(shù)據(jù)庫(kù)或者只有兩三條記錄的庫(kù)演示。提前準(zhǔn)備好十來份不同格式的測(cè)試文檔把搜索、分類、權(quán)限切換、回收站恢復(fù)這些操作連貫演示一遍效果比說一百句話都強(qiáng)。6.3 拓展思路與后續(xù)升級(jí)方向SSM版本的文檔管理系統(tǒng)做完后往下的升級(jí)路徑很清晰如果團(tuán)隊(duì)規(guī)模變大可以替換成Spring Boot來降低維護(hù)成本配合Spring Security做更細(xì)粒度的權(quán)限控制如果文件量繼續(xù)增長(zhǎng)可以對(duì)接對(duì)象存儲(chǔ)服務(wù)把文件從本地磁盤搬遷到云端數(shù)據(jù)庫(kù)只存訪問地址如果要做在線預(yù)覽可以通過中間件把Office文件轉(zhuǎn)換成PDF后再展示這也是企業(yè)版文檔系統(tǒng)最常見的功能。技術(shù)選型從來不是追新而是合適。SSM這套組合雖然在配置上比Spring Boot繁瑣但它的每一行配置都在幫你理解Web開發(fā)底層發(fā)生了什么。這個(gè)理解在排查線上問題時(shí)非常值錢。我個(gè)人在多次做過類似系統(tǒng)后最大的體會(huì)是文檔管理系統(tǒng)的難點(diǎn)不在存取文件而在定義清楚誰(shuí)能做什么。任務(wù)書限定SSM反而是件好事它強(qiáng)迫你把權(quán)限、流程、狀態(tài)這些業(yè)務(wù)規(guī)則用最傳統(tǒng)但最扎實(shí)的三層結(jié)構(gòu)寫出來。把這份功課做扎實(shí)了以后不管換成什么框架、什么存儲(chǔ)、什么部署方式核心的業(yè)務(wù)建模能力都是通用的。