Forest 除了能用生命周期来自定义注解外，也允许您把已有的 Forest 注解组合成一个新的注解

组合一个注解

/**
 * 用Forest组合注解实现一个自定义的请求头注解
 * 此注解加上了 @Headers 注解，并为注解的参数赋了值
 * 那么以后使用此注解的接口和方法，会自动添加上 @Headers 注解以及它的参数值
 */
@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.METHOD, ElementType.TYPE})
// 被组合的注解
@Headers({
        "Accept: text/plain",
        "Content-Type: application/json",
        // 在组合注解中可以在模板字符串中引用变量
        // 它会从全局变量或方法的参数中获取变量值
        "Token: ${token}"
})
public @interface MyHeaders {
}

使用组合注解的方法

// 该方法使用了自定义的组合注解 @MyHeaders
// 所以该方法发送的请求会自动添加以下请求头:
// Accept: text/plain
// Content-Type: application/json
// Token: xxx (从形参 token 中传入的值)
@Get("/data")
@MyHeaders
String getData(@Var("token") String token);

注意

组合注解目前无法在字符串模板中引用自身的注解属性

如需要定义和解析注解的属性，请使用《自定义注解》

组合多个注解

Forest 还可以组合2个及2个以上的 Forest 注解

/**
 * Forest 可以同时组合多个注解
 * 如方法使用该自定义的 @MySite 注解
 * 那么就等同使用这里被组合的 @Headers 注解和 @Address 注解
 * 以及它们的参数值
 */
@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.METHOD, ElementType.TYPE})
// 组合第一个注解
@Headers({
        "Accept: text/plain",
        "Content-Type: application/json"
})
// 组合第二个注解
// 可以从全局变量或方法参数中获取变量值
@Address(host = "${my-site.host}", port = "${my-site.port}")
public @interface MySite {
}

注意

定义组合注解的时候要注解不要组合自身，以及组合过自身的其它注解，以免引起循环引用

属性重写

注解的组合关系，类似于 Java 类的继承关系，继承关系中有多态（比如方式和属性的重写）， Forest 的组合注解也有类似的能力

从v1.5.33版本开始，Forest 提供了@OverrideAttribute注解，将被该注解标识的注解属性定义可重写的注解属性，它将覆盖被组合注解中的同名属性值

要重写组合注解的属性，要满足以下三个条件:

1. 注解定义时，要加上@@RequestAttributes注解，以标识该注解的属性可以被解析

2. 属性名要和被组合的注解中的属性名一致

3. 属性定义上要加上@OverrideAttribute注解

@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.METHOD, ElementType.TYPE})
// 加上 @RequestAttributes 注解才能解析注解中定义的属性
@RequestAttributes
// 被组合的 @Address 注解
@Address
public @interface MySite {
    
    // 重写 @Address 注解的 host 属性
    @OverrideAttribute
    String host();
    
    // 重写 @Address 注解的 port 属性
    @OverrideAttribute
    int port();
}

此时，使用@MySite，并为其 host 属性和 port 属性赋值时，将会自动覆盖被组合的@Address注解的 host 属性和 port 属性

// 等价于 @Address(host = "localhost", port = 8080)
@MySite(host = "localhost", port = 8080)
public interface MyClient {
    ...
}