自定义注解#

自定义注解机制用来让反射获取标注内容，目的是在类型元数据之外提供更多的有用信息，以支持更复杂的逻辑

自定义注解可以用在类型声明、成员变量声明、成员属性声明、成员函数声明、构造函数声明、构造器声明、(前面提到的函数里的)函数参数声明上

开发者可以通过 自定义类型标注@Annotation方式创建自己的自定义注解

@Annotation只能修饰class，并且不能是abstract或open或sealed修饰的class

当一个class声明它标注了@Annotation，那么它必须要提供至少一个const init函数，否则编译器会报错

下面是一个自定义注解的例子:

1
@Annotation
2
public class CustomAnnotation {
3
    let name: String
4
    let version: Int64
5

6
    public const init(name: String, version!: Int64 = 0) {
7
        this.name = name
8
        this.version = version
9
    }
10
}
11

12
// 使用标注
13
@CustomAnnotation["Sample", version: 1]
14
class Foo {}

注解信息需要在编译时生成信息绑定到类型上，自定义注解在使用时必须使用const init构建出合法的实例

我们规定:

• 注解声明语法与声明宏语法一致，后面的[]括号中需要按顺序或命名参数规则传入参数，且参数必须是const表达式

• 对于拥有无参构造函数的注解类型，声明时允许省略括号

1
@Annotation
2
public class MyAnnotation { ... }
3

4
@MyAnnotation                         // ok
5
class Foo {}

对于同一个注解目标，同一个注解类不允许声明多次，即 不可重复

编译器不承诺生成的多个Annotation元数据的顺序跟代码中Annotation的标注顺序保持一致

1
@MyAnnotation
2
@MyAnnotation                         // error
3
class Foo {}
4

5
@MyAnnotation
6
@MyAnnotation2
7
class Bar {}

Annotation不会被继承，因此一个类型的注解元数据只会来自它定义时声明的注解

如果需要父类型的注解元数据信息，需要开发者自己用反射接口查询

1
@BaseAnno
2
open class Base {}
3

4
@InterfaceAnno
5
interface I {}
6

7
@SubAnno
8
class Sub <: Base & I {}              // Sub 只有 SubAnno 注解信息

当单独使用@Annotation修饰一个类时, 此类就是一个注解类, 需要拥有一个const init, 且此构造函数的参数列表就是注解可以传入的参数列表

自定义了注解类之后, 就可以通过类名使用自定义注解了, 不允许多次重复对同一目标使用同一注解

自定义注解不会被继承

自定义注解, 可通过反射机制实现具体功能, 这是一个C++不原生具备的语法

自定义注解可以限制自己可以使用的位置，这样可以减少开发者的误用，这类注解需要在声明@Annotation时标注target参数

target参数需要以变长参数的形式传入该自定义注解希望支持的位置，target接收的参数是一个Array<AnnotationKind>

可以限制的位置包括:

• 类型声明(class、struct、enum、interface)

• 成员函数/构造函数中的参数

• 构造函数声明

• 成员函数声明

• 成员变量声明

• 成员属性声明

1
public enum AnnotaitionKind {
2
    | Type
3
    | Parameter
4
    | Init
5
    | MemberProperty
6
    | MemberFunction
7
    | MemberVariable
8
}
9

10
@Annotation[target: [Type, MemberFunction]]
11
class CustomAnnotation{}
12
@Annotation
13
class SubCustomAnnotation{}
14

15
@Annotation[target: []]
16
class MyAnno{}

当没有限定target的时候，该自定义注解可以用在以上全部位置

当限定target时，只能用在声明的列表中

自定义注解, 可以在定义时通过在参数列表中设置参数target的值, 来限制此注解的使用位置

即:@Annotation[target: [Array<AnnotationKind>]], AnnotationKind是仓颉内置的一个枚举类型