Java后端开发常用规范

忘是亡心i 2023-09-29 16:49 17阅读 0赞

原文网址：[Java后端开发常用规范\_IT利刃出鞘的博客-CSDN博客][Java_IT_-CSDN]

## 简介 ##

本文介绍Java后端开发的一些规范。持续更新。

本规范是本人在实践中总结出来的，可提高项目的可维护性、提高扩展性、提高开发速度。本文可以解决项目中效率低下、难以维护、让人心累的痛点等问题。

本文所有的规范，全都不是一拍脑袋就写出来的，全都是经过了如下步骤：

1.  经历了错误做法带来的问题
2.  在项目中使用过本文的正确做法（解决了错误做法的问题）
3.  查询过网上各种观点的信息
4.  经过自己的多重考虑

本文的规范，有的你也许不知道是好还是不好，我可以这么说：刚开始我同事也是不知道好还是不好，用了之后跟我说：真香！

比如：我刚入门Java时觉得controller、service、mapper、entity这几个大包比较好，后来是我一个技术很强的组长率先使用了新方式：每个表一个包，里边进行拆分。用了之后，一周以内我就发现了它的好处。

题外话：如果一个人技术很强（比如写过开源项目、是CSDN博客专家等），那么你如果和他有不一样的见解，可以先假设他是对的，然后再进行尝试与验证，这样你才能进步。不要直接去否定技术大牛，除非你达到或者超越了人家。

## 项目的版本指定 ##

版本号必须是-SNAPSHOT结尾。（版本号也就是pom.xml的version标签）。

因为业务代码更新会很频繁，使用-SNAPSHOT结尾可以保证每次从maven私库去拉新代码。

**不用-SNAPSHOT结尾的缺点**

如果不使用-SNAPSHOT结尾，会导致先从maven本地去取，若更新了代码，很难去更新本地依赖。虽然可以将maven设置为每次都从私库更新，但是这会导致所有依赖都从私库去拉，构建会很慢！

也许你想到了一个保证拉取最新代码的方法：每次改动代码都去修改版本号。虽然可行，但业务代码的改动会很频繁，这会导致版本超级多！这种方法只适用于开源项目或者变动不频繁的项目。

## 项目的模块划分 ##

**模块的划分**

单个项目分为：xxx-api模块、xxx-core模块，加一个pom.xml。比如订单项目，分为：order-api模块、order-core模块、pom.xml。

*  **xxx-api**：用于让其他项目使用（引入依赖）。包括：bo、vo、本项目的feign定义。
    
     *  xxx-api放的应该是本项目供其他项目调用的feign。想调本项目的其他项目直接引入这个xxx-api即可。如果自己想用feign调用其他项目，让其他项目把feign放到他们自己的yyy-api中。
        
         *  这种方式与dubbo的写法类似，符合rpc方法暴露和调用流程。
 *  **xxx-core**：主体项目。包括：业务（Controller、Service、Mapper、Entity）、配置类等。
 *  **pom.xml**：作为这个业务项目的父依赖，里边包含公共依赖等。

示意图：

![3222554588b54dcb82c14f5365f60d2f.png][]

**顶层pom.xml示例：**

上边parent标签的内容是公共项目里的，这个公共项目包含：核心组件、引入公共依赖，将spring-boot-starter-parent作为parent标签内容。common-parent的作用是：作为common项目的顶级项目，并给各个业务做parent。

**order-api的pom.xml**

上边parent标签的内容是公共项目里的，common-dep-api的作用是：作为各个业务的api的parent，里边有公共依赖等。

**order-core的pom.xml**

<?xml version="1.0" encoding="UTF-8"?>
    <project xmlns="http://maven.apache.org/POM/4.0.0"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
        <modelVersion>4.0.0</modelVersion>
    
        <parent>
            <groupId>com.knife.example</groupId>
            <artifactId>common-dep-core</artifactId>
            <version>0.0.1-SNAPSHOT</version>
            <relativePath>../pom.xml</relativePath>
        </parent>
    
        <artifactId>order-core</artifactId>
        <version>0.0.1-SNAPSHOT</version>
    
        <name>order-core</name>
        <packaging>jar</packaging>
        <description>Demo project for Spring Boot</description>
    
        <dependencies>
    
        </dependencies>
    
        <build>
            <plugins>
                <plugin>
                    <groupId>org.springframework.boot</groupId>
                    <artifactId>spring-boot-maven-plugin</artifactId>
                </plugin>
            </plugins>
    
            <resources>
                
                <resource>
                    <directory>src/main/resources</directory>
                    <excludes>
                        <exclude>application*.yml</exclude>
                    </excludes>
                    
                    <filtering>true</filtering>
                </resource>
    
                
                <resource>
                    <directory>src/main/resources</directory>
                    <includes>
                        <include>application.yml</include>
                        <include>application-${profileActive}.yml</include>
                        
                    </includes>
                    
                    <filtering>true</filtering>
                </resource>
            </resources>
        </build>
    
    </project>

上边parent标签的内容是公共项目里的，common-dep-core的作用是：作为各个业务的core的parent，里边有公共依赖等。

## **业务代码的结构** ##

1.  每个表对应一个包，里边是包含的包有：controller、service、mapper、entity等
2.  添加一个facade包（Controller调用Facade，Facade调用Service或Mapper）
    
    1.  使用MyBatis-Plus后，应该将Service和Mapper看为**同一级别**，都**作为数据访问层**，新建facade包作为业务层，这样业务多了可以在facade层拆分。

例如：

![c4cfaaba970541de8583bcb4e28847c5.png][]

**优点**

1.  模块化，业务分离清晰
2.  开发速度快（只需关注自己模块代码即可）

**思考**

有其他的划分方式是：xxx-api、xxx-common、xxx-entity、xxx-service、xxx-web。个人感觉这样的划分很差。它的缺点是：

1.  不符合业务模块化思想，后期很难拆分或合并项目
2.  开发速度慢（同一个业务的Entity、Service、Controller被拆开了，写的时候看代码要吐血）

**表名对应包下的包的命名规范**

1.  controller：Controller集合
2.  facade：调用Service的逻辑集合，要包含接口和实现类，实现类用@Component注入
3.  service：MyBatis-Plus的Service，里边不要写任何代码，只用于被facade调用。
4.  mapper：MyBatis-Plus的Mapper，被service调用。如果要写SQL，facade直接去调即可。
5.  entity：MyBatis-Plus的DAO（数据库对象）。
6.  bo：入参实体类
7.  vo：返回值实体类
8.  constant：常量。比如：枚举类、Interface常量类
9.  helper：业务工具，比如：组装实体类的字段
10. schedule：定时任务，比如：xxl-job的定时任务
11. mq：mq消费者
12. strategy：策略模式（假如用到策略模式的话）。其他设计模式也一样，单独写一个包，以设计模式的名字命名。

**备注**

本处说业务项目要分为api和core，不是所有项目。一个项目一般要这么分：

1.  一个common项目
    
    1.  可分为：
        
        1.  common-parent：父项目（指定SpringBoot为父项目）
        2.  common-dep-api：业务api层的依赖
        3.  common-dep-core：业务core层的依赖
        4.  common-core：业务的公共配置、工具类、全局处理等。
2.  多个业务应用项目
    
    1.  分为api和core

## 单个模块的包的划分 ##

**包结构的整体改造**

因为Mybatis-Plus的service有大量自带的逻辑，为了与业务逻辑区分，将它看成是数据交互层（与Mapper同一层次）。

对原来的controller=> service=> mapper结构进行改造，改为：controller=> facade=> service=> mapper

所以，**不要在service里写任何业务逻辑**，只能写与数据交互的逻辑。所有的业务逻辑写到facade中，facade内部分成抽象层和实现层。如果业务太多，就在facade里拆成多个。

**包名规定**

划分为如下几个包：

1.  controller
    
    1.  接口，不要写任何业务代码，必须直接用一行代码去调用facade。
2.  facade
    
    1.  所有业务代码写到这里，读写数据库时去调用service或者mapper
    2.  要写接口和实现类，实现类用@Component注入
3.  service
    
    1.  只存放Mybatis-Plus的service，不写任何业务代码。
4.  mapper：
    
    1.  MyBatis-Plus的Mapper。如果要写SQL，facade直接调，不要用service调mapper。
5.  entity
    
    1.  存放数据库表对应的实体类
6.  bo
    
    1.  方法的入参。所有的实体类名都以BO结尾，比如：UserBO。
7.  vo
    
    1.  方法的返回值。所有的实体类名都以VO结尾，比如：UserVO。
8.  dto
    
    1.  内部使用的实体类。（尽量不要使用此命名，因为分不清是入参还是返回值，不清晰）
    2.  所有的实体类名都以DTO结尾。
9.  constant
    
    1.  常量。比如：枚举类、Interface常量类。
10. helper
    
    1.  业务工具，比如：组装实体类的字段。工具类以Helper结尾，比如：UserHelper。
    2.  不用写接口和实现类，直接写实现类即可，若需要注册为Bean，用@Component。
11. schedule
    
    1.  定时任务，比如：xxl-job的定时任务。类名都以Schedule结尾，比如：UserSchedule。
12. mqConsumer
    
    1.  mq消费者。类名都以MqConsumer结尾，比如：UserMqConsumer。
13. strategy
    
    1.  策略模式（假如用到策略模式的话）。
    2.  其他设计模式也一样，单独写一个包，以设计模式的名字命名。

## 使用枚举（不要用数字） ##

**说明**

要用枚举来表示类型，不要用数字。比如：有三种支付方式：微信、支付宝、银行卡，则这样定义枚举：

package com.example.pay;
     
    public enum PayType {
        ALIPAY("支付宝支付"),
        WECHAT_PAY("微信支付"),
        BANK_CARD_PAY("银行卡支付")
        ;
     
        /**
         * 描述
         */
        private final String description;
     
        PayType(String description) {
            this.description = description;
        }
     
        public String getDescription() {
            return description;
        }
    }

所有用到的地方都用枚举来表示。比如：

1.  Controller：会自动将前端传过来的字符串转为枚举类（根据name()来转换）。
2.  Entity：写数据：自动将枚举对象的name()值写入数据库；读数据：根据name()转为枚举

详细用法见：[SpringBoot--在Entity(DAO)中使用枚举类型\_IT利刃出鞘的博客-CSDN博客][SpringBoot--_Entity_DAO_IT_-CSDN]

**优点**

可读性好

**不要用数字表示类型**

1：支付宝支付；2：微信支付；3：银行卡支付

原因：可读性极差，排查问题也麻烦。比如：前端页面上看到了2这个类型，还要看接口文档或者问后端这是什么意思，浪费时间！

## 接口文档 ##

**说明**

使用[Knife4j][]\+[Apixfox][]（推荐）。（不推荐Knife4j+Yapi，因为同步接口时有些麻烦。）

用法1：项目起来后，通过knife4j的“分组Url”去导入到Apifox。

用法2：使用Idea的Apifox Helper插件将Knife4j的数据同步到Apifox。

**Knife4j**

Knife4j的用法见[这里][Knife4j]。例如：

![d8143278652b4644b105ca9897c3e665.png][]

**优点**

1.  减少接口文档的代码冗余
2.  可快速导入接口

## git提交规范 ##

下边的git提交流程与规范是宝贵经验，它能解决如下问题：

1.  分支差距过大，导致合代码**无数的冲突**
2.  合完代码后发现**代码丢失**
3.  分支不清晰，**无法追溯问题**
4.  合代码耗时很长，占用大量时间。

上边是本文的部分内容，为便于维护，全文已转移到此网址：[Java后端开发常用规范 - 自学精灵][Java_ -]

[Java_IT_-CSDN]: https://knife.blog.csdn.net/article/details/125987061
[3222554588b54dcb82c14f5365f60d2f.png]: https://img-blog.csdnimg.cn/3222554588b54dcb82c14f5365f60d2f.png
[c4cfaaba970541de8583bcb4e28847c5.png]: https://img-blog.csdnimg.cn/c4cfaaba970541de8583bcb4e28847c5.png
[SpringBoot--_Entity_DAO_IT_-CSDN]: https://knife.blog.csdn.net/article/details/126775705
[Knife4j]: https://knife.blog.csdn.net/article/details/120753090
[Apixfox]: https://knife.blog.csdn.net/article/details/124058101
[d8143278652b4644b105ca9897c3e665.png]: https://img-blog.csdnimg.cn/d8143278652b4644b105ca9897c3e665.png
[Java_ -]: https://learn.skyofit.com/?p=1776