項目規范化工具類、封裝、代碼生成一個人寫項目像寫日記——自己能看懂就行團隊協作像寫公文——格式不統一就亂套。項目規范化不是為了好看是為了讓你三個月后回來還能看懂自己寫的什么。一、項目規范化的意義可維護性代碼結構清晰定位問題快修改影響范圍可控團隊協作效率新人接手項目不需要猜約定看目錄結構就知道代碼在哪減少低級錯誤統一封裝減少重復代碼魔法值用枚舉代替減少手寫出錯代碼審查效率規范統一的代碼風格Review時聚焦業務邏輯而非格式問題規范化不是寫一堆文檔約束人而是通過工程手段讓規范自動落地。二、項目分層規范經典的三層架構分層每層職責明確src/main/java/com/example/ ├── controller/ # 控制層接收請求、參數校驗、返回結果 ├── service/ # 業務層業務邏輯編排 │ └── impl/ ├── mapper/ # 持久層數據庫操作MyBatis接口 ├── entity/ # 實體類與數據庫表對應 ├── dto/ # 數據傳輸對象接口入參出參 │ ├── request/ # 請求DTO │ └── response/ # 響應DTO ├── vo/ # 視圖對象返回給前端的對象 ├── utils/ # 工具類 ├── config/ # 配置類 ├── exception/ # 自定義異常 ├── enums/ # 枚舉類 └── constant/ # 常量類分層依賴方向Controller → Service → Mapper禁止跨層調用Controller不能直接調Mapper禁止反向依賴Entity不能依賴DTO。三、命名規范類型規范示例類名大駝峰UserController, OrderService方法名小駝峰getUserById, createOrder變量名小駝峰userName, orderList常量名全大寫下劃線MAX_RETRY_COUNT, DEFAULT_PAGE_SIZE包名全小寫com.example.controller數據庫表名小寫下劃線t_user, t_order_detail接口名不加I前綴UserService非IUserService實現類名接口名ImplUserServiceImpl四、統一返回封裝所有接口返回統一結構前端只需按固定格式解析。4.1 Result封裝DataSchema(description統一返回結構)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 分頁結果封裝DataAllArgsConstructorpublicclassPageResultT{privateListTlist;// 數據列表privateLongtotal;// 總記錄數privateIntegerpageNum;// 當前頁碼privateIntegerpageSize;// 每頁條數privateIntegertotalPages;// 總頁數publicstaticTPageResultTof(ListTlist,Longtotal,IntegerpageNum,IntegerpageSize){inttotalPages(int)Math.ceil((double)total/pageSize);returnnewPageResult(list,total,pageNum,pageSize,totalPages);}}五、基礎實體封裝數據庫表通常都有公共字段創建時間、更新時間等抽取BaseEntity避免每個實體重復定義。DatapublicclassBaseEntity{TableId(typeIdType.ASSIGN_ID)// 雪花算法生成IDprivateLongid;TableField(fillFieldFill.INSERT)// 插入時自動填充privateLocalDateTimecreateTime;TableField(fillFieldFill.INSERT_UPDATE)// 插入和更新時自動填充privateLocalDateTimeupdateTime;TableField(fillFieldFill.INSERT)privateLongcreateBy;TableField(fillFieldFill.INSERT_UPDATE)privateLongupdateBy;TableLogic// 邏輯刪除標記TableField(fillFieldFill.INSERT)privateIntegerdeleted;}MyBatis-Plus自動填充處理器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);// 當前登錄用戶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());}}實體類繼承BaseEntity即可自動獲得這些公共字段DataEqualsAndHashCode(callSupertrue)TableName(t_user)publicclassUserextendsBaseEntity{privateStringusername;privateStringpassword;privateStringemail;privateIntegerstatus;}六、枚舉規范代碼里到處寫012這種魔法值過兩個月誰也不記得1是啟用還是禁用。用枚舉替代。GetterAllArgsConstructorpublicenumUserStatusEnum{DISABLED(0,禁用),ENABLED(1,啟用),LOCKED(2,鎖定);privatefinalIntegercode;privatefinalStringdesc;publicstaticUserStatusEnumgetByCode(Integercode){for(UserStatusEnume:values()){if(e.getCode().equals(code)){returne;}}thrownewIllegalArgumentException(無效的狀態碼: code);}}// 反面教材魔法值if(user.getStatus()1){...}// 正面示范枚舉if(UserStatusEnum.ENABLED.getCode().equals(user.getStatus())){...}常用枚舉場景狀態碼、性別、訂單狀態、支付方式、用戶角色等。七、工具類封裝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工具庫推薦自己寫工具類容易遺漏邊界場景推薦使用Hutool——國內最流行的Java工具庫500工具方法覆蓋絕大多數場景。dependencygroupIdcn.hutool/groupIdartifactIdhutool-all/artifactIdversion5.8.25/version/dependency// 字符串工具StrUtil.isBlank(str);// 判空StrUtil.format(用戶{}已存在,name);// 格式化// 日期工具DateUtil.now();// 當前時間字符串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一個庫頂你自己寫幾十個工具類而且經過大量生產驗證比手寫更可靠。八、代碼生成MyBatisX手動寫Entity/Mapper/Service/Controller四件套既枯燥又容易出錯。MyBatisX是IDEA插件連接數據庫后一鍵生成整套代碼。使用流程IDEA安裝MyBatisX插件連接數據庫Database面板右鍵表 → MyBatisX-Generator配置生成選項module選擇當前項目模塊packagecom.exampleentity勾選繼承BaseEntitymapper勾選生成Mapper接口service勾選生成Service接口Implcontroller勾選生成基礎CRUD接口點擊Generate一鍵生成生成后只需補充業務邏輯省去80%的重復勞動。九、代碼規范檢查阿里巴巴Java開發規約插件IDEA安裝Alibaba Java Coding Guidelines插件編碼時實時檢查規范問題命名不規范空指針風險線程安全問題魔法值未提取常量集合未指定初始容量!-- Checkstyle靜態檢查CI集成 --plugingroupIdorg.apache.maven.plugins/groupIdartifactIdmaven-checkstyle-plugin/artifactIdversion3.3.0/versionconfigurationconfigLocationcheckstyle-alibaba.xml/configLocation/configuration/plugin十、完整規范化項目結構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項目規范化不是一蹴而就的是在開發過程中逐步沉淀的。前期花時間搭好骨架后期團隊所有人都能受益——寫代碼時有章可循改代碼時有跡可循這才是規范化的真正價值。 項目規范化：工具類、封裝、代碼生成
項目規范化工具類、封裝、代碼生成一個人寫項目像寫日記——自己能看懂就行團隊協作像寫公文——格式不統一就亂套。項目規范化不是為了好看是為了讓你三個月后回來還能看懂自己寫的什么。一、項目規范化的意義可維護性代碼結構清晰定位問題快修改影響范圍可控團隊協作效率新人接手項目不需要猜約定看目錄結構就知道代碼在哪減少低級錯誤統一封裝減少重復代碼魔法值用枚舉代替減少手寫出錯代碼審查效率規范統一的代碼風格Review時聚焦業務邏輯而非格式問題規范化不是寫一堆文檔約束人而是通過工程手段讓規范自動落地。二、項目分層規范經典的三層架構分層每層職責明確src/main/java/com/example/ ├── controller/ # 控制層接收請求、參數校驗、返回結果 ├── service/ # 業務層業務邏輯編排 │ └── impl/ ├── mapper/ # 持久層數據庫操作MyBatis接口 ├── entity/ # 實體類與數據庫表對應 ├── dto/ # 數據傳輸對象接口入參出參 │ ├── request/ # 請求DTO │ └── response/ # 響應DTO ├── vo/ # 視圖對象返回給前端的對象 ├── utils/ # 工具類 ├── config/ # 配置類 ├── exception/ # 自定義異常 ├── enums/ # 枚舉類 └── constant/ # 常量類分層依賴方向Controller → Service → Mapper禁止跨層調用Controller不能直接調Mapper禁止反向依賴Entity不能依賴DTO。三、命名規范類型規范示例類名大駝峰UserController, OrderService方法名小駝峰getUserById, createOrder變量名小駝峰userName, orderList常量名全大寫下劃線MAX_RETRY_COUNT, DEFAULT_PAGE_SIZE包名全小寫com.example.controller數據庫表名小寫下劃線t_user, t_order_detail接口名不加I前綴UserService非IUserService實現類名接口名ImplUserServiceImpl四、統一返回封裝所有接口返回統一結構前端只需按固定格式解析。4.1 Result封裝DataSchema(description統一返回結構)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 分頁結果封裝DataAllArgsConstructorpublicclassPageResultT{privateListTlist;// 數據列表privateLongtotal;// 總記錄數privateIntegerpageNum;// 當前頁碼privateIntegerpageSize;// 每頁條數privateIntegertotalPages;// 總頁數publicstaticTPageResultTof(ListTlist,Longtotal,IntegerpageNum,IntegerpageSize){inttotalPages(int)Math.ceil((double)total/pageSize);returnnewPageResult(list,total,pageNum,pageSize,totalPages);}}五、基礎實體封裝數據庫表通常都有公共字段創建時間、更新時間等抽取BaseEntity避免每個實體重復定義。DatapublicclassBaseEntity{TableId(typeIdType.ASSIGN_ID)// 雪花算法生成IDprivateLongid;TableField(fillFieldFill.INSERT)// 插入時自動填充privateLocalDateTimecreateTime;TableField(fillFieldFill.INSERT_UPDATE)// 插入和更新時自動填充privateLocalDateTimeupdateTime;TableField(fillFieldFill.INSERT)privateLongcreateBy;TableField(fillFieldFill.INSERT_UPDATE)privateLongupdateBy;TableLogic// 邏輯刪除標記TableField(fillFieldFill.INSERT)privateIntegerdeleted;}MyBatis-Plus自動填充處理器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);// 當前登錄用戶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());}}實體類繼承BaseEntity即可自動獲得這些公共字段DataEqualsAndHashCode(callSupertrue)TableName(t_user)publicclassUserextendsBaseEntity{privateStringusername;privateStringpassword;privateStringemail;privateIntegerstatus;}六、枚舉規范代碼里到處寫012這種魔法值過兩個月誰也不記得1是啟用還是禁用。用枚舉替代。GetterAllArgsConstructorpublicenumUserStatusEnum{DISABLED(0,禁用),ENABLED(1,啟用),LOCKED(2,鎖定);privatefinalIntegercode;privatefinalStringdesc;publicstaticUserStatusEnumgetByCode(Integercode){for(UserStatusEnume:values()){if(e.getCode().equals(code)){returne;}}thrownewIllegalArgumentException(無效的狀態碼: code);}}// 反面教材魔法值if(user.getStatus()1){...}// 正面示范枚舉if(UserStatusEnum.ENABLED.getCode().equals(user.getStatus())){...}常用枚舉場景狀態碼、性別、訂單狀態、支付方式、用戶角色等。七、工具類封裝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工具庫推薦自己寫工具類容易遺漏邊界場景推薦使用Hutool——國內最流行的Java工具庫500工具方法覆蓋絕大多數場景。dependencygroupIdcn.hutool/groupIdartifactIdhutool-all/artifactIdversion5.8.25/version/dependency// 字符串工具StrUtil.isBlank(str);// 判空StrUtil.format(用戶{}已存在,name);// 格式化// 日期工具DateUtil.now();// 當前時間字符串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一個庫頂你自己寫幾十個工具類而且經過大量生產驗證比手寫更可靠。八、代碼生成MyBatisX手動寫Entity/Mapper/Service/Controller四件套既枯燥又容易出錯。MyBatisX是IDEA插件連接數據庫后一鍵生成整套代碼。使用流程IDEA安裝MyBatisX插件連接數據庫Database面板右鍵表 → MyBatisX-Generator配置生成選項module選擇當前項目模塊packagecom.exampleentity勾選繼承BaseEntitymapper勾選生成Mapper接口service勾選生成Service接口Implcontroller勾選生成基礎CRUD接口點擊Generate一鍵生成生成后只需補充業務邏輯省去80%的重復勞動。九、代碼規范檢查阿里巴巴Java開發規約插件IDEA安裝Alibaba Java Coding Guidelines插件編碼時實時檢查規范問題命名不規范空指針風險線程安全問題魔法值未提取常量集合未指定初始容量!-- Checkstyle靜態檢查CI集成 --plugingroupIdorg.apache.maven.plugins/groupIdartifactIdmaven-checkstyle-plugin/artifactIdversion3.3.0/versionconfigurationconfigLocationcheckstyle-alibaba.xml/configLocation/configuration/plugin十、完整規范化項目結構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項目規范化不是一蹴而就的是在開發過程中逐步沉淀的。前期花時間搭好骨架后期團隊所有人都能受益——寫代碼時有章可循改代碼時有跡可循這才是規范化的真正價值。