编译期注解之JavaPoet

注解系列

0x00 概述#

上一篇限于篇幅只介绍了APT，这篇来继续介绍javapoet，是square公司的开源库。正如其名，java诗人，通过注解来生成java源文件，通常要使用javapoet这个库与Filer配合使用。主要和注解配合用来干掉那些重复的模板代码(如butterknife 和databinding所做的事情)，当然你也可以使用这个技术让你的代码更加的炫酷。

0x01 简单使用#

使用之前要先引入这个库

1
compile 'com.squareup:javapoet:1.7.0'

javapoet是用来生成代码的，需要借助

常用类

使用javapoet前需要了解8个常用类

类名	作用
MethodSpec	代表一个构造函数或方法声明
TypeSpec	代表一个类，接口，或者枚举声明
FieldSpec	代表一个成员变量，一个字段声明
JavaFile	包含一个顶级类的Java文件
ParameterSpec	用来创建参数
AnnotationSpec	用来创建注解
ClassName	用来包装一个类
TypeName	类型，如在添加返回值类型是使用 TypeName.VOID

除此之外 JavaPoet提供了一套自定义的字符串格式化规则，常用的有 $L,$ S, $T,$ N

格式化规则	表示含义
$L	字面量
$S	字符串
$T	类、接口
$N	变量

0x02 使用进阶#

下面由浅入深，循序渐进的说明用法

方法&控制流：

添加方法 addcode 和 addstatement 对与无需类引入的极简代码可以直接使用addCode

1
MethodSpec main = MethodSpec.methodBuilder("main")
2
    .addCode(""
3
        + "int total = 0;\n"
4
        + "for (int i = 0; i < 10; i++) {\n"
5
        + "  total += i;\n"
6
        + "}\n")
7
    .build();

生成的是

1
void main() {
2
  int total = 0;
3
  for (int i = 0; i < 10; i++) {
4
    total += i;
5
  }
6
}

要是需要import的方法，如上面的.addStatement("$T.out.println($S)", System.class, "Hello, JavaPoet!") 就需要使用.addStatement来声明

更优雅的流控制

beginControlFlow 流开启 addStatement 处理语句 endControlFlow()流结束

如上面的用流改写就是

1
MethodSpec main = MethodSpec.methodBuilder("main")
2
    .addStatement("int total = 0")
3
    .beginControlFlow("for (int i = 0; i < 10; i++)")
4
    .addStatement("total += i")
5
    .endControlFlow()
6
    .build();

占位符

javapoet里面提供了占位符来帮助我们更好地生成代码

$L 字面常量（Literals）

1
private MethodSpec computeRange(String name, int from, int to, String op) {
2
  return MethodSpec.methodBuilder(name)
3
      .returns(int.class)
4
      .addStatement("int result = 0")
5
      .beginControlFlow("for (int i = $L; i < $L; i++)", from, to)
6
      .addStatement("result = result $L i", op)
7
      .endControlFlow()
8
      .addStatement("return result")
9
      .build();
10
}

这个就是一个for循环，op负责加减乘除等符号

$S 字符串常量（String）
$T 类型(Types)

最大的特点是自动导入包

1
MethodSpec today = MethodSpec.methodBuilder("today")
2
    .returns(Date.class)
3
    .addStatement("return new $T()", Date.class)
4
    .build();
5

6
TypeSpec helloWorld = TypeSpec.classBuilder("HelloWorld")
7
    .addModifiers(Modifier.PUBLIC, Modifier.FINAL)
8
    .addMethod(today)
9
    .build();
10

11
JavaFile javaFile = JavaFile.builder("com.example.helloworld", helloWorld)
12
    .build();
13

14
javaFile.writeTo(System.out);

生成的代码如下，而且会自动导包

1
package com.example.helloworld;
2

3
import java.util.Date;
4

5
public final class HelloWorld {
6
  Date today() {
7
    return new Date();
8
  }
9
}

$N 命名(Names),通常指我们自己生成的方法名或者变量名等等

比如这样的代码块

1
public String byteToHex(int b) {
2
  char[] result = new char[2];
3
  result[0] = hexDigit((b >>> 4) & 0xf);
4
  result[1] = hexDigit(b & 0xf);
5
  return new String(result);
6
}
7

8
public char hexDigit(int i) {
9
  return (char) (i < 10 ? i + '0' : i - 10 + 'a');
10
}

我们可以传递hexDigit()来代替。

1
MethodSpec hexDigit = MethodSpec.methodBuilder("hexDigit")
2
    .addParameter(int.class, "i")
3
    .returns(char.class)
4
    .addStatement("return (char) (i < 10 ? i + '0' : i - 10 + 'a')")
5
    .build();
6

7
MethodSpec byteToHex = MethodSpec.methodBuilder("byteToHex")
8
    .addParameter(int.class, "b")
9
    .returns(String.class)
10
    .addStatement("char[] result = new char[2]")
11
    .addStatement("result[0] = $N((b >>> 4) & 0xf)", hexDigit)
12
    .addStatement("result[1] = $N(b & 0xf)", hexDigit)
13
    .addStatement("return new String(result)")
14
    .build();

获取对应类

有两种方式:

ClassName.bestGuess(“类全名称”) 返回ClassName对象，这里的类全名称表示的类必须要存在，会自动导入相应的包
ClassName.get(“包名”，”类名”) 返回ClassName对象，不检查该类是否存在

因此如果使用JavaPoet的话后续代码重构改变类名往往需要格外注意一点

1
ClassName hoverboard = ClassName.get("com.mattel", "Hoverboard");
2
ClassName list = ClassName.get("java.util", "List");
3
ClassName arrayList = ClassName.get("java.util", "ArrayList");
4
TypeName listOfHoverboards = ParameterizedTypeName.get(list, hoverboard);
5

6
MethodSpec beyond = MethodSpec.methodBuilder("beyond")
7
    .returns(listOfHoverboards)
8
    .addStatement("$T result = new $T<>()", listOfHoverboards, arrayList)
9
    .addStatement("result.add(new $T())", hoverboard)
10
    .addStatement("result.add(new $T())", hoverboard)
11
    .addStatement("result.add(new $T())", hoverboard)
12
    .addStatement("return result")
13
    .build();

然后生成

1
package com.example.helloworld;
2

3
import com.mattel.Hoverboard;
4
import java.util.ArrayList;
5
import java.util.List;
6

7
public final class HelloWorld {
8
  List<Hoverboard> beyond() {
9
    List<Hoverboard> result = new ArrayList<>();
10
    result.add(new Hoverboard());
11
    result.add(new Hoverboard());
12
    result.add(new Hoverboard());
13
    return result;
14
  }
15
}

构建类的元素

方法

方法的修饰，如Modifiers.ABSTRACT

1
MethodSpec flux = MethodSpec.methodBuilder("flux")
2
    .addModifiers(Modifier.ABSTRACT, Modifier.PROTECTED)
3
    .build();
4

5
TypeSpec helloWorld = TypeSpec.classBuilder("HelloWorld")
6
    .addModifiers(Modifier.PUBLIC, Modifier.ABSTRACT)
7
    .addMethod(flux)
8
    .build();

这将会生成如下代码

1
public abstract class HelloWorld {
2
  protected abstract void flux();
3
}

当然Methods需要和MethodSpec.Builder配置来增加方法参数、异常、javadoc、注解等。

构造器

这个其实也是个函数方法而已，因此可以使用MethodSpec来生成构造器方法。比如：

1
MethodSpec flux = MethodSpec.constructorBuilder()
2
    .addModifiers(Modifier.PUBLIC)
3
    .addParameter(String.class, "greeting")
4
    .addStatement("this.$N = $N", "greeting", "greeting")
5
    .build();
6

7
TypeSpec helloWorld = TypeSpec.classBuilder("HelloWorld")
8
    .addModifiers(Modifier.PUBLIC)
9
    .addField(String.class, "greeting", Modifier.PRIVATE, Modifier.FINAL)
10
    .addMethod(flux)
11
    .build();

将会生成

1
public class HelloWorld {
2
  private final String greeting;
3

4
  public HelloWorld(String greeting) {
5
    this.greeting = greeting;
6
  }
7
}

参数(重要)

之前我们是通过addstatement直接设置参数，其实参数也有自己的一个专用类ParameterSpec，我们可以使用ParameterSpec.builder()来生成参数，然后MethodSpec的addParameter去使用，这样更加优雅。

1
ParameterSpec android = ParameterSpec.builder(String.class, "android")
2
    .addModifiers(Modifier.FINAL)
3
    .build();
4

5
MethodSpec welcomeOverlords = MethodSpec.methodBuilder("welcomeOverlords")
6
    .addParameter(android)
7
    .addParameter(String.class, "robot", Modifier.FINAL)
8
    .build();

生成的代码

1
void welcomeOverlords(final String android, final String robot) {
2
}

稍微复杂点的类型比如泛型、Map之类的，需要了解下JavaPoet定义的几种专门描述类型的类

常见的有

分类	生成的类型	JavaPoet 写法	也可以这么写（等效的 Java 写法）
内置类型	int	TypeName.INT	int.class
数组类型	int[]	ArrayTypeName.of(int.class)	int[].class
需要引入包名的类型	java.io.File	ClassName.get(“java.io”, “File”)	java.io.File.class
参数化类型（ParameterizedType	List	ParameterizedTypeName.get(List.class, String.class)	-
类型变量（WildcardType）用于声明泛型	T	TypeVariableName.get(“T”)	-
通配符类型	? extends String	WildcardTypeName.subtypeOf(String.class)	-

1
/*
2
 *Build input type, format as :
3
 *Map<String, Class<? extends IRouteGroup>>
4
 */
5
    ParameterizedTypeName inputMapTypeOfRoot = ParameterizedTypeName.get(
6
            ClassName.get(Map.class),
7
            ClassName.get(String.class),
8
            ParameterizedTypeName.get(
9
                    ClassName.get(Class.class),
10
                    WildcardTypeName.subtypeOf(ClassName.get(type_IRouteGroup))
11
            )
12
    );
13

14
    /*
15
     *Map<String, RouteMeta>
16
     */
17
    ParameterizedTypeName inputMapTypeOfGroup = ParameterizedTypeName.get(
18
            ClassName.get(Map.class),
19
            ClassName.get(String.class),
20
            ClassName.get(RouteMeta.class)
21
    );
22

23
    /*
24
     *Build input param name.
25
     */
26
    ParameterSpec rootParamSpec = ParameterSpec.builder(inputMapTypeOfRoot, "routes").build();
27
    ParameterSpec groupParamSpec = ParameterSpec.builder(inputMapTypeOfGroup, "atlas").build();

生成参数类型

1
public class ARouter$$Root$$app implements IRouteRoot {
2
  @Override
3
  public void loadInto(Map<String, Class<? extends IRouteGroup>> routes) {
4
    routes.put("service", ARouter$$Group$$service.class);
5
    routes.put("test", ARouter$$Group$$test.class);
6
  }
7
}
8

9

10
public class ARouter$$Group$$service implements IRouteGroup {
11
  @Override
12
  public void loadInto(Map<String, RouteMeta> atlas) {
13
    atlas.put("/service/hello", RouteMeta.build(RouteType.PROVIDER, HelloServiceImpl.class, "/service/hello", "service", null, -1, -2147483648));
14
    atlas.put("/service/json", RouteMeta.build(RouteType.PROVIDER, JsonServiceImpl.class, "/service/json", "service", null, -1, -2147483648));
15
    atlas.put("/service/single", RouteMeta.build(RouteType.PROVIDER, SingleService.class, "/service/single", "service", null, -1, -2147483648));
16
  }
17
}

还有常用的复杂类型，特别是各种泛型参数的map

1
final TypeVariableName s = TypeVariableName.get("S");
2
        final TypeVariableName p = TypeVariableName.get("P", s);
3
        final WildcardTypeName any = WildcardTypeName.subtypeOf(Object.class);
4
        final WildcardTypeName subTypeOfS = WildcardTypeName.subtypeOf(s);
5
        final ClassName java_lang_Class = ClassName.get(Class.class);
6
        final ClassName java_util_Collections = ClassName.get("java.util", "Collections");
7
        final ClassName java_util_Map = ClassName.get("java.util", "Map");
8
        final ClassName java_util_Set = ClassName.get("java.util", "Set");
9
        final ClassName java_util_LinkedHashMap = ClassName.get("java.util", "LinkedHashMap");
10
        final ClassName java_util_LinkedHashSet = ClassName.get("java.util", "LinkedHashSet");
11
        final ClassName instantiator = ClassName.get("java.util.concurrent", "Callable");
12
        final TypeName classOfAny = ParameterizedTypeName.get(java_lang_Class, any);
13
        final TypeName instantiatorOfAny = ParameterizedTypeName.get(instantiator, any);
14
        final TypeName instantiatorOfP = ParameterizedTypeName.get(instantiator, p);
15
        final TypeName classOfS = ParameterizedTypeName.get(java_lang_Class, s);
16
        final TypeName classOfP = ParameterizedTypeName.get(java_lang_Class, p);
17
        final TypeName classOfSubTypeOfS = ParameterizedTypeName.get(java_lang_Class, subTypeOfS);
18
        final TypeName setOfClass = ParameterizedTypeName.get(java_util_Set, classOfAny);
19
        final TypeName setOfClassOfSubTypeOfS = ParameterizedTypeName.get(java_util_Set, classOfSubTypeOfS);
20
        final TypeName linkedHashSetOfClass = ParameterizedTypeName.get(java_util_LinkedHashSet, classOfAny);
21
        final TypeName mapOfClassToSetOfClass = ParameterizedTypeName.get(java_util_Map, classOfAny, setOfClass);
22
        final TypeName mapOfClassToInstantiator = ParameterizedTypeName.get(java_util_Map, classOfAny, instantiatorOfAny);
23
        final TypeName linkedHashMapOfClassToSetOfClass = ParameterizedTypeName.get(java_util_LinkedHashMap, classOfAny, setOfClass);
24
        final TypeName linkedHashMapOfClassToInstantializer = ParameterizedTypeName.get(java_util_LinkedHashMap, classOfAny, instantiatorOfAny);

字段

可以使用FieldSpec去声明字段，然后加到Method中处理

1
FieldSpec android = FieldSpec.builder(String.class, "android")
2
    .addModifiers(Modifier.PRIVATE, Modifier.FINAL)
3
    .build();
4

5
TypeSpec helloWorld = TypeSpec.classBuilder("HelloWorld")
6
    .addModifiers(Modifier.PUBLIC)
7
    .addField(android)
8
    .addField(String.class, "robot", Modifier.PRIVATE, Modifier.FINAL)
9
    .build();

然后生成代码

1
public class HelloWorld {
2
  private final String android;
3

4
  private final String robot;
5
}

通常Builder可以更加详细的创建字段的内容，比如javadoc、annotations或者初始化字段参数等，如：

1
FieldSpec android = FieldSpec.builder(String.class, "android")
2
    .addModifiers(Modifier.PRIVATE, Modifier.FINAL)
3
    .initializer("$S + $L", "Lollipop v.", 5.0d)
4
    .build();

对应生成的代码

1
private final String android = "Lollipop v." + 5.0;

接口

接口方法必须是PUBLIC ABSTRACT并且接口字段必须是PUBLIC STATIC FINAL ，使用TypeSpec.interfaceBuilder

如下

1
TypeSpec helloWorld = TypeSpec.interfaceBuilder("HelloWorld")
2
    .addModifiers(Modifier.PUBLIC)
3
    .addField(FieldSpec.builder(String.class, "ONLY_THING_THAT_IS_CONSTANT")
4
        .addModifiers(Modifier.PUBLIC, Modifier.STATIC, Modifier.FINAL)
5
        .initializer("$S", "change")
6
        .build())
7
    .addMethod(MethodSpec.methodBuilder("beep")
8
        .addModifiers(Modifier.PUBLIC, Modifier.ABSTRACT)
9
        .build())
10
    .build();

生成的代码如下

1
public interface HelloWorld {
2
  String ONLY_THING_THAT_IS_CONSTANT = "change";
3

4
  void beep();
5
}

继承父类实现接口

接口代码

1
package com.test.javapoet;
2
public interface TestInterface<T> {
3
    void test(T testPara);
4
}

父类代码

1
public class TestExtendesClass {
2

3
}

使用javapoet实现接口并且继承父类

1
final ClassName  InterfaceName = ClassName.get("com.test.javapoet","TestInterface");
2

3

4
    ClassName superinterface = ClassName.bestGuess("com.test.javapoet.TestClass");
5
    //ClassName superinterface = ClassName.get("com.test.javapoet","aa");
6

7
    TypeSpec.Builder spec = TypeSpec.classBuilder("TestImpl")
8
            .addModifiers(Modifier.PUBLIC)
9
            // 添加接口，ParameterizedTypeName的参数1是接口，参数2是接口的泛型
10
            .addSuperinterface(ParameterizedTypeName.get(InterfaceName, superinterface))
11
            //使用ClassName.bestGuess会自动导入包
12
            .superclass(ClassName.bestGuess("com.zs.javapoet.test.TestExtendesClass"));
13

14

15
    MethodSpec.Builder methodSpec = MethodSpec.methodBuilder("test")
16
            .addAnnotation(Override.class)
17
            .returns(TypeName.VOID)
18
            .addParameter(superinterface, "testPara")
19
            .addStatement("System.out.println(hello)" );
20

21
        TypeSpec typeSpec = spec.addMethod(methodSpec.build()).build();
22

23
    JavaFile file = JavaFile.builder("com.zs.javapoet", typeSpec).build();
24
    file.writeTo(System.out);

生成代码

1
package com.test.javapoet;
2

3
    import com.zs.javapoet.test.TestExtendesClass;
4
    import java.lang.Override;
5

6
    public class TestImpl extends TestExtendesClass implements TestInterface<TestClass> {
7
      @Override
8
      void test(TestClass testPara) {
9
        System.out.println(hello);
10
      }
11
    }

枚举类型

使用TypeSpec.enumBuilder来创建，使用addEnumConstant来添加

1
TypeSpec helloWorld = TypeSpec.enumBuilder("Roshambo")
2
    .addModifiers(Modifier.PUBLIC)
3
    .addEnumConstant("ROCK")
4
    .addEnumConstant("SCISSORS")
5
    .addEnumConstant("PAPER")
6
    .build();

生成的代码

1
public enum Roshambo {
2
  ROCK,
3

4
  SCISSORS,
5

6
  PAPER
7
}

更复杂的类型也可以支持，如重写、注解等

1
TypeSpec helloWorld = TypeSpec.enumBuilder("Roshambo")
2
    .addModifiers(Modifier.PUBLIC)
3
    .addEnumConstant("ROCK", TypeSpec.anonymousClassBuilder("$S", "fist")
4
        .addMethod(MethodSpec.methodBuilder("toString")
5
            .addAnnotation(Override.class)
6
            .addModifiers(Modifier.PUBLIC)
7
            .addStatement("return $S", "avalanche!")
8
            .build())
9
        .build())
10
    .addEnumConstant("SCISSORS", TypeSpec.anonymousClassBuilder("$S", "peace")
11
        .build())
12
    .addEnumConstant("PAPER", TypeSpec.anonymousClassBuilder("$S", "flat")
13
        .build())
14
    .addField(String.class, "handsign", Modifier.PRIVATE, Modifier.FINAL)
15
    .addMethod(MethodSpec.constructorBuilder()
16
        .addParameter(String.class, "handsign")
17
        .addStatement("this.$N = $N", "handsign", "handsign")
18
        .build())
19
    .build();

生成代码

1
public enum Roshambo {
2
  ROCK("fist") {
3
    @Override
4
    public void toString() {
5
      return "avalanche!";
6
    }
7
  },
8

9
  SCISSORS("peace"),
10

11
  PAPER("flat");
12

13
  private final String handsign;
14

15
  Roshambo(String handsign) {
16
    this.handsign = handsign;
17
  }
18
}

判断是否是子类

1
private Types types;
2

3
@Override
4
public synchronized void init(ProcessingEnvironment processingEnv) {
5
super.init(processingEnv);
6

7
mFiler = processingEnv.getFiler();                  // Generate class.
8
types = processingEnv.getTypeUtils();            // Get type utils.
9
elements = processingEnv.getElementUtils();
10
……
11
}
12

13
TypeMirror type_Activity = elements.getTypeElement(ACTIVITY).asType();
14
TypeMirror tm = element.asType();
15
if (types.isSubtype(tm, type_Activity))

匿名内部类

需要使用Type.anonymousInnerClass(""),通常可以使用$L占位符来指代

1
TypeSpec comparator = TypeSpec.anonymousClassBuilder("")
2
    .addSuperinterface(ParameterizedTypeName.get(Comparator.class, String.class))
3
    .addMethod(MethodSpec.methodBuilder("compare")
4
        .addAnnotation(Override.class)
5
        .addModifiers(Modifier.PUBLIC)
6
        .addParameter(String.class, "a")
7
        .addParameter(String.class, "b")
8
        .returns(int.class)
9
        .addStatement("return $N.length() - $N.length()", "a", "b")
10
        .build())
11
    .build();
12

13
TypeSpec helloWorld = TypeSpec.classBuilder("HelloWorld")
14
    .addMethod(MethodSpec.methodBuilder("sortByLength")
15
        .addParameter(ParameterizedTypeName.get(List.class, String.class), "strings")
16
        .addStatement("$T.sort($N, $L)", Collections.class, "strings", comparator)
17
        .build())
18
    .build();

生成代码

1
void sortByLength(List<String> strings) {
2
  Collections.sort(strings, new Comparator<String>() {
3
    @Override
4
    public int compare(String a, String b) {
5
      return a.length() - b.length();
6
    }
7
  });
8
}

定义匿名内部类的一个特别棘手的问题是参数的构造。在上面的代码中我们传递了不带参数的空字符串。TypeSpec.anonymousClassBuilder("")。

注解

注解使用起来比较简单

1
MethodSpec toString = MethodSpec.methodBuilder("toString")
2
    .addAnnotation(Override.class)
3
    .returns(String.class)
4
    .addModifiers(Modifier.PUBLIC)
5
    .addStatement("return $S", "Hoverboard")
6
    .build();

生成代码

1
  @Override
2
  public String toString() {
3
    return "Hoverboard";
4
  }

通过AnnotationSpec.builder() 可以对注解设置属性：

1
MethodSpec logRecord = MethodSpec.methodBuilder("recordEvent")
2
    .addModifiers(Modifier.PUBLIC, Modifier.ABSTRACT)
3
    .addAnnotation(AnnotationSpec.builder(Headers.class)
4
        .addMember("accept", "$S", "application/json; charset=utf-8")
5
        .addMember("userAgent", "$S", "Square Cash")
6
        .build())
7
    .addParameter(LogRecord.class, "logRecord")
8
    .returns(LogReceipt.class)
9
    .build();

代码生成如下

1
@Headers(
2
    accept = "application/json; charset=utf-8",
3
    userAgent = "Square Cash"
4
)
5
LogReceipt recordEvent(LogRecord logRecord);

注解同样可以注解其他注解，通过$L引用如

1
MethodSpec logRecord = MethodSpec.methodBuilder("recordEvent")
2
    .addModifiers(Modifier.PUBLIC, Modifier.ABSTRACT)
3
    .addAnnotation(AnnotationSpec.builder(HeaderList.class)
4
        .addMember("value", "$L", AnnotationSpec.builder(Header.class)
5
            .addMember("name", "$S", "Accept")
6
            .addMember("value", "$S", "application/json; charset=utf-8")
7
            .build())
8
        .addMember("value", "$L", AnnotationSpec.builder(Header.class)
9
            .addMember("name", "$S", "User-Agent")
10
            .addMember("value", "$S", "Square Cash")
11
            .build())
12
        .build())
13
    .addParameter(LogRecord.class, "logRecord")
14
    .returns(LogReceipt.class)
15
    .build();

生成代码

1
@HeaderList({
2
    @Header(name = "Accept", value = "application/json; charset=utf-8"),
3
    @Header(name = "User-Agent", value = "Square Cash")
4
})
5
LogReceipt recordEvent(LogRecord logRecord);

注释

javadoc

0x03 后续#

在javapoet之前有javawriter，但javapoet有着更强大的代码模型，并且对类的理解更加到位，因此推荐使用javapoet

0x00 概述#

0x01 简单使用#

0x02 使用进阶#

0x03 后续#

参考文章#