写一个自己的编码风格校验工具

旧城等待， 2024-02-21 11:41 10阅读 0赞

#### 文章目录 ####

*   *  1. 目标
     *  2. 代码实现
     *  3. 结果验证

### 1. 目标 ###

我们知道java编译器把Java程序源码编译成字节码的时候，会对Java程序源码做各方面的检查校验，这些校验主要是以程序“写得对不对”为出发点，但不会校验程序“写得好不好”。有鉴于此，业界出现了许多针对程序“写得好不好”的辅助校验工具，如CheckStyle、FindBug、Klocwork等。这些代码校验工具有一些是基于Java的源码进行校验的，有的是通过扫描字节码来完成的，我们的目标就是实现一款拥有自己编码风格的校验工具：NameCheckProcessor（对Java程序命名进行检查）。程序的命名规则如下：

*  类或接口符合驼峰命名法，首字母大写
 *  方法要符合驼峰命名法，首字母小写
 *  字段
 *   *  类或实例变量，符合驼峰命名法，首字母小写
 *   *  常量。要求全部由大写字母或下划线构成，并且第一个字符不能是下划线

### 2. 代码实现 ###

要通过注解处理器API实现编译器插件，首先需要了解这组API的一些基本信息。

我们实现注解处理器的代码需要继承抽象类`javax.annotation.processing.AbstractProcessor`，这个抽象类只有一个子类必须实现的方法：“process()”，它是Javac编译器在执行注解处理器代码时要调用的过程，我们可以从这个方法的第一个参数“annotations”中获取到此注解处理器所要处理的注解集合，从第二个参数“roundEnv”中访问到当前这个轮次中的抽象语法树节点，每个语法树节点在这里表示为一个Element。在`javax.lang.model.ElementKind`中定义了18类Element，已经包括了Java代码中可能出现的所有元素：

<table> 
 <thead> 
  <tr> 
   <th>元素名称</th> 
   <th>含义</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>PACKAGE</td> 
   <td>包</td> 
  </tr> 
  <tr> 
   <td>ENUM</td> 
   <td>枚举</td> 
  </tr> 
  <tr> 
   <td>CLASS</td> 
   <td>类</td> 
  </tr> 
  <tr> 
   <td>ANNOTATION_TYPE</td> 
   <td>注解</td> 
  </tr> 
  <tr> 
   <td>INTERFACE</td> 
   <td>接口</td> 
  </tr> 
  <tr> 
   <td>ENUM_CONSTANT</td> 
   <td>枚举值</td> 
  </tr> 
  <tr> 
   <td>FIELD</td> 
   <td>字段</td> 
  </tr> 
  <tr> 
   <td>PARAMETER</td> 
   <td>参数</td> 
  </tr> 
  <tr> 
   <td>LOCAL_VARIABLE</td> 
   <td>本地变量</td> 
  </tr> 
  <tr> 
   <td>EXCEPTION_PARAMETER</td> 
   <td>异常</td> 
  </tr> 
  <tr> 
   <td>METHOD</td> 
   <td>方法</td> 
  </tr> 
  <tr> 
   <td>CONSTRUCTOR</td> 
   <td>构造函数</td> 
  </tr> 
  <tr> 
   <td>STATIC_INIT</td> 
   <td>静态代码块</td> 
  </tr> 
  <tr> 
   <td>INSTANCE_INIT</td> 
   <td>实例语句块</td> 
  </tr> 
  <tr> 
   <td>TYPE_PARAMETER</td> 
   <td>参数化类型（范型尖括号中的类型）</td> 
  </tr> 
  <tr> 
   <td>RESOURCE_VARIABLE</td> 
   <td>资源变量(try-resource)中定义的变量</td> 
  </tr> 
  <tr> 
   <td>MODULE</td> 
   <td>模块</td> 
  </tr> 
  <tr> 
   <td>OTHER</td> 
   <td>未定义的其他语法树节点</td> 
  </tr> 
 </tbody> 
</table>

除了process()方法中方法及参数之外，还有一个很重要的实例变量，在注解处理器初始化的时候（init()方法执行的时候）创建，继承了AbstractProcessor的注解处理器代码可以直接访问它。它代表了注解处理器框架提供了一个上下文环境，要创建新的代码，向编译器输出信息、获取其他工具类等都需要用到这个实例变量。

注解处理器除了process()方法及其参数之外，还有两个经常配合着使用的注解，分别是`@SupportedAnnotationTypes`和`@SupportedSourceVersion`，前者代表了这个注解处理器对哪些注解感兴趣，可以使用星号作为通配符表示对所有注解都感兴趣，后者指出类这个注解处理器可以处理哪些版本的Java代码。

每一个注解处理器在运行时都是单例的，如果不需要改变或添加抽象语法树中的内容，process()方法就可以返回一个值为false的布尔值，通知编译器这轮次中的代码未发生变化，无需构造新的Javacompiler实例，在这次实战中的注解处理器中只对程序命名进行检查，不需要改变语法树的结构，所以process()返回值会一直都是false。

*  实现注解处理器NameCheckProcessor

import javax.annotation.processing.*;
    import javax.lang.model.SourceVersion;
    import javax.lang.model.element.Element;
    import javax.lang.model.element.TypeElement;
    import java.util.Set;
    
    //表示可以支持所有的注解
    @SupportedAnnotationTypes("*")
    //表示只支持JDK8的代码
    @SupportedSourceVersion(SourceVersion.RELEASE_8)
    public class NameCheckProcessor extends AbstractProcessor {
        
        private  NameChecker nameChcker;
    
        /**
         * 初始化注解处理器，这里调用了父类AbstractProcessor的init方法，以确保处理器的初始化工作得以完成。
         * @param processingEnv environment to access facilities the tool framework
         * provides to the processor
         */
        @Override
        public void init(ProcessingEnvironment processingEnv){
        
            super.init(processingEnv);
            nameChcker=new NameChecker(processingEnv);
    
        }
        @Override
        public boolean process(Set<? extends TypeElement> annotations, RoundEnvironment roundEnv) {
        
            //这里检查是否编译过程已经结束，如果没有结束，则执行下面的循环。这是为了确保处理发生在编译的合适时机。
            if(!roundEnv.processingOver()){
        
                for(Element element:roundEnv.getRootElements()){
        
                    nameChcker.checkname(element);
                }
            }
            //处理完成后，方法返回false，表示不希望后续的注解处理器再处理这些元素
            return false;
        }
    }

> 从上面代码可以看出NameCheckProcessor能处理基于JDK 8的代码，它不限于特定的注解，对任何代码都感兴趣，而在process()方法中时把当前轮次中的每一个RootElement传递到一个NameChecker检查器中执行名称检查逻辑

*  实现命名检查器NameChecker

import javax.annotation.processing.Messager;
    import javax.annotation.processing.ProcessingEnvironment;
    import javax.lang.model.element.*;
    import javax.lang.model.util.ElementScanner8;
    import java.util.EnumSet;
    import static javax.lang.model.element.ElementKind.*;
    import static javax.tools.Diagnostic.Kind.WARNING;
    
    public class NameChecker {
        
        //用于在编译时输出警告信息
        private final Messager messager;
        //NameCheckScanner是一个私有类，用于检查和扫描代码规范
        NameCheckScanner nameChckerScanner=new NameCheckScanner();
    
        NameChecker(ProcessingEnvironment processingEnvironment){
        
            //获取消息对象，用于后续警告信息的输出
            this.messager=processingEnvironment.getMessager();
        }
    
        /**
         * 用于执行名称检查
         * @param element 需要被检查的元素
         */
        public void checkNames(Element element){
        
            nameChckerScanner.scan(element);
        }
    
        /**
         * 名称检查实现类，ElementScanner8 是 Java 标准库中的类，
         * 用于扫描和处理抽象语法树 (AST) 中的元素。这里它被参数化为两个类型参数 Void，表示不返回任何值（Void）。
         */
        private class NameCheckScanner extends ElementScanner8<Void,Void>{
        
            /**此方法用于检查java类名是否规范
             * @param e  the element to visit
             * @param p  a visitor-specified parameter
             * @return
             */
            @Override
            public Void visitType(TypeElement e,Void p){
        
                //这一行代码扫描了类的类型参数，用于进一步检查类型参数的命名规范
                scan(e.getTypeParameters(),p);
                //checkCamelCase 方法来检查类名是否符合驼峰命名规范，第二个参数 true 表示类名应以大写字母开头。
                checkCamelCase(e,true);
                //调用父类的 visitType 方法，继续处理类的其他元素
                super.visitType(e,p);
                return null;
            }
    
            /**
             * 用于检查方法和变量的命名规范，包括方法名、变量名是否符合规范，以及一些特殊情况的检查
             * @param e  the element to visit
             * @param p  a visitor-specified parameter
             * @return
             */
            @Override
            public Void visitExecutable(ExecutableElement e,Void p){
        
                if(e.getKind()==METHOD){
        
                    Name name= e.getSimpleName();
                    if(name.contentEquals(e.getEnclosingElement().getSimpleName())){
        
                        messager.printMessage(WARNING,"一个普通方法:"+name+"不应当与类名重复，避免与构造函数混淆",e);
                    }
                    checkCamelCase(e,false);
                }
                super.visitExecutable(e,p);
                return null;
            }
            @Override
            public Void visitVariable(VariableElement e,Void p){
        
                //如果这个Variable是枚举或者是常量，则按大写名称检查，否则按照驼峰命名规则检查
                if(e.getKind()==ENUM_CONSTANT || e.getConstantValue()!=null || heuristicallyConstant(e)){
        
                    checkAllCaps(e);
                }else {
        
                    checkCamelCase(e,false);
                }
                return  null;
            }
    
            /**
             * 判断一个量是否为常量
             * @param e
             * @return
             */
            private boolean heuristicallyConstant(VariableElement e){
        
                if(e.getEnclosingElement().getKind() == INTERFACE){
        
                    return  true;
                }else if(e.getKind() == FIELD && e.getModifiers().containsAll(EnumSet.of(Modifier.PUBLIC,Modifier.STATIC, Modifier.FINAL))){
        
                    return true;
                }else{
        
                    return false;
                }
            }
    
            /**
             * 判断传入的Element是否符合驼峰命名法，如果不符合发出警告信息
             * @param e
             * @param initialCaps
             */
            private void checkCamelCase(Element e, boolean initialCaps){
        
                String name=e.getSimpleName().toString();
                boolean previousUpper= false;
                boolean conventional=true;
                int firstCodePoint =name.codePointAt(0);
    
                if(Character.isUpperCase(firstCodePoint)) {
        
                    previousUpper = true;
                    if (!initialCaps) {
        
                        messager.printMessage(WARNING, "名称" + name + "应当以小写字母开头", e);
                        return;
                    }
                }else if (Character.isLowerCase(firstCodePoint)) {
        
                    if (!initialCaps) {
        
                        messager.printMessage(WARNING, "名称" + name + "应当以大写字母开头");
                        return;
                    }
                } else {
        
                    conventional = false;
                }
                if (conventional) {
        
                    int cp = firstCodePoint;
                    for (int i = Character.charCount(cp); i < name.length(); i += Character.charCount(cp)) {
        
                        cp = name.codePointAt(i);
                        if (Character.isUpperCase(cp)) {
        
                            if (previousUpper) {
        
                                conventional = false;
                                break;
                            }
                            previousUpper = true;
                        } else {
        
                                previousUpper = false;
                        }
                    }
                }
                if (!conventional) {
        
                    messager.printMessage(WARNING, "名称" + name + "应当符合驼峰命名法", e);
                }
            }
    
            /**
             * 大写命名检查，要求第一个字母必须是大写的英文字母。其余部分可以是下划线或大写字母
             * @param e
             */
            private void checkAllCaps(Element e){
        
                String name=e.getSimpleName().toString();
                boolean conventional=true;
                int firstCodepoint=name.codePointAt(0);
                if(!Character.isUpperCase(firstCodepoint)){
        
                    conventional=false;
                }else {
        
                    boolean previousUnderscore=false;
                    int cp=firstCodepoint;
                    for(int i=Character.charCount(cp);i<name.length();i+=Character.charCount(cp)){
        
                        cp=name.codePointAt(i);
                        if(cp ==(int) '_'){
        
                            if(previousUnderscore){
        
                                conventional=false;
                                break;
                            }
                            previousUnderscore=true;
                        }else {
        
                            previousUnderscore=false;
                            if(!Character.isUpperCase(cp) && !Character.isDigit(cp)){
        
                                conventional=false;
                                break;
                            }
                        }
                    }
                }
                if(!conventional){
        
                    messager.printMessage(WARNING,"常量"+name+"应当全部以大写字母或下划线命名，并且以字母开头",e);
                }
            }
    
        }
    
    
    }

### 3. 结果验证 ###

下面定义一个包含了多处不规范命名的代码样例

public class BADLY_NAMED_CODE {
        
        enum colors{
        
            red,blue,green;
        }
        static  final int _FORTY_TWO= 42;
        
        public static  int NOT_A_CONSTANT=_FORTY_TWO;
        protected void BADLY_NAMED_CODE(){
        
            return;
        }
        public void NOTcamelCASEmethodNAME(){
        
            return;
        }
    }

通过使用Javac命令"-processor"参数来执行编译时需要附带的注解处理器，如果有多个注解处理器的话，用逗号隔开，开可以使用-XprintRounds和-XprintProcessorInfo参数来查看主机处理器运作的详细信息。

javac -processor NameCheckProcessor  /Users/jackchai/Desktop/Self-study-notes/jvm测试/jvmtest/src/BADLY_NAMED_CODE.java

![在这里插入图片描述][9a13bb53347e444f89741f87ec9119fe.png]

[9a13bb53347e444f89741f87ec9119fe.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/02/21/0849e43aab944a9d99348eb1450d7023.png