ExecutableElement与参数的封装关系不对称是否为API设计问题

（本问题标记有annotation-processing标签，以下讨论围绕javax.lang.model.element包的相关概念展开。）

Element#getEnclosedElements()的官方文档有如下重点标注内容：

类或接口被视为封装了其直接声明的字段、方法、构造器、记录组件、成员类与成员接口；包封装其内部的顶层类与接口，但不封装子包；模块封装其内部的包。[…] 其他种类的元素当前不被视为封装任何元素….

按照该规则，若对ExecutableElement调用getEnclosedElements()，返回的List应始终为空（至少在javax.lang.model.element的规则变更前如此）。

但Element#getEnclosingElement()的文档又有如下说明：

• 若当前元素为方法或构造器参数，将返回声明该参数的可执行元素。

也就是说，对于ElementKind为PARAMETER的VariableElement实例，调用其getEnclosingElement()方法，会返回对应的ExecutableElement实例（例如ElementKind为METHOD的方法元素）。类型参数的封装元素获取逻辑也存在相同特性。

这种双向关系的不对称设计十分反常，该特性是官方有意设计，还是API开发时的疏漏？

这是官方有意做出的明确设计，并非API开发疏漏。

两个方法从设计之初就没有定义成对称的双向导航关系，二者的语义边界完全不同：

• getEnclosedElements()的核心语义是返回当前元素作为成员声明容器时，直接持有的、属于自身成员范畴的元素。它枚举的是有正式“成员”身份的子元素：类的字段、方法是类的成员，包下的顶层类是包的成员，所以会被该方法返回。
  而方法、构造器这类可执行元素本质是代码逻辑块，它的参数、类型参数、内部定义的局部变量、局部类都不属于“方法的成员”——Java语言规范里从来没有“方法成员参数”这类定义，这些元素只是方法签名或方法实现的组成部分，不具备成员身份，因此自然不会被getEnclosedElements()返回。
• getEnclosingElement()的核心语义是返回当前元素在语法结构上，直接所属的词法作用域宿主。它只需要回答“当前元素的声明代码写在哪个元素的定义块内部”，完全不要求宿主必须将当前元素认作自身成员。
  方法参数、方法上声明的类型参数，从词法作用域上确实定义在对应的可执行元素内部，因此getEnclosingElement()返回所属的ExecutableElement是完全符合语义的。

实践提示 #

如果需要获取ExecutableElement对应的参数、类型参数，不要依赖getEnclosedElements()，直接调用ExecutableElement提供的专属接口getParameters()、getTypeParameters()即可，这也是官方API设计中为这类非成员子元素预留的标准获取路径。

内容的提问来源于stack exchange，提问作者Laird Nelson