Java后端开发规范

        在Java后端开发中，遵循一套明确的规范和最佳实践是非常重要的，这不仅可以提高代码的质量和可维护性，还可以促进团队协作和项目的长期发展。因此，对于有志于学习 Java 语言的朋友而言，从学习初期便着力培养良好的代码编写习惯，是通往成功掌握这门语言的关键一步。

一、开发环境

        1.Java8

        2.IntelliJ IDEA

二、Java命名

        1.maven模块名小写，多个单词使用-连接。

              正确: example-moudle
              错误: exampleMoudle

        2.包名全部小写，多个单词使用多个目录层级。

              正确: org.example.pro.service.manage
              错误: org.example.pro.serviceManage

        3.类名首字母大写,使用驼峰命名,类名通常为名词,要见名知义。

              正确: serviceManage
              错误: servicemanage,Servicemanage,Service_Manage

        4.方法名首字母小写，使用驼峰命名。名称要见名知义

              正确: findById(String id), BatchDeleteServiceApply(List serviceApplyIdList)
              错误: getData(String arg)

        5.局部变量首字母小写，使用驼峰命名。名称要见名知义。

              正确: String serviceId = service.getId();

              错误: String str = service.getId();

        6.常量使用大写，多个单词使用_连接

              正确: static String DEFAULT_CONFIG = "1";
              错误: static String DEFAULTCONFIG = "1";

三、Restful 接口命名

URL使用小写，多个单词使用-或者/连接。

        如：sevice-apply、system/log。

通常情况下应该使用URL(统一资源定位符)来描述资源，使用HTTP Method(GET-查询,POST-新增,PUT-修改,PATCH-修改不存在则新增,DELETE-删除)来描述对资源的操作。

在一些特殊操作无法使用HTTP Method来描述操作的时候，使用_开头加动词来描述。如:service/_query。

可以使用注解体现Restful风格的接口

操作	描述	注解
查询	GET	@GetMapping
新增	POST	@PostMapping
修改	PUT	@PutMapping
修改不存在则新增	PATCH	@PatchMapping
删除	DELETE	@DeleteMapping

四、注释

注释的作用主要有：

• 提高代码可读性：帮助开发者快速理解代码逻辑、变量用途、函数功能等，尤其在复杂代码中。
• 方便代码维护：让后续维护者能轻松读懂代码意图，减少修改代码时出错概率。
• 促进团队协作：使团队成员能高效理解彼此代码，提高沟通和协作效率。
• 辅助代码调试：注释可暂时屏蔽部分代码，便于定位问题。

1. 类注释，遵循java doc规范。

主要由: @author (作者) 、@since (在什么版本添加的) 、 @see (和当前类有关的其他类) 以及对类的描述组成

/**
* 服务申请,用于封装服务申请的信息,如 申请时间,申请人,报名信息等.
* @author 糖心何包蛋爱编程
* @since  2.1
* @see ApplyEntity
* @see ServiceApply#of(ServiceApply)
*/
public class ServiceApply{
    
}

2.方法注释, 遵循java doc规范。注释应当描述方法的作用以及对应的示例

/**
 * 用户注册方法。
 * 
 * @param username 用户的用户名，不能为 null 或空字符串。
 * @param password 用户的密码，不能为 null 或空字符串。
 * @return 注册成功返回 true，失败返回 false。
 * @throws IllegalArgumentException 如果用户名或密码为空，抛出此异常。
 */
public boolean registerUser(String username, String password) throws IllegalArgumentException {
    // 方法的具体实现
}

3.行注释：行注释用于解释代码中某一行或一小段代码的作用，通常放在代码行的上方或右侧。

// 计算两个数的和
int sum = a + b;

int result = calculateResult(); // 调用 calculateResult 方法获取计算结果

⚠️注意 ⚠️注意 ⚠️注意

请使用javadoc内置的tag如：@author,@since,@see,@link,@param,@return等。不要添加无关tag。

五、编码风格

建议使用文章顶部展示Idea缩进和配色配置

1.响应式编程中，避免在lambda表达式中编写复杂逻辑。应该将逻辑抽离到单独的方法。

错误示例
return productPropertyMono
        .map(prop->{
            Map map = new HashMap<>();
            map.put("property",prop.getProperty());
            ....
            return map;
        })
        .flatMap(this::doSomeThing)


正确示例
//在ProductProperty中编写toMap方法实现上面lambda中到逻辑.
return productPropertyMono
        .map(ProductProperty::toMap)
        .flatMap(this::doSomeThing)

2.链式调用逢“.”换行

错误示例
return activityApplyService.createQuery().where(ActivityApplyEntity::getId,activictyApplyId).fetch().map(DeviceEntity::toDeviceInfo);

正确示例
return activityApplyService                        
    .createQuery()
    .where(ActivityApplyEntity::getId,activictyApplyId)
    .fetch()
    .map(DeviceEntity::toDeviceInfo);

3.集合类应当预分配容量

List serviceIdList = 
    new ArrayList<>(serviceList.size());

Map serviceMapping = 
    Maps.newHashMapWithExpectedSize(serviceList.size());

六、Spring Bean注入

1.禁止使用@Autowire注入，应当使用构造方法注入。便于后续单元测试。

错误示例

@Service
public class ProductService{

 @Autowire   
 private ReactiveRepository repository;

}


正确示例

@Service
public class ProductService{
    
    private final ReactiveRepository repository;
    
    public ProductService(ReactiveRepository repository){
        this.repository=repository;
    }
}

//或者使用lombok注解

@Service
@RequiredArgsConstructor
public class ProductService{
    
  private final ReactiveRepository repository;
  
}

2.禁止使用@Value获取配置信息，应当单独定义配置类使用@ConfigurationProperties来处理。

错误示例
@Service
public class ProductService{
  @Value("product.name")
  private String name;

  @Value("product.category")
  private String category;
}

正确示例
@ConfigurationProperties(prefix="product")
@Getter
@Setter
public class ProductProperty{
    
    private String name;
    
    private String category;
    
}

@Service
@RequiredArgsConstructor
public class ProductService{
   
  private final ProductProperty property;
    
}

七、Maven

1.引入同一个项目的子模块时, 禁止使用固定的版本号。

错误示例

  org.example.pro
  test-manager
  1.0.0


正确示例

    org.example.pro
    test-manager
    ${project.version}

2.引入外部依赖时，应当在父模块的 dependencyManagement 中统一定义版本，并在子模块中不指定版本号。

错误示例


  org.example.pro
  test-manager
  1.0.0



正确示例


 
    1.0.0
 


  
      org.example.pro
      test-manager
      ${project.version}
  




  org.example.pro
  test-manager

八、日志

日志框架统一使用slf4j。

//错误示例
log.debug("收到数据:"+data); 

//正确示例
log.debug("收到数据: {}",data);

//更好的示例
if(log.isDebugEnabled()){ //只要涉及到调用变量方法的时候,应该加上此判断
  //需要描述清楚 行为,结果,关联信息等
  log.debug("MQTT网关{},收到客户端[{}]数据:{}",gatewayId,client.ip(),data);
}

什么问题都可以评论区留言，看见都会回复的

如果你觉得本篇文章对你有所帮助的，把“文章有帮助的”打在评论区

多多支持吧！！！

点赞加藏评论，是对小编莫大的肯定。抱拳了！