12.4.6 Java 注解处理到 KSP 参考
3 分钟阅读
12.4.6 Java 注解处理到 KSP 参考
程序元素
| Java | KSP 中最接近的设施 | 说明 |
| AnnotationMirror | KSAnnotation | |
| AnnotationValue | KSValueArguments | |
| Element | KSDeclaration / KSDeclarationContainer | |
| ExecutableElement | KSFunctionDeclaration | |
| PackageElement | KSFile | KSP 不把包建模为程序元素 |
| Parameterizable | KSDeclaration | |
| QualifiedNameable | KSDeclaration | |
| TypeElement | KSClassDeclaration | |
| TypeParameterElement | KSTypeParameter | |
| VariableElement | KSValueParameter / KSPropertyDeclaration | |
类型
KSP 要求显式的类型解析，因此 Java 中的某些功能只能由 KSType 以及解析前对应的元素来完成。
| Java | KSP 中最接近的设施 | 说明 |
| ArrayType | KSBuiltIns.arrayType | |
| DeclaredType | KSType / KSClassifierReference | |
| ErrorType | KSType.isError | |
| ExecutableType | KSType / KSCallableReference | |
| IntersectionType | KSType / KSTypeParameter | |
| NoType | KSType.isError | KSP 中不适用 |
| NullType | | KSP 中不适用 |
| PrimitiveType | KSBuiltIns | 与 Java 中的原始类型并不完全相同 |
| ReferenceType | KSTypeReference | |
| TypeMirror | KSType | |
| TypeVariable | KSTypeParameter | |
| UnionType | 不适用 | Kotlin 的每个 catch 块只有一种类型。即使是 Java 注解处理器也无法观察到 UnionType |
| WildcardType | KSType / KSTypeArgument | |
其他
| Java | KSP 中最接近的设施 | 说明 |
| Name | KSName | |
| ElementKind | ClassKind / FunctionKind | |
| Modifier | Modifier | |
| NestingKind | ClassKind / FunctionKind | |
| AnnotationValueVisitor | | |
| ElementVisitor | KSVisitor | |
| AnnotatedConstruct | KSAnnotated | |
| TypeVisitor | | |
| TypeKind | KSBuiltIns | 有些可以在 builtins 中找到，否则对 DeclaredType 请检查 KSClassDeclaration |
| ElementFilter | Collection.filterIsInstance | |
| ElementKindVisitor | KSVisitor | |
| ElementScanner | KSTopDownVisitor | |
| SimpleAnnotationValueVisitor | | KSP 中不需要 |
| SimpleElementVisitor | KSVisitor | |
| SimpleTypeVisitor | | |
| TypeKindVisitor | | |
| Types | Resolver / utils | 部分 utils 也集成到了符号接口中 |
| Elements | Resolver / utils | |
详细信息
了解 Java 注解处理 API 的功能如何通过 KSP 来实现。
AnnotationMirror
| Java | KSP 等价物 |
| getAnnotationType | ksAnnotation.annotationType |
| getElementValues | ksAnnotation.arguments |
AnnotationValue
| Java | KSP 等价物 |
| getValue | ksValueArgument.value |
Element
| Java | KSP 等价物 |
| asType | ksClassDeclaration.asType(...) 仅对 KSClassDeclaration 可用。需要提供类型实参。 |
| getAnnotation | 待实现 |
| getAnnotationMirrors | ksDeclaration.annotations |
| getEnclosedElements | ksDeclarationContainer.declarations |
| getEnclosingElements | ksDeclaration.parentDeclaration |
| getKind | 按 ClassKind 或 FunctionKind 进行类型检查和强制转换 |
| getModifiers | ksDeclaration.modifiers |
| getSimpleName | ksDeclaration.simpleName |
ExecutableElement
| Java | KSP 等价物 |
| getDefaultValue | 待实现 |
| getParameters | ksFunctionDeclaration.parameters |
| getReceiverType | ksFunctionDeclaration.parentDeclaration |
| getReturnType | ksFunctionDeclaration.returnType |
| getSimpleName | ksFunctionDeclaration.simpleName |
| getThrownTypes | Kotlin 中不需要 |
| getTypeParameters | ksFunctionDeclaration.typeParameters |
| isDefault | 检查父声明是否为接口 |
| isVarArgs | ksFunctionDeclaration.parameters.any { it.isVarArg } |
Parameterizable
| Java | KSP 等价物 |
| getTypeParameters | ksFunctionDeclaration.typeParameters |
QualifiedNameable
| Java | KSP 等价物 |
| getQualifiedName | ksDeclaration.qualifiedName |
TypeElement
| Java | KSP 等价物 |
|---|---|
getEnclosedElements | ksClassDeclaration.declarations |
getEnclosingElement | ksClassDeclaration.parentDeclaration |
getInterfaces | kotlin // 应该可以在不做解析的情况下完成 ksClassDeclaration.superTypes .map { it.resolve() } .filter { (it?.declaration as? KSClassDeclaration)?.classKind == ClassKind.INTERFACE } |
getNestingKind | 检查 KSClassDeclaration.parentDeclaration 和 inner 修饰符 |
getQualifiedName | ksClassDeclaration.qualifiedName |
getSimpleName | ksClassDeclaration.simpleName |
getSuperclass | kotlin // 应该可以在不做解析的情况下完成 ksClassDeclaration.superTypes .map { it.resolve() } .filter { (it?.declaration as? KSClassDeclaration)?.classKind == ClassKind.CLASS } |
getTypeParameters | ksClassDeclaration.typeParameters |
TypeParameterElement
| Java | KSP 等价物 |
| getBounds | ksTypeParameter.bounds |
| getEnclosingElement | ksTypeParameter.parentDeclaration |
| getGenericElement | ksTypeParameter.parentDeclaration |
VariableElement
| Java | KSP 等价物 |
| getConstantValue | 待实现 |
| getEnclosingElement | ksValueParameter.parentDeclaration |
| getSimpleName | ksValueParameter.simpleName |
ArrayType
| Java | KSP 等价物 |
| getComponentType | ksType.arguments.first() |
DeclaredType
| Java | KSP 等价物 |
| asElement | ksType.declaration |
| getEnclosingType | ksType.declaration.parentDeclaration |
| getTypeArguments | ksType.arguments |
ExecutableType
注意： 函数的
KSType只是由FunctionN<R, T1, T2, ..., TN>系列表示的签名。
| Java | KSP 等价物 |
| getParameterTypes | ksType.declaration.typeParameters、ksFunctionDeclaration.parameters.map { it.type } |
| getReceiverType | ksFunctionDeclaration.parentDeclaration.asType(...) |
| getReturnType | ksType.declaration.typeParameters.last() |
| getThrownTypes | Kotlin 中不需要 |
| getTypeVariables | ksFunctionDeclaration.typeParameters |
IntersectionType
| Java | KSP 等价物 |
| getBounds | ksTypeParameter.bounds |
TypeMirror
| Java | KSP 等价物 |
| getKind | 对原始类型、Unit 类型与 KSBuiltIns 中的类型比较，否则就是已声明类型 |
TypeVariable
| Java | KSP 等价物 |
| asElement | ksType.declaration |
| getLowerBound | 待定。仅当提供了捕获并且需要显式的边界检查时才需要。 |
| getUpperBound | ksTypeParameter.bounds |
WildcardType
| Java | KSP 等价物 |
|---|---|
getExtendsBound | kotlin if (ksTypeArgument.variance == Variance.COVARIANT) ksTypeArgument.type else null |
getSuperBound | kotlin if (ksTypeArgument.variance == Variance.CONTRAVARIANT) ksTypeArgument.type else null |
Elements
| Java | KSP 等价物 |
|---|---|
getAllAnnotationMirrors | KSDeclarations.annotations |
getAllMembers | getAllFunctions，getAllProperties 待实现 |
getBinaryName | 待定，参见 Java 规范 |
getConstantExpression | KSP 中有常量值，但没有表达式 |
getDocComment | 待实现 |
getElementValuesWithDefaults | 待实现 |
getName | resolver.getKSNameFromString |
getPackageElement | 不支持包，但可以获取包的信息。KSP 无法对包执行操作 |
getPackageOf | 不支持包 |
getTypeElement | Resolver.getClassDeclarationByName |
hides | 待实现 |
isDeprecated | kotlin KsDeclaration.annotations.any { it.annotationType.resolve()!!.declaration.qualifiedName!!.asString() == Deprecated::class.qualifiedName } |
overrides | KSFunctionDeclaration.overrides / KSPropertyDeclaration.overrides（各自类的成员函数） |
printElements | KSP 在大多数类上都有基本的 toString() 实现 |
Types
| Java | KSP 等价物 |
| asElement | ksType.declaration |
| asMemberOf | resolver.asMemberOf |
| boxedClass | 不需要 |
| capture | 待定 |
| contains | KSType.isAssignableFrom |
| directSuperTypes | (ksType.declaration as KSClassDeclaration).superTypes |
| erasure | ksType.starProjection() |
| getArrayType | ksBuiltIns.arrayType.replace(...) |
| getDeclaredType | ksClassDeclaration.asType |
| getNoType | ksBuiltIns.nothingType / null |
| getNullType | 视上下文而定，KSType.markNullable 可能有用 |
| getPrimitiveType | 不需要，请检查 KSBuiltins |
| getWildcardType | 在期望 KSTypeArgument 的地方使用 Variance |
| isAssignable | ksType.isAssignableFrom |
| isSameType | ksType.equals |
| isSubsignature | functionTypeA == functionTypeB / functionTypeA == functionTypeB.starProjection() |
| isSubtype | ksType.isAssignableFrom |
| unboxedType | 不需要 |