项目规范化工具类、封装、代码生成一个人写项目像写日记——自己能看懂就行团队协作像写公文——格式不统一就乱套。项目规范化不是为了好看是为了让你三个月后回来还能看懂自己写的什么。一、项目规范化的意义可维护性代码结构清晰定位问题快修改影响范围可控团队协作效率新人接手项目不需要猜约定看目录结构就知道代码在哪减少低级错误统一封装减少重复代码魔法值用枚举代替减少手写出错代码审查效率规范统一的代码风格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项目规范化不是一蹴而就的是在开发过程中逐步沉淀的。前期花时间搭好骨架后期团队所有人都能受益——写代码时有章可循改代码时有迹可循这才是规范化的真正价值。
