注解、反射与元数据驱动：把声明编译成受控计划
先看两个很像、根因却完全不同的现场。第一个现场是新处理器已经合并，类上也明明写了注解，服务启动后路由表里却没有它；第二个现场是插件可以正常装载和调用，但每热更新一次，元空间就再涨一截，旧插件始终卸不掉。
这时只盯着“反射有没有扫到”通常会越查越乱。注解并不会自己执行代码，它只提供一份 metadata。框架还要把 metadata 发现出来，校验并编译成 plan，把 plan 放进与组件生命周期一致的 cache，业务请求最后才会 invoke。第一个现场可能断在 metadata 或 plan，第二个现场大多藏在 cache；每一段都必须留下独立证据。
元数据只有变成调用计划才会生效
故障定位要沿着元数据怎样变成调用计划、访问能力由谁授予、启动与热路径怎样分工、缓存为什么可能阻止类卸载一直追下去。@Retention(RUNTIME)、@Target、可重复与继承语义是这条链的输入契约，不需要扩成注解 API 手册。
Spring 容器、AOP、字节码增强和编译期注解处理拥有各自的发现、链接与生命周期，不能直接套用运行时反射缓存的结论。
类、模块与加载器共同决定元数据身份
理解 Java 类、方法、模块与类加载器，并能使用 JDK 17 或更高版本运行仓库示例。版本、发行商与 --release 的选择先阅读Java 长期版本基线。
先沿着一条请求看清完整链路
如果一次业务请求进来后，框架才去遍历类、读取注解、检查签名，再临时决定调用哪个方法，请求延迟和失败位置都会变得不可预测。稳妥的实现会把这些工作提前到服务启动或插件装载阶段，将有限候选集编译成不可变计划。请求真正到来时，只做查找和调用。
图里每一段都对应一种不同现场。metadata 是声明输入，先要证明它确实进入了运行时可见的 class 文件，落点也符合框架约定。随后 plan 把重复键、方法签名和访问能力一次性校验掉。cache 把已经链接好的计划发布给请求线程，invoke 才执行目标行为。把这四段混成一个“scan”方法，日志里就只会剩下一句“扫描失败”，既无法排除构建问题，也无法判断权限问题。
第一步先别进框架，检查 class 文件里到底有没有注解
源码里看得见 @Route，不代表运行时也看得见。注解接口定义的是结构化数据格式，编译器会把注解类型、元素名和元素值写入 class 文件属性。@Retention(SOURCE) 只留在源码工具阶段；CLASS 可以进入 class 文件，但运行时反射不保证可见；只有 RUNTIME 才会进入 RuntimeVisibleAnnotations 等运行时可见属性。这里最容易踩的坑是 Retention 默认值恰好是 CLASS。如果运行时注解漏写了 RUNTIME，问题不是扫描器“偶尔漏扫”，而是反射输入从一开始就不存在。
@Target 决定元数据附着位置。方法声明上的注解与返回类型上的 TYPE_USE 注解位于不同 classfile 属性，也要从不同反射入口读取；框架若只扫 Method.getAnnotations()，不会自动得到 getAnnotatedReturnType() 上的数据。这里的架构含义不是记住两个 API，而是先定义解释器接受哪一种元数据位置，再用 classfile 和契约测试证明编译产物满足约定。
可重复注解会通过容器注解表达。消费者若承诺支持重复声明，应使用能展开容器的查询语义，并对重复键、顺序和冲突给出自己的规则。从单值注解升级为可重复注解会改变旧查询方式看到的结果，因此它是注解契约的兼容性变更，不是无成本语法增强。
@Inherited 的范围更窄：它只影响类声明上的注解，并沿超类链工作；接口注解、方法、字段和构造器不会因此继承。覆盖方法的元数据如何合并、接口与实现类谁优先，必须由框架显式定义。若解释器把“语言层继承”与“框架层合并”混为一谈，同一声明在代理类、子类和接口入口上会得到不同计划。
反射展示的是 JVM 已加载实体，不是源码文本。编译器可能产生 bridge 或 synthetic 成员，方法返回顺序也没有业务稳定性保证。计划生成器应过滤不接受的合成成员，以声明类、名称和 JVM 描述符构造稳定身份，再按显式优先级排序。若源码参数名参与元数据语义，还要把编译参数是否保留参数名纳入构建契约，不能假定生产 class 文件与 IDE 中看到的源码信息相同。
确认 metadata 没问题后，才轮到 plan。它不是一个裸 Method，而是经过校验的执行描述，里面至少有稳定路由键、目标成员、参数适配方式和调用能力。重复键、非法签名或不可访问成员应在这里直接让启动失败。若框架记录一条 warning 后继续，部署看似成功，真正的故障却会拖到第一笔命中该路由的请求。计划发布后保持不可变，配置变更时原子替换整份快照，请求线程就不会读到一半新、一半旧的状态。
接着才是 cache。它的目的不是“加一个 Map 提速”，而是把昂贵的发现和链接与请求热路径隔开。热路径只按稳定键取得计划并执行，不再重新解释注解。这个 Map 如果放错生命周期，恰恰就是插件卸不掉的起点，后面会专门验证。
第二步看框架在哪一段丢了处理器
框架日志显示“扫描完成”仍然不够，因为大家口中的扫描至少包含发现、索引、链接和发布四段。发现阶段只从模块清单、包索引或显式注册表拿到候选 class 名称，不应该顺手初始化所有类。候选数在这里就从预期的 80 个变成 8 万个，启动慢的原因已经出现，不必继续怀疑 MethodHandle。
索引阶段读取 classfile 或已加载类型的 metadata，先形成与执行能力无关的描述符。构建期生成索引可以省掉运行时遍历，但启动时必须核对索引版本和实际制品；否则旧索引会稳定地遗漏新处理器。链接阶段才加载必要类型，校验重复项、方法签名和访问权限，并创建 Method、Constructor 或 MethodHandle。最后，发布阶段把一组完全验证的计划作为不可变快照交给缓存，业务流量从此才能看见它。
现在回到“加了注解却没生效”的现场。先对照发现阶段的候选清单：候选里没有目标类，就检查包边界、模块清单和索引版本；候选里有类、描述符里没有注解，就回到 classfile 保留与读取位置；描述符正确、计划未发布，再看重复键、签名和访问校验。四段若被一个 catch (Exception) { continue; } 包住，关键处理器也会被悄悄跳过。可选插件可以隔离失败，核心处理器链接失败则应阻断启动，这两者必须在注册时就区分。
多模块或插件系统还要记录类型由哪个类加载器定义。线程上下文类加载器只是一种发现提示，不应成为计划身份；相同全限定名在两个插件中可以合法共存。若框架把类名当全局唯一键，轻则路由串线，重则把高权限模块创建的执行能力交给低权限插件。
先用仓库里的最小路由器把这条链跑一遍。完整源码位于 examples/backend-development/java/annotations-reflection/MetadataRouterDemo.java。它故意在一个方法上放了两个可重复路由注解，启动时展开并生成计划，随后缓存 MethodHandle 再调用。进入 examples/backend-development/java/annotations-reflection/ 后执行：
mkdir -p out
javac --release 17 -Xlint:all -Werror -d out MetadataRouterDemo.java
java -cp out example.MetadataRouterDemo稳定输出如下，member 的空白差异不影响判断：
component=base-handler
plan=order.create member=public java.lang.String example.MetadataRouterDemo$Handler.execute(java.lang.String) result=handled:payload
plan=order.retry member=public java.lang.String example.MetadataRouterDemo$Handler.execute(java.lang.String) result=handled:payload两条计划的顺序和结果同时证明重复注解已经展开、启动期计划已经完成链接。若这里只有一个路由，先不要改调用器，应该检查重复注解的容器查询语义。
程序自身日志只能证明一条行为路径，还要从编译产物和访问边界各取一份独立证据：
# 1. 产物证据：运行时注解是否真正进入 class 文件
javap -v -classpath out 'example.MetadataRouterDemo$Handler'
# 2. 行为证据：重复注解是否被展开并生成稳定计划
java -cp out example.MetadataRouterDemo
# 3. 边界证据：强封装目标是否拒绝深反射
java -cp out example.MetadataRouterDemo illegal-access第一条命令的输出中应该能找到 RuntimeVisibleAnnotations；PowerShell 可以用 Select-String -Pattern RuntimeVisibleAnnotations -Context 0,12 缩小范围。class 文件里没有这一项，就回去修注解声明或构建过程。产物里有、路由输出不对，才检查查询和合并规则。第三条故意访问 JDK 私有成员，默认应看到 trySetAccessible=false 和 InaccessibleObjectException。这是权限边界生效的证据，不应该为了把测试“修绿”而扩大开放面。
扫描到了却调用失败，下一步查访问能力
有一种现场很容易被误判：启动日志已经打印了目标方法，调用时却失败。能发现成员只证明 metadata 和查找路径存在，不代表调用方已经获得执行能力。Java 访问修饰符、模块读取关系、包的 exports / opens 以及 MethodHandles.Lookup 共同决定结果。trySetAccessible() 返回 false 或抛出 InaccessibleObjectException，说明当前架构边界不允许深反射，不是“反射偶尔失灵”。
运行 java -cp out example.MetadataRouterDemo illegal-access 可观察 JDK 17+ 强封装下对 String 私有成员的访问失败。若部署参数使用 --add-opens，结果可能改变；这证明能力来自部署授权。长期方案应优先使用公开 API 或由目标模块提供明确适配入口。确需开放时，只开放给指定消费模块，并把开放项纳入升级清单，不能把 ALL-UNNAMED 当默认修复。
排查时先保留原始异常类型。NoSuchMethodException 通常表示查找描述与实际类型模型不符，此时比较声明类、名称和 JVM 描述符；IllegalAccessException 表示已经找到成员，但调用方没有语言或模块访问权；trySetAccessible() 返回 false / InaccessibleObjectException 则把问题进一步收窄到包没有开放。只有 InvocationTargetException 表示已经进入目标方法，真正失败位于它的 cause。若框架把这些全部改写成 handler execute failed，运维只能靠猜。
MethodHandles.Lookup 把调用者身份与允许的查找模式显式化，创建出的句柄可以视为能力令牌。publicLookup()、普通 lookup() 和经授权的 privateLookupIn() 能力不同；获取私有 lookup 仍受模块开放关系约束。反射的 Method 也受访问检查控制，只是能力建立和调用时机的表现不同。框架需要记录“计划使用何种能力链接”，而不是在失败后依次尝试 setAccessible、privateLookupIn 和 JVM 参数直到能运行。
反射对象或 MethodHandle 一旦创建，便携带可执行能力。它们不应进入用户可控注册表，也不能让外部输入直接选择类名、成员名或表达式。元数据值必须经过长度、格式、冲突和允许类型校验；扫描到的候选制品也必须来自受信构建链。
服务启动变慢时，不要先把反射都换成 MethodHandle
另一个常见现场是升级框架后启动多了十几秒，团队第一反应是“反射太慢，换 MethodHandle”。这个判断跳过了真正的运行过程。元数据驱动把显式注册的部分成本搬到了启动期，候选枚举、classfile I/O、类加载甚至类初始化、注解解析、语义校验和调用链接都可能占时间。先给每一阶段计时，同时记录候选类、过滤类、成功计划和失败计划数量，才知道该优化哪一段。扫描整个 classpath 导致候选从几百变成几万时，更换调用 API 对启动几乎没有帮助。
缓存也有生命周期风险。全局静态 Map 若强引用插件的 Class、Method 或 MethodHandle，就会连同类加载器一起保活，造成热部署后的元空间增长。插件计划应由插件生命周期容器持有并在卸载时整体释放；跨生命周期缓存才考虑 ClassValue 或弱引用，并用卸载实验验证，而不是只凭数据结构名称判断安全。
缓存键至少要回答三个问题：同一个符号由谁定义、按什么解释器版本生成、在什么配置作用域内有效。一个可审计的逻辑键可写成 (definingClassLoader, declaringClass, JVM descriptor, interpreterVersion, policyFingerprint)。真正实现不一定把类加载器直接放入强引用键，但这些维度不能消失。若配置改变了默认值、冲突优先级或访问策略，仅以 Method 为键复用旧计划会产生语义陈旧。
弱键也不是自动卸载保证。若 value 中的 MethodHandle、适配器 lambda、注解代理或诊断对象反向强引用目标类，缓存仍形成强引用环路；线程本地变量、调度任务和监听器也可能把整个插件容器挂在宿主生命周期上。卸载测试应重复装载和卸载隔离类加载器，释放生命周期容器，触发受控 GC 后借助 JFR、类卸载日志或堆分析确认旧 loader 可回收。生产上同时观测已加载类数、卸载类数和元空间趋势。
启动和热路径成本要分别核算
启动成本可近似拆成：候选枚举与 classfile I/O、类型加载/验证、可能发生的类初始化、注解对象解析、语义校验、调用链接和计划发布。热路径成本则主要是键构造、缓存查找、参数适配、实际调用和异常包装。两条路径目标不同：启动期允许较重校验以换取故障前移；热路径要求不扫描、不重新解释、尽量不分配临时描述对象。
构建期索引能降低候选枚举与 classfile 读取，但会增加构建插件、增量编译和索引一致性成本。延迟链接可以缩短启动，却把签名或访问错误推迟到首个请求。大型服务可以对低频可选扩展延迟链接，对核心请求处理器仍在启动期完整验证。这个选择应由启动预算、首请求延迟和失败可接受时间共同决定，不能只追求一个启动数字。
并行扫描也不是免费加速。类加载锁、磁盘读取、类初始化副作用和共享索引竞争都可能让并行度超过收益。先用 JFR 或阶段计时定位瓶颈，再决定减少候选、使用索引、并行解析还是延迟可选模块。性能验收至少比较冷启动、缓存命中稳态、计划重载和异常路径，并在实际 JDK、模块参数与类加载器拓扑下执行。
是否用 MethodHandle 应由调用形态和基准决定。稳定高频计划可以在启动期链接精确类型句柄；低频管理操作使用核心反射更直接。JDK 18 起核心反射已由 method handle 重构，并不意味着机械替换 Method.invoke 一定提速。首先消除热路径扫描和重复解析，通常比更换调用 API 更重要。
工程验收不应写一个脱离服务规模的“扫描必须小于 500 毫秒”。先固定同一制品、JDK、容器额度和候选集合，再比较这些不变量与趋势：
| 观测项 | 采集位置 | 通过条件 | 失败指向 |
|---|---|---|---|
| 候选数、过滤数、计划数 | discovery / index / publish 阶段计数 | 同一制品重复启动结果一致，核心计划不缺失 | 扫描边界或索引漂移 |
| 重复键、签名失败、访问失败数 | link 阶段分类计数 | 核心扩展为 0；可选扩展有明确隔离名单 | 契约或模块授权错误 |
| 冷启动各阶段耗时 | 阶段计时或 JFR | 优化后瓶颈阶段下降，非目标阶段没有同步恶化 | 优化对象判断错误 |
| 热路径计划命中率 | invoke 前的低基数指标 | 稳态不再扫描或重新链接 | 缓存键或生命周期错误 |
| 卸载代际与旧 loader 存活数 | ReferenceQueue、JFR 或堆引用链 | 完整卸载后旧代最终归零，元空间不随代际单调增长 | 宿主强引用未释放 |
这些条件刻意不用跨项目魔法数字。绝对预算由服务启动 SLO 和流量模型决定，但“同一制品的计划集合稳定”“热路径不重新解释”“释放后旧代最终归零”是可以自动验证的架构不变量。
再回到选型：什么情况值得引入这层间接性
元数据驱动适合有限、稳定、需要扩展的声明面，例如命令注册、序列化映射和校验规则。它让扩展者声明“是什么”，由统一解释器生成行为。前提是候选范围有上界，计划能在启动期完整校验，且失败可阻断发布。
若领域核心只有少量固定分支，直接代码通常更容易导航、重构和受类型系统保护；若规则依赖复杂运行时上下文、需要逐步调试或包含高权限动作，隐藏在注解后的控制流也会放大审计成本。不要仅为了减少几行注册代码引入扫描器、解释器和缓存生命周期。
选型确定后，排障顺序也随之固定：先确认 class 文件中是否有 metadata，再核对候选范围和查询语义，然后检查计划校验与模块访问，最后才看缓存版本和目标调用异常。下面用三个现场把这条顺序再走一遍。
源码有注解，计划却是空的
第一步运行 javap -v 查保留属性。没有运行时可见属性就回到声明和编译过程；有属性再看框架读的是声明注解还是类型使用注解，是否错误期待接口或方法继承。两项都正确，最后对照候选清单和过滤日志，找到目标类在哪个阶段消失。这里不要先清缓存或盲目扩大扫描包，那会改变现场，甚至把启动成本进一步放大。
本地可以调用，生产模块环境却失败
先比较本地和生产到底运行在 classpath 还是 module path，再通过 java --describe-module、启动参数和包开放关系确认调用方与目标模块。记录声明类、成员描述符以及链接使用的 Lookup，本地 unnamed module 的成功不能证明生产权限正确。修复优先落到公开适配入口；确实需要深反射时，只增加最小 opens，并在没有多余 --add-opens 的环境中做回归。
每次热更新后元空间都上升
先为每代插件记录类加载器标识和计划数量。卸载时停止插件创建的线程与定时任务，注销监听器，再释放整个计划容器。若旧 loader 仍然存在，用堆引用链向上查：常见所有者是宿主静态 Map、ThreadLocal、MethodHandle 或注解代理。修复后重复装载和卸载，观察类卸载计数和元空间能否回落。提高 Metaspace 上限只能推迟下一次 OOM，无法修复生命周期错误。
框架设计取舍
运行时反射的优势是接入简单、可依据运行时组合计划，代价是错误较晚、模块权限和冷启动成本更明显。构建期生成注册表或代码可以让类型错误前移、减少运行时扫描，并更适合原生镜像的闭世界约束；代价是构建链复杂、增量编译与多模块合并需要额外治理。显式注册最容易导航和审计，适合扩展点不多、权限较高的核心领域。
三者可以组合：构建期产生候选索引，启动期验证并链接，运行时只执行计划；对无法生成的插件保留受限扫描入口。关键是只有一套冲突、合并和权限语义，不能让代码生成路径与反射路径各自解释同一注解，否则同一制品在不同部署模式下会产生不同系统行为。
元数据契约也需要版本治理
注解看起来像内部声明，实际上常被多个模块、构建插件和运行时解释器共同依赖。新增带默认值的可选元素通常比新增必填元素安全，但默认值本身仍会改变旧制品在新解释器下生成的计划。删除元素、缩窄 Target、改变 Retention、修改重复项合并顺序或从显式声明改为继承，都应按公共契约变更评审。
计划中应记录解释器版本和策略指纹，启动时输出“制品元数据版本 → 解释器版本 → 生成计划版本”的可追踪关系。滚动升级期间若新旧实例对同一注解解释不同，路由、校验或序列化行为会出现流量相关漂移。兼容策略可以是解释器同时支持相邻版本、构建期迁移元数据，或发布前一次性升级制品；不能依赖缓存逐渐过期来完成语义迁移。
对于跨团队扩展点，应提供一个小型兼容性样本库：旧版注解制品不重新编译，直接交给新版解释器生成计划，并与期望快照比较；新版制品也要在允许的旧解释器上明确失败或降级。这样才能区分源码兼容、二进制可加载与解释语义兼容，避免“编译通过”掩盖运行计划变化。
元数据系统的可观测性同样围绕计划而不是反射调用次数建立。启动报告应能回答每个扩展点发现了什么、为何过滤、最终发布哪一版计划；运行指标只记录低基数计划族、缓存命中、调用延迟和失败族，不能把任意类名或路由值全部做成标签。诊断端点若展示成员签名与模块信息，要受管理权限保护，避免把内部结构变成攻击者的枚举入口。
把这条链落实到代码审查和发布
代码评审先从注解契约开始。保留策略、落点、重复和继承语义都要有契约测试，不能依赖反射返回顺序。随后审查候选是否来自白名单或受控注册表，扫描数量与耗时有没有上限。启动测试要故意制造重复键、非法签名、关键处理器缺失和访问失败，确认核心计划不会被静默跳过。
性能评审则沿 plan 和 cache 往后看：请求热路径只能查询不可变计划，缓存键必须区分类型身份和解释器策略，插件卸载测试要证明旧类加载器可回收。私有访问、特殊 Lookup 和 --add-opens 都进入权限与 JDK 升级清单，外部输入不能选择任意类或成员。
最后保留一条可控退路。扩展点数量很少或元数据解释器发生兼容故障时，可以切到显式注册或阻断该插件；不能让关键能力在告警后悄悄消失。这样一来，需求阶段定义声明面，编码阶段建立计划，测试阶段验证失败路径，发布阶段检查启动报告，维护阶段追踪缓存生命周期，架构约束才真正贯穿下来。
注解与反射边界查这些规范
JLS 25 第 9.6～9.7 节：注解接口、元注解和合法出现位置。Java SE 25 AnnotatedElement：直接、间接、关联与继承查询语义。
Java SE 25 AccessibleObject：访问检查与模块边界。
Java SE 25 MethodHandles.Lookup：方法句柄的能力模型。
JEP 403：强封装 JDK 内部 API 与 JEP 416：用 Method Handle 重构核心反射：JDK 17+ 的封装和实现背景。
结论
再遇到“注解写了却没生效”，先看 classfile，再跟着候选、描述符、链接和发布日志向前走；再遇到“插件卸不掉”，从计划缓存的生命周期和类加载器引用链往回查。这样排查时面对的是一条能取证的运行链，而不是一句含糊的“反射有问题”。元数据驱动真正值得保留的前提，也正是这条链从声明到调用都能验证、能失败、能释放。