hyperf 自定义异常响应需明确分离 http 状态码与业务码，统一返回结构 {"code":1002,"message":"用户名已存在","errors":{...}}，确保 handler 顺序合理、isvalid() 严格判断、stoppropagation() 显式终止，并记录含 request_id 等上下文的日志。
Hyperf 自定义异常响应要返回清晰错误提示，关键不是“写个 handler 就完事”，而是得把状态码、业务码、错误结构、上下文日志这四块理清楚，否则容易出现 422 没 errors、500 里塞了 HTTP 状态码当业务码、日志查不到请求 ID 这类问题。
HTTP 状态码和业务 code 必须分离
HTTP status（如 400、422、500）只反映通信层结果，业务错误码（如 1001、2003）应统一放在 JSON body 的 code 字段里。不要用 $throwable->getCode() 直接设为 HTTP 状态——比如 ValidationException 构造时传了 422，不代表你该调 $response->withStatus(422)，因为框架默认已按异常类型设好 status；更常见的是误把业务码（如 504）当 HTTP 状态返回，导致语义错乱。
- 正确做法：HTTP status 固定用标准值（4xx/5xx），body 中
{"code":1002,"message":"用户名已存在","errors":{...}} - ValidationExceptionHandler 默认带
errors字段，但前提是它被真正触发——检查exceptions.php里 handler 键名是否与server.php中 HTTP server 的 name 完全一致（大小写敏感） - 手写 handler 时，别漏掉
$validator->errors()->messages()，只取first()会丢掉全部字段错误
异常处理器顺序决定谁先接管
config/autoload/exceptions.php 中的数组顺序就是匹配顺序。HttpExceptionHandler 是框架内置兜底处理器，专门处理 NotFoundException、MethodNotAllowedHttpException 等，返回标准 HTTP 状态。如果你把 AppExceptionHandler 放在它前面，且 isValid() 返回 true，那 404 就会被当成普通异常吞掉，返回 500 而非 404。
- 推荐顺序：
HttpExceptionHandler→ValidationExceptionHandler→ 自定义业务异常 Handler（如 JwtExceptionHandler） -
isValid()必须严格判断类型，例如return $throwable instanceof UserException;，不能直接写return true; - 若 handler 不处理当前异常，就不要调
stopPropagation()，让它继续往下匹配
必须显式终止异常传播链
每个 handler 处理完异常后，一定要调 $this->stopPropagation()。否则异常会继续传递给下一个 handler，造成重复记录、响应被覆盖、甚至日志里看到两条一模一样的错误。
- 典型错误：写了
if ($e instanceof FooException) { ... }却没加stopPropagation()，结果 ValidationException 也被这个宽泛条件捕获并返回空 body - 只有确认当前 handler 已完整处理该异常，才调用
stopPropagation()；不确定或不处理，就原样返回$response
错误响应需带可追溯上下文
光返回 {"message":"xxx"} 不够。生产环境需要能快速定位问题：是哪个接口、哪个用户、什么时间、携带什么参数出的问题。这些信息不能靠 $e->getTraceAsString() 拼凑，而要从容器中取当前请求上下文并结构化记录。
- 在 handler 的
handle()方法里，通过$this->container->get(RequestInterface::class)获取请求对象，提取 path、method、ip、request_id - 日志内容建议包含：timestamp、request_id、uri、method、user_id（如有）、exception class、message、trace（精简关键行）
- 返回给前端的 message 应该是用户友好的（如“手机号格式不正确”），而非开发堆栈（如“ArgumentCountError”）
