安卓to鸿蒙系列：ButterKnife(二)-安卓鸿蒙

本文基于https://gitee.com/openharmony-tpc/butterknife 分析JakeWharton/butterknife的源码，及移植到鸿蒙需要做的工作。

如果对apt的概念及实践不熟悉，请先移步：安卓to鸿蒙系列：ButterKnife(一)，然后再来阅读本文，会事半功倍!

butterknife项目结构：

和我们在安卓to鸿蒙系列：ButterKnife(一)写的“乞丐版BufferKnife”一样，主要由三个module组成

butterknife_annotations//编译时、运行时都用到

定义了注解

butterknife_compiler//编译时用到

apt的主要实现部分。注解的解析、处理，生成模板文件

butterknife//运行时用到

对外的工具类，供用户使用，完成注入操作。 butterknife_runtime 定义运行时用到的一些类及工具方法。

移植butterknife_annotations

直接对比openharmony-tpc和JakeWharton的这个module吧：

可以看到有增、删、改。

其中增加和删除的是一一对应的。

BindBitmap vs BindPixelMap//安卓的Bitmap对应鸿蒙的PixelMap 
 
BindView vs BindComponent//安卓的View对应鸿蒙的Component 
 
BindViews vs BindComponents//同上 
 
BindDrawable vs BindElement //安卓的Drawable对应鸿蒙的ohos.agp.components.element.Element

其它都是修改，以BindingString为例，只是去掉了鸿蒙没有的注解StringRes、修改注释。

ps：对于鸿蒙没有的注解，还有一个办法就是把androidx或support包下相应的文件copy进来，并且包名也保持一致，这样我们就不需要修改BindingString这一类文件了。经过对比发现，可以减少不小的工作量。

还有一些修改稍复杂一些，以OnClick为例。只要写过两个平台的代码，还是很容易理解的，只是做相应的等价替换。

分析butterknife_compiler的源码

优秀资源参考：

静态分析

1.主要的几个类

ButterKnifeProcessor//注解入口类，apt程序必须继承AbstractProcessor，没什么好说的。
BindingSet//从名字可知，这个类是绑定信息的集合。举例：MainAbilitySlice对应一个BindingSet,也就对应一个xxxx_ViewBinding。

BindingSet的实例存在于编译期，执行它的brewJava()方法生成xxxx_ViewBinding文件。

各种XxxBinding，如：FieldViewBinding、MethodViewBinding、ResourceBinding的各种子类，表示某字段的绑定信息。

以MainAbilitySlice和FieldViewBinding为例，如下注解代码：

//MainAbilitySlice 
@BindComponent(ResourceTable.Id_viewRoot) 
DirectionalLayout mDlViewRoot;

生成一个FieldViewBinding实例，其值为：

final class FieldViewBinding implements MemberViewBinding { 
    private final String name;//"mDlViewRoot" 
    private final TypeName type;//DirectionalLayout 
    private final boolean required;//true 
}

ViewBinding//表示某个控件的绑定信息，其中包括field和method(对于各种事件绑定)。如下代码所示:

final class ViewBinding { 
    private final Id id; 
    private final Map<ListenerClass, Map<ListenerMethod, Set<MethodViewBinding>>> methodBindings; 
    private final FieldViewBinding fieldBinding; 
}

2.ButterKnifeProcessor#process()方法相当注解执行的main方法(会进入多次)，主要干了两件事findAndParseTargets()和brewJava()，如下图所示：

用到的工具：SequenceDiagram - IntelliJ IDEA插件，直接在插件市场搜索、安装就行，用来生成方法调用时序图

3.其中ButterKnifeProcessor#findAndParseTargets()的主要功能是找到并解析各个targets，如下图所示：

ps：这个图省略了很多parseXXX()方法，只保留了一个parseBindComponent()，因为功能类似。不然图太长了。

由上图可知findAndParseTargets()方法实现了以下三件事：

解析注入对象相关的注解parseXXX()

处理@BindComponent,@BindString 之类的组件或资源

//添加注释、删掉多余代码的parseBindComponent() 
private void parseBindComponent(Element element, Map<TypeElement, BindingSet.Builder> builderMap, 
                                Set<TypeElement> erasedTargetNames) { 
    //获取当前元素element的类级别的元素，即XXXAbility 
    TypeElement enclosingElement = (TypeElement) element.getEnclosingElement(); 
    
    //获取@BindComponent的值，即ResourceTable.Id_xxx 
    int id = element.getAnnotation(BindComponent.class).value(); 
     
    //根据当前元素的类级别的元素先从Map中获取BindingSet的内部类Builder 
    BindingSet.Builder builder = builderMap.get(enclosingElement); 
    Id resourceId = elementToId(element, BindComponent.class, id); 
     
    //builder为空，说明当前类还没有对应的value，需要new一个出来，并放到builderMap中 
    //builder会被BindComponent和OnClick等共用一个(享元模式？)，并且它们以XXXAbility分组放在builderMap中。 
    if (builder != null) { 
        String existingBindingName = builder.findExistingBindingName(resourceId); 
        if (existingBindingName != null) { 
            return; 
        } 
    } else { 
        builder = getOrCreateBindingBuilder(builderMap, enclosingElement); 
    } 
 
    //@BindComponent修饰的字段的简单名称，即变量名比如mTextView 
    String name = simpleName.toString(); 
    //@BindComponent修饰的字段的类型，比如Text 
    TypeName type = TypeName.get(elementType); 
    //是否被@Nullable修饰 
    boolean required = isFieldRequired(element); 
 
    //调用BindingSet的内部类Builder中的addField方法封装解析的信息 
    builder.addField(resourceId, new FieldViewBinding(name, type, required)); 
     
    // Add the type-erased version to the valid binding targets set. 
    //给所有含有自定义注解的类组成的Set集合中添加元素 
    erasedTargetNames.add(enclosingElement); 
}

解析事件绑定相关的注解findAndParseListener()

处理@OnClick,@OnItemClick,@OnTextChanged 之类的Listener

通过以上两步，完成了注解信息的扫描收集，并将解析的信息保存到builderMap和erasedTargetNames两个集合中;

findAllSupertypeBindings()，findParentType()，及findAndParseTargets()

第三步，对上面提到的builderMap和erasedTargetNames两个集合中的信息进行重新整理，最终返回一个以TypeElement为key，BindingSet为vaule的bindingMap集合。

下面直接帖学习笔记ButterKnife的分析吧：

private Map<TypeElement, BindingSet> findAndParseTargets1(RoundEnvironment env) { 
    //这个不是最后返回的对象,这个只是BindingSet对应的Builder类，保存了BindComponent、BindString、OnClick等等相关的绑定信息 
    Map<TypeElement, BindingSet.Builder> builderMap = new LinkedHashMap<>(); 
    Set<TypeElement> erasedTargetNames = new LinkedHashSet<>(); 
 
    //隐藏代码 @BindXxx-------------------- 
 
    //绑定界面上的View 
    for (Element element : env.getElementsAnnotatedWith(BindComponent.class)) { 
        parseBindComponent(element, builderMap, erasedTargetNames); 
    } 
 
    //隐藏代码 bindListener.--------------- 
 
    Map<TypeElement, ClasspathBindingSet> classpathBindings = 
            findAllSupertypeBindings(builderMap, erasedTargetNames); 
    //组合所有类的关系  组成 树 
    //这里注释也写了，用队列的方式，将超类与子类绑定，从根开始 
    // Associate superclass binders with their subclass binders. This is a queue-based tree walk 
    // which starts at the roots (superclasses) and walks to the leafs (subclasses). 
    //这个获取的所有的“类”  放入了队列 
    Deque<Map.Entry<TypeElement, BindingSet.Builder>> entries = 
            new ArrayDeque<>(builderMap.entrySet()); 
    //即将返回的对象 
    Map<TypeElement, BindingSet> bindingMap = new LinkedHashMap<>(); 
    while (!entries.isEmpty()) { 
        Map.Entry<TypeElement, BindingSet.Builder> entry = entries.removeFirst(); 
 
        TypeElement type = entry.getKey(); 
        BindingSet.Builder builder = entry.getValue(); 
        //拿队列出来的第一个 在erasedTargetNames中查询,父类是否在这个这个集合里 
        //为什么要这样？ 因为可能 你在父类中 绑定了一个String 
        //在子类中使用了这个String,所以必须先初始化父类的String 
        //翻看生成好的代码来看，初始化都是在构造函数中进行绑定的 
        //所以考虑继承情况，必须把所有的类进行一个关联。 
        TypeElement parentType = findParentType(type, erasedTargetNames, classpathBindings.keySet()); 
        if (parentType == null) { 
            //如果没有父类，则直接 放入 
            bindingMap.put(type, builder.build()); 
        } else { 
            //如果父类有绑定 
            //再从bindingMap（即将返回的对象）中取看看 是否已经放进去了 
            BindingInformationProvider parentBinding = bindingMap.get(parentType); 
            if (parentBinding == null) { 
                //如果没绑定进去 再从classpathBindings中取 一个父类 
                parentBinding = classpathBindings.get(parentType); 
            } 
            if (parentBinding != null) { 
                //如果这个父类不是空的 则和当前循环里的builder  子、父类绑定 
                builder.setParent(parentBinding); 
                //放入即将返回的map里 
                bindingMap.put(type, builder.build()); 
            } else { 
                //翻译是：有个超类绑定，但还没有构建它，放到后面继续排队 
                // Has a superclass binding but we haven't built it yet. Re-enqueue for later. 
                //比如：子类继承父类都有绑定，这时候子类需要关联父类，父类还没初始化， 
                //把子类放到队尾，等父类初始化完成在进行关联 
                entries.addLast(entry); 
            } 
        } 
    } 
    //返回，这时候这个map的key 就全是“类信息” 
    //value就是获取好的 当前类里面需要绑定的内容 
    //并且 “类” 也已经做好了继承关系 
    return bindingMap; 
}

总结一下这个方法，就像它的方法名一样 “找到并解析各个targets” 。这里有个疑问，targets是什么呢? targets就是待注入的字段、待绑定事件的方法，比如下面代码中的mTextView就是target，即“待注入的字段”

@BindComponent(ResourceTable.Id_tv_hello) 
Text mTextView;

动态分析

动态分析主要是验证一下上面静态分析的结论。对于比较复杂的代码，需要debug跟一下代码，查看运行时关键变量的值。

怎么调试butterknife_compiler?

参考：https://www.w3ma.com/how-to-debug-an-annotation-processor-in-android-studio/

1.新建一个remote debug，比如命名为aptDebug

因为apt过程在编译期，所以需要remote debug。什么是remote debug，可以自己google一下。

2.在butterknife根目录的命令行中运行gradlew --no-daemon -Dorg.gradle.debug=true :entry:clean :entry:compileDebugJavaWithJavac，编译过程处于等待调试的状态，如下如：

:entry:clean加上它是表示重新构建。

-Dorg.gradle.debug=true设置为true时，Gradle将在启用远程调试的情况下运行构建，侦听端口5005。这等效于将-agentlib：jdwp = transport = dt_socket，server = y，suspend = y，address = 5005添加到 JVM命令行，它将挂起虚拟机，直到连接了调试器。

3.设置断点，然后点击小虫子debug按钮。

4.以debug parseBindComponent()为例：

小技巧：条件断点在这里会提高调试的效率。自己google一下。

通过debug跟代码，可知void parseBindComponent(Element element, Map<TypeElement, BindingSet.Builder> builderMap, Set<TypeElement> erasedTargetNames)方法的输入element为@BindComponent注解的java元素，输出builderMap和erasedTargetNames。

其中BinderingSet$Builder为BinderingSet的构建者，这里用到了Builder构建者设计模式。

其中BinderingSet记录了模板类XXX_ViewBinding的生成规则。

在parseBindComponent方法中，调用Builder的addField添加了一条生成java文件的规则，即注入View。其它的parseXXX()方法类似。总结一下：

parseBindComponent()//调用Builder的`addField`，注入View。 
parseResourceXXX()//调用Builder的`addResource`，注入各种资源，如String、int、float、Dimen、Color、Array、PixelMap等。 
findAndParseListener()//调用Builder的`addMethod`，绑定各种事件。

5.debug Map<TypeElement, BindingSet> findAndParseTargets()

先说上面提到 targets是什么呢?，通过跟代码，可知targets是被注解的Element，比如MainAblilitySlice中的mDlViewRoot

@BindComponent(ResourceTable.Id_viewRoot) 
DirectionalLayout mDlViewRoot;

方法的返回值是类和它的模板类的一一对应。

如"com.example.butterknife.slice.MainAbilitySlice" -> "com.example.butterknife.slice.MainAbilitySlice_ViewBinding"

日志分析：

debug的效率其实很低。听说10倍程序员都爱打日志。所以，我们也要知道apt的messager的用法及注意事项有哪些?

虽然System.out.println();也可以打日志。但是messager会根据日志类型，把Kind.WARNING和Kind.ERROR类型的日志做统计，方便我们定位问题。

在ButterKnifeProcessor中有封装messager的几个方法：

private void error(Element element, String message, Object... args) { 
    printMessage(Kind.ERROR, element, message, args); 
} 
 
private void note(Element element, String message, Object... args) { 
    printMessage(Kind.NOTE, element, message, args); 
} 
 
private void printMessage(Kind kind, Element element, String message, Object[] args) { 
    if (args.length > 0) { 
        message = String.format(message, args); 
    } 
 
    processingEnv.getMessager().printMessage(kind, message, element); 
}

注意：一定要执行gradlew --no-daemon :entry:clean :entry:compileDebugJavaWithJavac，compileDebugJavaWithJavac这个task。而且加上clean。不然看不到日志。

向apt程序传参：

在ButterKnifeProcessor中覆写了getSupportedOptions()，这样我们可以向apt传参了。

@Override 
public Set<String> getSupportedOptions() { 
    ImmutableSet.Builder<String> builder = ImmutableSet.builder(); 
    builder.add(OPTION_SDK_INT, OPTION_DEBUGGABLE); 
    if (trees != null) { 
        builder.add(IncrementalAnnotationProcessorType.ISOLATING.getProcessorOption()); 
    } 
    return builder.build(); 
}

传参方法：在entry中

ohos { 
    compileSdkVersion 5 
    defaultConfig { 
        compatibleSdkVersion 5 
 
        javaCompileOptions { 
            annotationProcessorOptions { 
                arguments = ['butterknife.debuggable': "true"] 
            } 
        } 
    } 
}

在init()方法中，我们可以取出传入的值：

@Override 
public synchronized void init(ProcessingEnvironment env) { 
    super.init(env); 
    debuggable = !"false".equals(env.getOptions().get(OPTION_DEBUGGABLE)); 
    env.getMessager().printMessage(Kind.NOTE, "--------------- debuggable = "+debuggable); 
}

移植butterknife_compiler

通过上面的代码分析，我们知道在安卓和鸿蒙上butterknife_compiler的基本流程没有变，所以移植工作要做的就是因为平台class及api不同，做一些相应的调整。

对比代码后，差异不大。简单列举一下：

findViewById的修改
Resource相关api的修改
Font的修改(NORMAL变成REGULAR)
BindAnim在鸿蒙版上暂不支持
COLOR_STATE_LIST在鸿蒙版上暂不支持

移植butterknife_runtime

butterknife_runtime同时被butterknife_compiler和butterknife两个module依赖，其中大多是一些工具类，同样，做相应的api修改就可以。

对比代码后，差异比较大。但是都集中的对资源Resource的加载差异上，以及androidx.annotation.UiThread之类的注解(直接删掉就好)。

移植butterknife

butterknife这个module只有一个类ButterKnife，这个类的作用就是通过反射实例化XXX_ViewBinding，并提供一系列静态方法如Unbinder bind(Ability target)来实现target中变量的注入和方法的绑定。同样，做相应的api修改就可以。

欢迎有兴趣的朋友可以完善entry中的用例

目前该库有一些bug，比如：Unbinder bind(Ability target)注入Ability会失败。我相信，bug不止这一个。

发现bug，提issue。我们一起将它完善。

总结

距离写完安卓to鸿蒙系列：ButterKnife(一)已经有两个多月，当时，写一个乞丐版ButterKnife觉得还是很easy的。但是，想读懂ButterKnife难度还是很大的，一方面自己菜，另一方面代码量大，代码结构复杂。而且很多概念不好理解(比如javapoet引入的各种类，绑定信息相关的几个类BingdingSet、BingdingSet.Builder、xxxBingding等)。

想了解更多内容，请访问：

51CTO和华为官方合作共建的鸿蒙技术社区

https://harmonyos.51cto.com