安卓to鸿蒙系列:ButterKnife(二) 原创 精华

发布于 2021-7-20 21:10
1409浏览
2收藏

@toc

本文基于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吧:

安卓to鸿蒙系列:ButterKnife(二)-鸿蒙HarmonyOS技术社区
可以看到有增、删、改。

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

    BindBitmap vs BindPixelMap//安卓的Bitmap对应鸿蒙的PixelMap

    BindView vs BindComponent//安卓的View对应鸿蒙的Component

    BindViews vs BindComponents//同上

    BindDrawable vs BindElement //安卓的Drawable对应鸿蒙的ohos.agp.components.element.Element

  • 其它都是修改,以BindingString为例,只是去掉了鸿蒙没有的注解StringRes、修改注释。
    安卓to鸿蒙系列:ButterKnife(二)-鸿蒙HarmonyOS技术社区

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

  • 还有一些修改稍复杂一些,以OnClick为例。只要写过两个平台的代码,还是很容易理解的,只是做相应的等价替换。
    安卓to鸿蒙系列:ButterKnife(二)-鸿蒙HarmonyOS技术社区

分析butterknife_compiler的源码

优秀资源参考:

静态分析

  1. 主要的几个类

    • ButterKnifeProcessor//注解入口类,apt程序必须继承AbstractProcessor,没什么好说的。

    • BindingSet//从名字可知,这个类是绑定信息的集合。举例:MainAbilitySlice对应一个BindingSet,也就对应一个xxxx_ViewBinding

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

    • 各种XxxBinding,如:FieldViewBindingMethodViewBindingResourceBinding的各种子类,表示某字段的绑定信息。

      MainAbilitySliceFieldViewBinding为例,如下注解代码:

      //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插件,直接在插件市场搜索、安装就行,用来生成方法调用时序图

    安卓to鸿蒙系列:ButterKnife(二)-鸿蒙HarmonyOS技术社区

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

    安卓to鸿蒙系列:ButterKnife(二)-鸿蒙HarmonyOS技术社区

    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

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

    • findAllSupertypeBindings()findParentType(),及findAndParseTargets()

      第三步,对上面提到的builderMaperasedTargetNames两个集合中的信息进行重新整理,最终返回一个以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一下。

    安卓to鸿蒙系列:ButterKnife(二)-鸿蒙HarmonyOS技术社区

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

    安卓to鸿蒙系列:ButterKnife(二)-鸿蒙HarmonyOS技术社区

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

    安卓to鸿蒙系列:ButterKnife(二)-鸿蒙HarmonyOS技术社区

  4. 以debug parseBindComponent()为例:

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

    安卓to鸿蒙系列:ButterKnife(二)-鸿蒙HarmonyOS技术社区

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

    其中BinderingSet$BuilderBinderingSet的构建者,这里用到了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;
    

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

    安卓to鸿蒙系列:ButterKnife(二)-鸿蒙HarmonyOS技术社区

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

日志分析:

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

虽然System.out.println();也可以打日志。但是messager会根据日志类型,把Kind.WARNINGKind.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:compileDebugJavaWithJavaccompileDebugJavaWithJavac这个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);
}

安卓to鸿蒙系列:ButterKnife(二)-鸿蒙HarmonyOS技术社区

移植butterknife_compiler

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

安卓to鸿蒙系列:ButterKnife(二)-鸿蒙HarmonyOS技术社区

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

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

移植butterknife_runtime

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

安卓to鸿蒙系列:ButterKnife(二)-鸿蒙HarmonyOS技术社区

对比代码后,差异比较大。但是都集中的对资源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

©著作权归作者和HarmonyOS技术社区共同所有,如需转载,请注明出处,否则将追究法律责任
已于2021-7-21 08:41:28修改
3
收藏 2
回复
举报
回复
添加资源
添加资源将有机会获得更多曝光,你也可以直接关联已上传资源 去关联