【Lombok】onX | 为Lombok注解添加自定义注解

一、实验性功能说明

onX是在lombok v0.11.8中作为实验性功能引入的。

实验因为：

• 丑陋的语法。这个功能的语法不是最佳的，但它是可能工作的最不曲折的语法（目前！）。
• 可能java 9会提供（更多）更好的方式来支持这个功能。
• 不确定因素。未来版本的javac可能会破坏这个功能，我们可能无法恢复它。

当前状态：不确定–目前我们觉得这个功能不能脱离实验状态。

二、简介

这个功能被认为是 “变通状态”–它的存在是为了让那些没有这个功能就无法工作的lombok用户无论如何都能使用这个功能。如果我们找到一个更好的方法来实现这个功能，或者未来的某个java版本引入了一个替代策略，这个功能可以在没有一个合理的废弃期的情况下消失。另外，这个功能可能在未来的javac版本中无法使用。使用时请自行斟酌。

大多数使lombok生成方法或构造函数的注解可以被配置为使lombok在生成的代码中的元素上添加自定义注解。

@Getter、@Setter和@Wither支持onMethod选项，这将把列出的注释放在生成的方法上。

@AllArgsConstructor、@NoArgsConstructor和@RequiredArgsConstructor支持onConstructor选项，它将把列出的注释放在生成的构造函数上。

除了onMethod之外，@Setter和@Wither还支持onParam；列出的注解将被放在生成的方法的唯一参数上。@EqualsAndHashCode也支持onParam；列出的注释将被放置在生成的equals方法的唯一参数上，以及任何生成的canEqual方法。

语法有点奇怪，取决于你所使用的javac。

在javac7上，要使用3个onX特性中的任何一个，你必须用@__(@AnnotationGoesHere)来包装要应用到构造函数/方法/参数的注释。要应用多个注释，请使用@__({@Annotation1, @Annotation2})。注释本身显然也可以有参数。

在javac8及以上版本中，你可以在onMethod、onParam或onConstructor后面加一个下划线。

三、示例比较

1. Lombok 写法

import lombok.AllArgsConstructor;
import lombok.Getter;
import lombok.Setter;

import javax.inject.Inject;
import javax.persistence.Id;
import javax.persistence.Column;
import javax.validation.constraints.Max;

@AllArgsConstructor(onConstructor=@__(@Inject))
public class OnXExample {
//  @Getter(onMethod=@__({@Id, @Column(name="unique-id")})) //JDK7
//  @Setter(onParam=@__(@Max(10000))) //JDK7
  @Getter(onMethod_={@Id, @Column(name="unique-id")}) //JDK8
  @Setter(onParam_=@Max(10000)) //JDK8
  private long unid;
}

2. Java 标准写法

import javax.inject.Inject;
import javax.persistence.Id;
import javax.persistence.Column;
import javax.validation.constraints.Max;

public class OnXExample {
  private long unid;

  @Inject
  public OnXExample(long unid) {
    this.unid = unid;
  }

  @Id @Column(name="unique-id")
  public long getUnid() {
    return unid;
  }

  public void setUnid(@Max(10000) long unid) {
    this.unid = unid;
  }
}

四、支持的配置项

lombok.onX.flagUsage = [warning | error] (默认: not set)
如果已配置，Lombok会将onX的任何使用标记为警告或错误。

五、附属说明

这个奇怪的语法的原因是为了让这个功能在javac 7编译器中工作；@__类型是对注解类型__（双下划线）的注解引用，它实际上并不存在；这使得javac 7由于错误而延迟中止编译过程，因为有可能一个注解处理器后来会创建__类型。相反，lombok应用了注解并删除了引用，这样错误就不会真正发生。重点是。__类型必须不存在，否则这个特性就不能工作。在罕见的情况下，__类型确实存在（并且被导入或在包中），你可以简单地添加更多的下划线。技术上来说，任何不存在的类型都可以工作，但是为了保持一致性和可读性，并捕捉错误的使用，如果’wrapper'注解除了一系列下划线之外，lombok认为这是一个错误。

在javac8中，上述功能应该工作，但是由于javac8中的一个bug，它没有工作。然而，从javac8开始，如果参数名在注解类型中不存在，编译会进行到lombok可以修复它的阶段。

重申：这一特征随时可能消失；如果您使用此功能，当我们找到更好的实现此功能的方法时，或者如果javac的未来版本迫使我们在没有其他选择的情况下完全删除此功能时，请准备好调整代码。

onX参数在任何类型范围的变体上都是不合法的。例如，一个类上的@Getter注解不支持onMethod。

参考文献

【1】onX | Sup dawg, we heard you like annotations, so we put annotations in your annotations so you can annotate while you’re annotating.