必须用Method.getParameterAnnotations()获取参数注解，因其返回Annotation[][]可遍历每个参数的全部注解；而Method.getParameters()[i].getAnnotation()在未加-parameters编译时恒为null，且@ApiParam等注解不自动写入JVM参数属性。
Java 反射怎么拿到方法参数上的 @ApiParam 或自定义注解
必须用 Method.getParameterAnnotations()，而不是 Method.getParameters() 的 getAnnotation() —— 后者在 Java 8+ 默认返回 null，除非编译时加 -parameters 且注解声明了 @Retention(RetentionPolicy.RUNTIME)。
实操要点：
-
getParameterAnnotations()返回Annotation[][]：外层数组长度 = 参数个数，内层数组是该参数上所有注解 - 遍历每个参数的注解数组，用
instanceof或annotation.annotationType() == ApiParam.class判定目标注解 - 若用自定义注解，确保它带
@Documented @Retention(RUNTIME) @Target(PARAMETER) - Spring MVC 的
@RequestParam、@PathVariable等本身不存参数级元数据，不能直接反射读取语义；需配合HandlerMethod或 Spring 的ParameterNameDiscoverer
为什么 method.getParameters()[i].getAnnotation(ApiParam.class) 总是 null
因为 Executable.getParameters() 返回的是 Parameter 实例，其 getAnnotation() 方法仅对 @RuntimeVisibleParameterAnnotations 属性有效 —— 这依赖 javac -parameters 编译，且多数注解（如 Swagger 的 @ApiParam）并未被 JVM 自动写入该属性。
正确路径是：
立即学习“Java免费学习笔记（深入）”；
- 调用
method.getParameterAnnotations() - 对第
i个参数，遍历annotations[i]数组 - 用
annotation instanceof ApiParam拿到实例，再调((ApiParam) annotation).value() - 若用 Lombok 的
@Builder或其他字节码增强工具，确认它们未擦除参数注解（部分版本会）
生成文档时如何把注解值和 Spring 参数绑定逻辑对齐
反射只能读注解，但 Spring 实际怎么解析参数（比如 query 还是 path），得结合 @RequestMapping 的 method 和 consumes，以及参数级注解类型。不能只靠 @ApiParam 的 value() 字段猜。
建议策略：
- 先用反射提取所有参数注解（
@PathVariable、@RequestParam、@RequestBody、@ApiParam） - 按注解类型归类：含
@PathVariable→ path 参数；含@RequestParam→ query/form；含@RequestBody→ body 对象（此时再递归反射其字段） -
@ApiParam优先级低于 Spring 原生注解：若同时有@RequestParam和@ApiParam，以@RequestParam.name()为准，@ApiParam补充description和required - 注意
@RequestParam(required = false)和@ApiParam(required = false)语义一致，但前者由 Spring 执行，后者仅用于文档
性能与兼容性要注意的三个点
反射读参数注解不是高频操作，但批量扫描 Controller 类时容易卡顿，尤其在启动期。
- 缓存结果：用
ConcurrentHashMap<method list>></method>存每方法的参数文档信息，避免重复反射 - 跳过桥接方法：
method.isBridge()为 true 时直接忽略（泛型擦除生成的冗余方法） - JDK 版本差异：Java 17+ 对
Parameter.getDeclaredAnnotations()支持更稳，但依然不推荐依赖它；坚持用getParameterAnnotations()最保险
最易被忽略的是：Swagger v2 的 @ApiParam 在 Spring Boot 3 + Springdoc OpenAPI 下已失效，要切到 @Parameter 注解，且反射时得换判断逻辑 —— 这类迁移细节不查源码很容易漏掉。
