目規(guī)范化：工具類、封裝、代碼生成)
項(xiàng)目規(guī)范化工具類、封裝、代碼生成一個(gè)人寫(xiě)項(xiàng)目像寫(xiě)日記——自己能看懂就行團(tuán)隊(duì)協(xié)作像寫(xiě)公文——格式不統(tǒng)一就亂套。項(xiàng)目規(guī)范化不是為了好看是為了讓你三個(gè)月后回來(lái)還能看懂自己寫(xiě)的什么。一、項(xiàng)目規(guī)范化的意義可維護(hù)性代碼結(jié)構(gòu)清晰定位問(wèn)題快修改影響范圍可控團(tuán)隊(duì)協(xié)作效率新人接手項(xiàng)目不需要猜約定看目錄結(jié)構(gòu)就知道代碼在哪減少低級(jí)錯(cuò)誤統(tǒng)一封裝減少重復(fù)代碼魔法值用枚舉代替減少手寫(xiě)出錯(cuò)代碼審查效率規(guī)范統(tǒng)一的代碼風(fēng)格Review時(shí)聚焦業(yè)務(wù)邏輯而非格式問(wèn)題規(guī)范化不是寫(xiě)一堆文檔約束人而是通過(guò)工程手段讓規(guī)范自動(dòng)落地。二、項(xiàng)目分層規(guī)范經(jīng)典的三層架構(gòu)分層每層職責(zé)明確src/main/java/com/example/ ├── controller/ # 控制層接收請(qǐng)求、參數(shù)校驗(yàn)、返回結(jié)果 ├── service/ # 業(yè)務(wù)層業(yè)務(wù)邏輯編排 │ └── impl/ ├── mapper/ # 持久層數(shù)據(jù)庫(kù)操作MyBatis接口 ├── entity/ # 實(shí)體類與數(shù)據(jù)庫(kù)表對(duì)應(yīng) ├── dto/ # 數(shù)據(jù)傳輸對(duì)象接口入?yún)⒊鰠?│ ├── request/ # 請(qǐng)求DTO │ └── response/ # 響應(yīng)DTO ├── vo/ # 視圖對(duì)象返回給前端的對(duì)象 ├── utils/ # 工具類 ├── config/ # 配置類 ├── exception/ # 自定義異常 ├── enums/ # 枚舉類 └── constant/ # 常量類分層依賴方向Controller → Service → Mapper禁止跨層調(diào)用Controller不能直接調(diào)Mapper禁止反向依賴Entity不能依賴DTO。三、命名規(guī)范類型規(guī)范示例類名大駝峰UserController, OrderService方法名小駝峰getUserById, createOrder變量名小駝峰userName, orderList常量名全大寫(xiě)下劃線MAX_RETRY_COUNT, DEFAULT_PAGE_SIZE包名全小寫(xiě)com.example.controller數(shù)據(jù)庫(kù)表名小寫(xiě)下劃線t_user, t_order_detail接口名不加I前綴UserService非IUserService實(shí)現(xiàn)類名接口名ImplUserServiceImpl四、統(tǒng)一返回封裝所有接口返回統(tǒng)一結(jié)構(gòu)前端只需按固定格式解析。4.1 Result封裝DataSchema(description統(tǒng)一返回結(jié)構(gòu))publicclassResultT{privateIntegercode;privateStringmessage;privateTdata;privateResult(Integercode,Stringmessage,Tdata){this.codecode;this.messagemessage;this.datadata;}publicstaticTResultTsuccess(Tdata){returnnewResult(200,操作成功,data);}publicstaticTResultTsuccess(){returnnewResult(200,操作成功,null);}publicstaticTResultTfail(Stringmessage){returnnewResult(500,message,null);}publicstaticTResultTfail(Integercode,Stringmessage){returnnewResult(code,message,null);}}4.2 分頁(yè)結(jié)果封裝DataAllArgsConstructorpublicclassPageResultT{privateListTlist;// 數(shù)據(jù)列表privateLongtotal;// 總記錄數(shù)privateIntegerpageNum;// 當(dāng)前頁(yè)碼privateIntegerpageSize;// 每頁(yè)條數(shù)privateIntegertotalPages;// 總頁(yè)數(shù)publicstaticTPageResultTof(ListTlist,Longtotal,IntegerpageNum,IntegerpageSize){inttotalPages(int)Math.ceil((double)total/pageSize);returnnewPageResult(list,total,pageNum,pageSize,totalPages);}}五、基礎(chǔ)實(shí)體封裝數(shù)據(jù)庫(kù)表通常都有公共字段創(chuàng)建時(shí)間、更新時(shí)間等抽取BaseEntity避免每個(gè)實(shí)體重復(fù)定義。DatapublicclassBaseEntity{TableId(typeIdType.ASSIGN_ID)// 雪花算法生成IDprivateLongid;TableField(fillFieldFill.INSERT)// 插入時(shí)自動(dòng)填充privateLocalDateTimecreateTime;TableField(fillFieldFill.INSERT_UPDATE)// 插入和更新時(shí)自動(dòng)填充privateLocalDateTimeupdateTime;TableField(fillFieldFill.INSERT)privateLongcreateBy;TableField(fillFieldFill.INSERT_UPDATE)privateLongupdateBy;TableLogic// 邏輯刪除標(biāo)記TableField(fillFieldFill.INSERT)privateIntegerdeleted;}MyBatis-Plus自動(dòng)填充處理器ComponentpublicclassMyMetaObjectHandlerimplementsMetaObjectHandler{OverridepublicvoidinsertFill(MetaObjectmetaObject){this.strictInsertFill(metaObject,createTime,LocalDateTime.class,LocalDateTime.now());this.strictInsertFill(metaObject,updateTime,LocalDateTime.class,LocalDateTime.now());this.strictInsertFill(metaObject,deleted,Integer.class,0);// 當(dāng)前登錄用戶ID從ThreadLocal/SecurityContext獲取LonguserIdSecurityUtils.getCurrentUserId();this.strictInsertFill(metaObject,createBy,Long.class,userId);this.strictInsertFill(metaObject,updateBy,Long.class,userId);}OverridepublicvoidupdateFill(MetaObjectmetaObject){this.strictUpdateFill(metaObject,updateTime,LocalDateTime.class,LocalDateTime.now());this.strictUpdateFill(metaObject,updateBy,Long.class,SecurityUtils.getCurrentUserId());}}實(shí)體類繼承BaseEntity即可自動(dòng)獲得這些公共字段DataEqualsAndHashCode(callSupertrue)TableName(t_user)publicclassUserextendsBaseEntity{privateStringusername;privateStringpassword;privateStringemail;privateIntegerstatus;}六、枚舉規(guī)范代碼里到處寫(xiě)012這種魔法值過(guò)兩個(gè)月誰(shuí)也不記得1是啟用還是禁用。用枚舉替代。GetterAllArgsConstructorpublicenumUserStatusEnum{DISABLED(0,禁用),ENABLED(1,啟用),LOCKED(2,鎖定);privatefinalIntegercode;privatefinalStringdesc;publicstaticUserStatusEnumgetByCode(Integercode){for(UserStatusEnume:values()){if(e.getCode().equals(code)){returne;}}thrownewIllegalArgumentException(無(wú)效的狀態(tài)碼: code);}}// 反面教材魔法值if(user.getStatus()1){...}// 正面示范枚舉if(UserStatusEnum.ENABLED.getCode().equals(user.getStatus())){...}常用枚舉場(chǎng)景狀態(tài)碼、性別、訂單狀態(tài)、支付方式、用戶角色等。七、工具類封裝7.1 自定義工具類publicclassRegexUtils{privatestaticfinalPatternPHONE_PATTERNPattern.compile(^1[3-9]\\d{9}$);privatestaticfinalPatternEMAIL_PATTERNPattern.compile(^[A-Za-z0-9_.-][A-Za-z0-9.-]$);publicstaticbooleanisPhone(Stringphone){returnphone!nullPHONE_PATTERN.matcher(phone).matches();}publicstaticbooleanisEmail(Stringemail){returnemail!nullEMAIL_PATTERN.matcher(email).matches();}}7.2 Hutool工具庫(kù)推薦自己寫(xiě)工具類容易遺漏邊界場(chǎng)景推薦使用Hutool——國(guó)內(nèi)最流行的Java工具庫(kù)500工具方法覆蓋絕大多數(shù)場(chǎng)景。dependencygroupIdcn.hutool/groupIdartifactIdhutool-all/artifactIdversion5.8.25/version/dependency// 字符串工具StrUtil.isBlank(str);// 判空StrUtil.format(用戶{}已存在,name);// 格式化// 日期工具DateUtil.now();// 當(dāng)前時(shí)間字符串DateUtil.formatDateTime(date);// 格式化日期// 加密工具SecureUtil.md5(password);// MD5加密SecureUtil.sha256(password);// SHA256加密// ID生成IdUtil.getSnowflakeNextId();// 雪花算法ID// HTTP客戶端HttpUtil.get(https://api.example.com/data);HttpUtil.post(url,body);// JSON處理JSONUtil.toJsonStr(obj);JSONUtil.parseObj(json).getStr(key);Hutool一個(gè)庫(kù)頂你自己寫(xiě)幾十個(gè)工具類而且經(jīng)過(guò)大量生產(chǎn)驗(yàn)證比手寫(xiě)更可靠。八、代碼生成MyBatisX手動(dòng)寫(xiě)Entity/Mapper/Service/Controller四件套既枯燥又容易出錯(cuò)。MyBatisX是IDEA插件連接數(shù)據(jù)庫(kù)后一鍵生成整套代碼。使用流程IDEA安裝MyBatisX插件連接數(shù)據(jù)庫(kù)Database面板右鍵表 → MyBatisX-Generator配置生成選項(xiàng)module選擇當(dāng)前項(xiàng)目模塊packagecom.exampleentity勾選繼承BaseEntitymapper勾選生成Mapper接口service勾選生成Service接口Implcontroller勾選生成基礎(chǔ)CRUD接口點(diǎn)擊Generate一鍵生成生成后只需補(bǔ)充業(yè)務(wù)邏輯省去80%的重復(fù)勞動(dòng)。九、代碼規(guī)范檢查阿里巴巴Java開(kāi)發(fā)規(guī)約插件IDEA安裝Alibaba Java Coding Guidelines插件編碼時(shí)實(shí)時(shí)檢查規(guī)范問(wèn)題命名不規(guī)范空指針風(fēng)險(xiǎn)線程安全問(wèn)題魔法值未提取常量集合未指定初始容量!-- Checkstyle靜態(tài)檢查CI集成 --plugingroupIdorg.apache.maven.plugins/groupIdartifactIdmaven-checkstyle-plugin/artifactIdversion3.3.0/versionconfigurationconfigLocationcheckstyle-alibaba.xml/configLocation/configuration/plugin十、完整規(guī)范化項(xiàng)目結(jié)構(gòu)com.example.shop/ ├── ShopApplication.java ├── config/ │ ├── Knife4jConfig.java │ ├── MyBatisPlusConfig.java │ ├── RedisConfig.java │ └── WebMvcConfig.java ├── common/ │ ├── result/ │ │ ├── Result.java │ │ └── PageResult.java │ ├── entity/ │ │ └── BaseEntity.java │ ├── exception/ │ │ ├── BusinessException.java │ │ └── GlobalExceptionHandler.java │ ├── enums/ │ │ ├── UserStatusEnum.java │ │ └── OrderStatusEnum.java │ └── constant/ │ └── RedisConstant.java ├── controller/ │ ├── user/ │ │ └── UserController.java │ └── order/ │ └── OrderController.java ├── service/ │ ├── user/ │ │ ├── UserService.java │ │ └── impl/UserServiceImpl.java │ └── order/ │ ├── OrderService.java │ └── impl/OrderServiceImpl.java ├── mapper/ │ ├── UserMapper.java │ └── OrderMapper.java ├── entity/ │ ├── User.java │ └── Order.java ├── dto/ │ ├── request/ │ │ ├── UserLoginDTO.java │ │ └── OrderCreateDTO.java │ └── response/ │ ├── UserVO.java │ └── OrderVO.java └── utils/ ├── RegexUtils.java └── SecurityUtils.java項(xiàng)目規(guī)范化不是一蹴而就的是在開(kāi)發(fā)過(guò)程中逐步沉淀的。前期花時(shí)間搭好骨架后期團(tuán)隊(duì)所有人都能受益——寫(xiě)代碼時(shí)有章可循改代碼時(shí)有跡可循這才是規(guī)范化的真正價(jià)值。 項(xiàng)目規(guī)范化：工具類、封裝、代碼生成
項(xiàng)目規(guī)范化工具類、封裝、代碼生成一個(gè)人寫(xiě)項(xiàng)目像寫(xiě)日記——自己能看懂就行團(tuán)隊(duì)協(xié)作像寫(xiě)公文——格式不統(tǒng)一就亂套。項(xiàng)目規(guī)范化不是為了好看是為了讓你三個(gè)月后回來(lái)還能看懂自己寫(xiě)的什么。一、項(xiàng)目規(guī)范化的意義可維護(hù)性代碼結(jié)構(gòu)清晰定位問(wèn)題快修改影響范圍可控團(tuán)隊(duì)協(xié)作效率新人接手項(xiàng)目不需要猜約定看目錄結(jié)構(gòu)就知道代碼在哪減少低級(jí)錯(cuò)誤統(tǒng)一封裝減少重復(fù)代碼魔法值用枚舉代替減少手寫(xiě)出錯(cuò)代碼審查效率規(guī)范統(tǒng)一的代碼風(fēng)格Review時(shí)聚焦業(yè)務(wù)邏輯而非格式問(wèn)題規(guī)范化不是寫(xiě)一堆文檔約束人而是通過(guò)工程手段讓規(guī)范自動(dòng)落地。二、項(xiàng)目分層規(guī)范經(jīng)典的三層架構(gòu)分層每層職責(zé)明確src/main/java/com/example/ ├── controller/ # 控制層接收請(qǐng)求、參數(shù)校驗(yàn)、返回結(jié)果 ├── service/ # 業(yè)務(wù)層業(yè)務(wù)邏輯編排 │ └── impl/ ├── mapper/ # 持久層數(shù)據(jù)庫(kù)操作MyBatis接口 ├── entity/ # 實(shí)體類與數(shù)據(jù)庫(kù)表對(duì)應(yīng) ├── dto/ # 數(shù)據(jù)傳輸對(duì)象接口入?yún)⒊鰠?│ ├── request/ # 請(qǐng)求DTO │ └── response/ # 響應(yīng)DTO ├── vo/ # 視圖對(duì)象返回給前端的對(duì)象 ├── utils/ # 工具類 ├── config/ # 配置類 ├── exception/ # 自定義異常 ├── enums/ # 枚舉類 └── constant/ # 常量類分層依賴方向Controller → Service → Mapper禁止跨層調(diào)用Controller不能直接調(diào)Mapper禁止反向依賴Entity不能依賴DTO。三、命名規(guī)范類型規(guī)范示例類名大駝峰UserController, OrderService方法名小駝峰getUserById, createOrder變量名小駝峰userName, orderList常量名全大寫(xiě)下劃線MAX_RETRY_COUNT, DEFAULT_PAGE_SIZE包名全小寫(xiě)com.example.controller數(shù)據(jù)庫(kù)表名小寫(xiě)下劃線t_user, t_order_detail接口名不加I前綴UserService非IUserService實(shí)現(xiàn)類名接口名ImplUserServiceImpl四、統(tǒng)一返回封裝所有接口返回統(tǒng)一結(jié)構(gòu)前端只需按固定格式解析。4.1 Result封裝DataSchema(description統(tǒng)一返回結(jié)構(gòu))publicclassResultT{privateIntegercode;privateStringmessage;privateTdata;privateResult(Integercode,Stringmessage,Tdata){this.codecode;this.messagemessage;this.datadata;}publicstaticTResultTsuccess(Tdata){returnnewResult(200,操作成功,data);}publicstaticTResultTsuccess(){returnnewResult(200,操作成功,null);}publicstaticTResultTfail(Stringmessage){returnnewResult(500,message,null);}publicstaticTResultTfail(Integercode,Stringmessage){returnnewResult(code,message,null);}}4.2 分頁(yè)結(jié)果封裝DataAllArgsConstructorpublicclassPageResultT{privateListTlist;// 數(shù)據(jù)列表privateLongtotal;// 總記錄數(shù)privateIntegerpageNum;// 當(dāng)前頁(yè)碼privateIntegerpageSize;// 每頁(yè)條數(shù)privateIntegertotalPages;// 總頁(yè)數(shù)publicstaticTPageResultTof(ListTlist,Longtotal,IntegerpageNum,IntegerpageSize){inttotalPages(int)Math.ceil((double)total/pageSize);returnnewPageResult(list,total,pageNum,pageSize,totalPages);}}五、基礎(chǔ)實(shí)體封裝數(shù)據(jù)庫(kù)表通常都有公共字段創(chuàng)建時(shí)間、更新時(shí)間等抽取BaseEntity避免每個(gè)實(shí)體重復(fù)定義。DatapublicclassBaseEntity{TableId(typeIdType.ASSIGN_ID)// 雪花算法生成IDprivateLongid;TableField(fillFieldFill.INSERT)// 插入時(shí)自動(dòng)填充privateLocalDateTimecreateTime;TableField(fillFieldFill.INSERT_UPDATE)// 插入和更新時(shí)自動(dòng)填充privateLocalDateTimeupdateTime;TableField(fillFieldFill.INSERT)privateLongcreateBy;TableField(fillFieldFill.INSERT_UPDATE)privateLongupdateBy;TableLogic// 邏輯刪除標(biāo)記TableField(fillFieldFill.INSERT)privateIntegerdeleted;}MyBatis-Plus自動(dòng)填充處理器ComponentpublicclassMyMetaObjectHandlerimplementsMetaObjectHandler{OverridepublicvoidinsertFill(MetaObjectmetaObject){this.strictInsertFill(metaObject,createTime,LocalDateTime.class,LocalDateTime.now());this.strictInsertFill(metaObject,updateTime,LocalDateTime.class,LocalDateTime.now());this.strictInsertFill(metaObject,deleted,Integer.class,0);// 當(dāng)前登錄用戶ID從ThreadLocal/SecurityContext獲取LonguserIdSecurityUtils.getCurrentUserId();this.strictInsertFill(metaObject,createBy,Long.class,userId);this.strictInsertFill(metaObject,updateBy,Long.class,userId);}OverridepublicvoidupdateFill(MetaObjectmetaObject){this.strictUpdateFill(metaObject,updateTime,LocalDateTime.class,LocalDateTime.now());this.strictUpdateFill(metaObject,updateBy,Long.class,SecurityUtils.getCurrentUserId());}}實(shí)體類繼承BaseEntity即可自動(dòng)獲得這些公共字段DataEqualsAndHashCode(callSupertrue)TableName(t_user)publicclassUserextendsBaseEntity{privateStringusername;privateStringpassword;privateStringemail;privateIntegerstatus;}六、枚舉規(guī)范代碼里到處寫(xiě)012這種魔法值過(guò)兩個(gè)月誰(shuí)也不記得1是啟用還是禁用。用枚舉替代。GetterAllArgsConstructorpublicenumUserStatusEnum{DISABLED(0,禁用),ENABLED(1,啟用),LOCKED(2,鎖定);privatefinalIntegercode;privatefinalStringdesc;publicstaticUserStatusEnumgetByCode(Integercode){for(UserStatusEnume:values()){if(e.getCode().equals(code)){returne;}}thrownewIllegalArgumentException(無(wú)效的狀態(tài)碼: code);}}// 反面教材魔法值if(user.getStatus()1){...}// 正面示范枚舉if(UserStatusEnum.ENABLED.getCode().equals(user.getStatus())){...}常用枚舉場(chǎng)景狀態(tài)碼、性別、訂單狀態(tài)、支付方式、用戶角色等。七、工具類封裝7.1 自定義工具類publicclassRegexUtils{privatestaticfinalPatternPHONE_PATTERNPattern.compile(^1[3-9]\\d{9}$);privatestaticfinalPatternEMAIL_PATTERNPattern.compile(^[A-Za-z0-9_.-][A-Za-z0-9.-]$);publicstaticbooleanisPhone(Stringphone){returnphone!nullPHONE_PATTERN.matcher(phone).matches();}publicstaticbooleanisEmail(Stringemail){returnemail!nullEMAIL_PATTERN.matcher(email).matches();}}7.2 Hutool工具庫(kù)推薦自己寫(xiě)工具類容易遺漏邊界場(chǎng)景推薦使用Hutool——國(guó)內(nèi)最流行的Java工具庫(kù)500工具方法覆蓋絕大多數(shù)場(chǎng)景。dependencygroupIdcn.hutool/groupIdartifactIdhutool-all/artifactIdversion5.8.25/version/dependency// 字符串工具StrUtil.isBlank(str);// 判空StrUtil.format(用戶{}已存在,name);// 格式化// 日期工具DateUtil.now();// 當(dāng)前時(shí)間字符串DateUtil.formatDateTime(date);// 格式化日期// 加密工具SecureUtil.md5(password);// MD5加密SecureUtil.sha256(password);// SHA256加密// ID生成IdUtil.getSnowflakeNextId();// 雪花算法ID// HTTP客戶端HttpUtil.get(https://api.example.com/data);HttpUtil.post(url,body);// JSON處理JSONUtil.toJsonStr(obj);JSONUtil.parseObj(json).getStr(key);Hutool一個(gè)庫(kù)頂你自己寫(xiě)幾十個(gè)工具類而且經(jīng)過(guò)大量生產(chǎn)驗(yàn)證比手寫(xiě)更可靠。八、代碼生成MyBatisX手動(dòng)寫(xiě)Entity/Mapper/Service/Controller四件套既枯燥又容易出錯(cuò)。MyBatisX是IDEA插件連接數(shù)據(jù)庫(kù)后一鍵生成整套代碼。使用流程IDEA安裝MyBatisX插件連接數(shù)據(jù)庫(kù)Database面板右鍵表 → MyBatisX-Generator配置生成選項(xiàng)module選擇當(dāng)前項(xiàng)目模塊packagecom.exampleentity勾選繼承BaseEntitymapper勾選生成Mapper接口service勾選生成Service接口Implcontroller勾選生成基礎(chǔ)CRUD接口點(diǎn)擊Generate一鍵生成生成后只需補(bǔ)充業(yè)務(wù)邏輯省去80%的重復(fù)勞動(dòng)。九、代碼規(guī)范檢查阿里巴巴Java開(kāi)發(fā)規(guī)約插件IDEA安裝Alibaba Java Coding Guidelines插件編碼時(shí)實(shí)時(shí)檢查規(guī)范問(wèn)題命名不規(guī)范空指針風(fēng)險(xiǎn)線程安全問(wèn)題魔法值未提取常量集合未指定初始容量!-- Checkstyle靜態(tài)檢查CI集成 --plugingroupIdorg.apache.maven.plugins/groupIdartifactIdmaven-checkstyle-plugin/artifactIdversion3.3.0/versionconfigurationconfigLocationcheckstyle-alibaba.xml/configLocation/configuration/plugin十、完整規(guī)范化項(xiàng)目結(jié)構(gòu)com.example.shop/ ├── ShopApplication.java ├── config/ │ ├── Knife4jConfig.java │ ├── MyBatisPlusConfig.java │ ├── RedisConfig.java │ └── WebMvcConfig.java ├── common/ │ ├── result/ │ │ ├── Result.java │ │ └── PageResult.java │ ├── entity/ │ │ └── BaseEntity.java │ ├── exception/ │ │ ├── BusinessException.java │ │ └── GlobalExceptionHandler.java │ ├── enums/ │ │ ├── UserStatusEnum.java │ │ └── OrderStatusEnum.java │ └── constant/ │ └── RedisConstant.java ├── controller/ │ ├── user/ │ │ └── UserController.java │ └── order/ │ └── OrderController.java ├── service/ │ ├── user/ │ │ ├── UserService.java │ │ └── impl/UserServiceImpl.java │ └── order/ │ ├── OrderService.java │ └── impl/OrderServiceImpl.java ├── mapper/ │ ├── UserMapper.java │ └── OrderMapper.java ├── entity/ │ ├── User.java │ └── Order.java ├── dto/ │ ├── request/ │ │ ├── UserLoginDTO.java │ │ └── OrderCreateDTO.java │ └── response/ │ ├── UserVO.java │ └── OrderVO.java └── utils/ ├── RegexUtils.java └── SecurityUtils.java項(xiàng)目規(guī)范化不是一蹴而就的是在開(kāi)發(fā)過(guò)程中逐步沉淀的。前期花時(shí)間搭好骨架后期團(tuán)隊(duì)所有人都能受益——寫(xiě)代碼時(shí)有章可循改代碼時(shí)有跡可循這才是規(guī)范化的真正價(jià)值。