【架构】-----Service 层代码太长太乱？试试这套 “见名知意” 的命名规范！

前言java服务层业务比较复杂导致单个函数行数太多可读性极低怎么解决让函数名本身就清晰告知开发者它的类型、职责、适用场景。以下是可落地的、行业通用的命名规范体系兼顾简洁性和辨识度一、核心命名原则不分类前提下前缀区分类型用固定前缀标识函数类型是最直观的方式优先级高于其他命名规则。动词名词体现职责前缀后紧跟核心动作业务对象明确函数做什么、针对什么业务。统一后缀/修饰符对特殊场景如共用、辅助增加后缀避免歧义。拒绝模糊词汇禁用“doSomething”“handleData”“processInfo”等无意义命名。二、分类型命名规范无物理分类以下是针对不同函数类型的具体命名规则附示例以订单业务为例函数类型命名规则前缀/后缀示例订单业务说明入口函数核心动词 业务对象无特殊前缀无核心动词开头createOrder(OrderDTO dto)queryOrderById(Long id)cancelOrder(String orderNo)入口函数是控制层直接调用的核心函数无特殊前缀用最简洁的核心动词体现业务动作是命名体系的“基础层”。校验函数validate 校验维度 业务对象前缀validatevalidateOrderParam(OrderDTO dto)validateOrderStatus(String orderNo)validateOrderAmount(BigDecimal amount)前缀固定为validate后接“校验维度”参数/状态/金额 业务对象明确校验的具体内容。共用函数核心功能 业务对象 Common后缀后缀CommonformatOrderNoCommon(String no)calculateTaxCommon(BigDecimal amount)convertDateCommon(Date date)后缀固定为Common标识是跨场景共用的通用逻辑无业务上下文依赖可在多个入口函数中复用。辅助函数辅助动作 目标对象 For 场景可选前缀build/parse/assemblebuildOrderDTOForDetail(OrderDO order)parseOrderGoodsFromJson(String json)assembleOrderCondition(OrderQueryDTO query)前缀用build组装、parse解析、assemble拼装等后缀可加For场景如ForDetail/ForList明确辅助的具体场景。抽取函数do 具体操作 业务对象前缀dodoCalculateOrderAmount(OrderDTO dto)doGenerateOrderNo()doUpdateOrderStatus(String orderNo, Integer status)前缀固定为do标识是从复杂业务中拆分的“子逻辑”仅被本类其他函数调用通常设为private不对外暴露。复杂业务函数process 业务场景 业务对象前缀processprocessOrderPay(OrderDTO dto)processOrderRefund(String orderNo, BigDecimal refundAmount)processOrderTimeout(String orderNo)前缀固定为process标识处理核心/复杂业务规则可调用do开头的抽取函数是入口函数的“业务实现层”。三、完整代码示例无物理分类以下是一个不做分类的OrderService示例仅通过命名区分所有函数类型保持代码内聚且可读性强/** * 订单服务无物理分类仅通过命名区分函数类型 * 核心规则入口函数无特殊前缀其他函数通过前缀/后缀标识类型 */ServicepublicclassOrderService{AutowiredprivateOrderMapperorderMapper;// ---------------------- 入口函数控制层直接调用无特殊前缀 ----------------------publicOrderDTOcreateOrder(OrderDTOdto){// 1. 调用校验函数validateOrderParam(dto);// 2. 调用复杂业务函数OrderDOorderDOprocessOrderCreate(dto);// 3. 调用辅助函数OrderDTOresultbuildOrderDTOForDetail(orderDO);returnresult;}publicOrderDTOqueryOrderById(Longid){OrderDOorderDOorderMapper.selectById(id);returnbuildOrderDTOForDetail(orderDO);}// ---------------------- 校验函数前缀validate ----------------------publicvoidvalidateOrderParam(OrderDTOdto){if(dtonull){thrownewBusinessException(PARAM_NULL,订单参数不能为空);}if(StringUtils.isBlank(dto.getOrderNo())){thrownewBusinessException(PARAM_ERROR,订单号不能为空);}}privatevoidvalidateOrderStatus(StringorderNo){OrderDOorderDOorderMapper.selectByOrderNo(orderNo);if(orderDO.getStatus()!0){thrownewBusinessException(STATUS_ERROR,订单非待支付状态无法操作);}}// ---------------------- 复杂业务函数前缀process ----------------------privateOrderDOprocessOrderCreate(OrderDTOdto){// 调用抽取函数BigDecimalamountdoCalculateOrderAmount(dto);StringorderNodoGenerateOrderNo();OrderDOorderDOnewOrderDO();orderDO.setOrderNo(orderNo);orderDO.setAmount(amount);orderDO.setCreateTime(newDate());orderMapper.insert(orderDO);returnorderDO;}// ---------------------- 抽取函数前缀do私有 ----------------------privateBigDecimaldoCalculateOrderAmount(OrderDTOdto){returndto.getGoodsList().stream().map(GoodsDTO::getPrice).reduce(BigDecimal.ZERO,BigDecimal::add);}privateStringdoGenerateOrderNo(){returnORDER_System.currentTimeMillis()RandomUtils.nextInt(1000,9999);}// ---------------------- 辅助函数前缀build/parse ----------------------privateOrderDTObuildOrderDTOForDetail(OrderDOorderDO){OrderDTOdtonewOrderDTO();dto.setOrderNo(orderDO.getOrderNo());dto.setAmount(orderDO.getAmount());// 调用共用函数dto.setCreateTime(formatDateCommon(orderDO.getCreateTime()));returndto;}// ---------------------- 共用函数后缀Common ----------------------privateStringformatDateCommon(Datedate){if(datenull){return;}SimpleDateFormatsdfnewSimpleDateFormat(yyyy-MM-dd HH:mm:ss);returnsdf.format(date);}}四、补充规范无分类场景必加即便仅靠命名区分也需要配套少量规则保证可读性避免命名混乱访问修饰符约束入口函数public对外暴露控制层调用。校验/复杂业务函数public或protected可被同包其他Service复用。抽取/辅助/共用函数private仅本类使用如需跨类复用升级为public并保持命名规则。参数命名约束业务对象参数用业务对象名缩写/全称如OrderDTO dto、Long orderId。基础类型参数加语义前缀如String orderNo而非String no、BigDecimal orderAmount而非BigDecimal amount。注释简化约束因命名已体现类型注释只需说明“业务规则”无需说明“函数类型”。示例/** * 创建订单核心入口 * 业务规则1. 校验参数 2. 计算金额 3. 生成订单号 4. 持久化 * param dto 订单入参 * return 订单详情 */publicOrderDTOcreateOrder(OrderDTOdto){...}五、避坑点无分类命名的关键禁止前缀混用不要把do用在入口函数如doCreateOrder也不要把validate用在业务函数如validateOrderCreate。禁止缩写模糊不要用cOrder代替createOrder不要用vParam代替validateOrderParam缩写仅在团队完全共识的前提下使用如query可简写为qry。禁止函数过长即便命名规范单个函数行数也不能超过50行否则再清晰的命名也无法掩盖逻辑混乱。总结仅靠命名规范区分服务层函数的核心是固定前缀用validate/do/process等前缀标识函数类型入口函数无特殊前缀。语义完整前缀后紧跟“动作业务对象”明确函数职责。特殊后缀用Common标识共用函数用For场景标识辅助函数。修饰符配合通过public/private区分函数是否对外暴露减少调用歧义。这套方案无需拆分类/包适合中小型项目或快速迭代场景既能保证代码可读性新人看函数名就知道类型和用途又能避免过度设计平衡规范和开发效率。