Hyperf注解校验必须绑定切面才能生效，注解本身仅为元数据；需注册@Aspect切面并用@PointBean配置正确切点，通过AnnotationReader读取注解参数，从方法参数而非请求体提取待校验值，失败时抛ValidationException以触发框架标准响应。
Hyperf注解校验逻辑必须绑定到切面，不能只写注解类
Hyperf 的自定义注解本身只是元数据容器，@ValidateParam 这类注解不执行任何逻辑，哪怕你写了 validate() 方法也不会自动调用。真正触发校验的，是切面（Aspect）在方法执行前读取注解、提取参数、调用验证器。所以第一步不是写注解，而是确认切面已注册且拦截范围正确。
常见错误是注解类实现了 Validatable 接口或加了 @Aspect，但没配 @PointBean 或切点表达式写错，导致切面根本没生效——此时无论注解参数怎么写，都不会报错，也不会校验，静默失效。
- 确保切面类被
@Aspect标记，并用@PointBean注册 - 切点表达式推荐用
@annotation(YourAnnotation)而非execution()，更精准 - 注解必须声明
@Target({ElementType.METHOD})和@Retention(RetentionPolicy.RUNTIME)
在切面中读取注解参数要用 MethodMatcher + Reflection
Hyperf 切面的 process 方法只提供 $proceedingJoinPoint，它不直接暴露被拦截方法的反射对象。要拿到 @ValidateParam 的 field、rule 等值，得先从 $proceedingJoinPoint->getMethodName() 和类名拼出完整方法签名，再用 Container::get(ReflectionClass::class) 或手动 new \ReflectionMethod() 获取反射实例，最后调用 getAttributes()（PHP 8+）或 getDocComment() + 解析（PHP 7.4 需降级方案）。
Hyperf 2.2+ 推荐用 Hyperf\Di\Annotation\AnnotationReader，它比原生反射更兼容框架的注解扫描机制：
// 在切面 process 方法中
$method = $proceedingJoinPoint->getMethod();
$attributes = $this->annotationReader->getAnnotations($method, ValidateParam::class);
if (empty($attributes)) {
return $proceedingJoinPoint->process();
}
$annotation = $attributes[0];
$field = $annotation->field; // string
$rule = $annotation->rule; // array|string
- 别用
$method->getAttributes()直接取，Hyperf 的注解可能未被 PHP 原生识别（尤其带配置参数时） -
AnnotationReader需在构造函数注入，不能静态调用 - 如果注解支持多个字段（如
fields={"name","email"}），解析后要映射到实际参数值，靠$proceedingJoinPoint->getArguments()拿不到命名参数，得结合ReflectionMethod::getParameters()对齐顺序
参数值提取必须匹配控制器方法签名，不能硬写 $_POST 或 request()->all()
很多人在校验逻辑里直接调 $this->request->post()，这在 HTTP 控制器里看似可行，但在命令行、WebSocket、gRPC 等场景会出错——因为 RequestInterface 不一定存在，或数据来源不是表单。正确做法是：从 $proceedingJoinPoint->getArguments() 取实参，再根据注解里的 field 名去匹配对应参数的属性或键。
例如注解写 @ValidateParam(field="user", rule={"required", "array"})，而方法签名为 public function store(User $user, Request $request)，那就该取第一个参数 $user 的实例，而不是去请求体里找 user 字段：
$args = $proceedingJoinPoint->getArguments();
$paramName = $annotation->field;
// 找第几个参数叫 $paramName（按 ReflectionParameter->getName()）
$targetArg = $this->findArgumentByName($method, $args, $paramName);
if ($targetArg instanceof ValidationRule) {
$result = $this->validator->validate($targetArg, $rule);
}
- 不要假设参数来自 HTTP 请求体；Hyperf 切面是通用的，可能拦截任意容器管理的方法
- 如果注解想校验请求体字段（如
name），应明确设计为@ValidateParam(from="request", field="name")，并在切面里分支处理 - 对数组型参数（如
array $data），$targetArg是数组，可直接传给validator()->make()；对对象，需考虑是否支持自动转数组（如toArray()或jsonSerialize()）
验证失败抛 ValidationException 并统一响应，别用 throw new Exception()
Hyperf 的 Validator 组件抛出的是 Hyperf\Validation\Exception\ValidationException，它会被框架的异常处理器自动转成 422 响应并附带错误信息。如果你手动 throw InvalidArgumentException 或其他异常，就绕过了标准流程，前端收不到 errors 字段，日志里也看不到结构化错误详情。
而且，Hyperf 默认异常处理器只捕获 Throwable，但只有 ValidationException 会触发 ResponseFactory::fail() 流程：
if (! $this->validator->validate($value, $rule)) {
$message = sprintf('Validation failed for %s: %s', $field, implode(',', $rule));
throw new ValidationException(
$this->validator->getMessages(), // 必须传 MessageBag
$this->validator->failed()
);
}
- 务必传
MessageBag实例，不能只传字符串消息；否则ResponseFactory无法序列化 - 别在切面里调
return $this->response->fail(...)—— 这会跳过后续中间件和异常处理，破坏框架一致性 - 如果项目用了自定义异常处理器，需确认它仍继承
Hyperf\HttpServer\Exception\Handler\ExceptionHandler并重写了shouldReport()和render()
最易被忽略的一点：注解参数的类型校验（比如 rule 是 string 还是 array）必须在切面里做防御性检查，否则 validator()->make() 可能因传入非法规则而静默失败或报 PHP Warning。
