广场 › 移动开发 › 安卓to鸿蒙系列：ButterKnife(二)

江南才子 发表于 2021-7-27 11:27:11

安卓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的源码
静态分析

[*]主要的几个类

[*]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;
}

[*]ButterKnifeProcessor#process()方法相当注解执行的main方法(会进入多次)，主要干了两件事findAndParseTargets()和brewJava()，如下图所示：
用到的工具：SequenceDiagram - IntelliJ IDEA插件，直接在插件市场搜索、安装就行，用来生成方法调用时序图

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

ps：这个图省略了很多parseXXX()方法，只保留了一个parseBindComponent()，因为功能类似。不然图太长了。
由上图可知findAndParseTargets()方法实现了以下三件事：

[*]解析注入对象相关的注解parseXXX()
处理@BindComponent,@BindString 之类的组件或资源
//添加注释、删掉多余代码的parseBindComponent()
private void parseBindComponent(Element element, Map<TypeElement, BindingSet.Builder> builderMap,

                              Set&lt;TypeElement&gt; 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集合。
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&lt;&gt;(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/

[*]新建一个remote debug，比如命名为aptDebug
因为apt过程在编译期，所以需要remote debug。什么是remote debug，可以自己google一下。

[*]在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命令行，它将挂起虚拟机，直到连接了调试器。

[*]设置断点，然后点击小虫子debug按钮。

[*]以debug parseBindComponent()为例：
小技巧：条件断点在这里会提高调试的效率。自己google一下。

通过debug跟代码，可知void parseBindComponent(Element element, Map&amp;lt;TypeElement, BindingSet.Builder&amp;gt; builderMap, Set&amp;lt;TypeElement&amp;gt; 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，绑定各种事件。
[*]debug Map&amp;lt;TypeElement, BindingSet&amp;gt; findAndParseTargets()
先说上面提到 targets是什么呢？，通过跟代码，可知targets是被注解的Element， 比如MainAblilitySlice中的mDlViewRoot
@BindComponent(ResourceTable.Id_viewRoot)
DirectionalLayout mDlViewRoot;方法的返回值是类和它的模板类的一一对应。

如"com.example.butterknife.slice.MainAbilitySlice" -&gt; "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等）。
再次膜拜大神JakeWharton。
想了解更多关于鸿蒙的内容，请访问：
51CTO和华为官方战略合作共建的鸿蒙技术社区
https://harmonyos.51cto.com/#bkwz

文档来源：51CTO技术博客https://blog.51cto.com/harmonyos/3193955

查看完整版本: 安卓to鸿蒙系列：ButterKnife(二)