Play Framework Scala 错误处理完全指南：从 HttpErrorHandler 到自定义 JSON/HTML 错误响应

后端Web框架【免费下载链接】playframeworkThe Community Maintained High Velocity Web Framework For Java and Scala.项目地址https://gitcode.com/gh_mirrors/pl/playframework点击查看免费下载导读本文基于 Play Framework 官方 Scala 指南中的《Handling errors》文档系统讲解 Play 中 HTTP 错误处理的完整体系客户端错误4xx与服务器错误5xx如何被框架自动识别与处理、如何通过HttpErrorHandler接口统一接管错误响应、如何为 JSON API 配置JsonHttpErrorHandler、如何按Accept头在 HTML 与 JSON 之间自动切换、以及如何通过继承DefaultHttpErrorHandler在保留开发模式调试能力的同时定制生产环境错误页。读完本文你将能够为任何基于 Play 的 Scala 应用纯 JSON 后端、前后端混合应用或纯 HTML 站点落地一套贴合业务需求的错误响应方案并理解其底层实现原理。错误的两大类型客户端错误与服务器错误一个 HTTP 应用可能返回的错误从根本上可以分为两类客户端错误Client errors4xx表示发起连接的客户端做了错误的事情例如请求了不存在的资源、发送了格式非法的请求头、使用了不支持的 Content-Type 等。服务器错误Server errors5xx表示服务器自身出现了问题例如 Action 代码抛出了未捕获的异常。Play 在多数场景下会自动检测客户端错误——包括格式非法的请求头值、不支持的内容类型、找不到对应路由的资源等同时也会自动处理服务器错误——如果你的 Action 代码抛出异常Play 会捕获它并生成一个服务器错误页发送给客户端。而 Play 处理这些错误的统一入口就是HttpErrorHandler接口。它只定义了两个方法trait HttpErrorHandler { // 客户端错误statusCode 必须 400 且 500 def onClientError(request: RequestHeader, statusCode: Int, message: String ): Future[Result] // 服务器错误 def onServerError(request: RequestHeader, exception: Throwable): Future[Result] }这两个方法的实现在core/play/src/main/scala/play/api/http/HttpErrorHandler.scala中该 trait 自 Play 2.4.0 引入是整个错误处理体系的核心契约无论采用哪种错误处理器、无论渲染成什么格式最终都要收敛为返回一个Future[Result]。为 JSON API 配置错误响应JsonHttpErrorHandler默认情况下Play 以 HTML 格式返回错误页。但对于 JSON API 而言错误响应也应该是 JSON才能保持接口风格的一致性。Play 为此提供了HttpErrorHandler的替代实现JsonHttpErrorHandler它会将错误格式化为 JSON 返回。要启用它只需在conf/application.conf中配置play.http.errorHandler属性play.http.errorHandler play.api.http.JsonHttpErrorHandler从源码core/play/src/main/scala/play/api/http/HttpErrorHandler.scala可以看到JsonHttpErrorHandler的实际行为客户端错误返回{error: {requestId: 请求ID, message: 错误信息}}状态码保持原 4xx 值若传入的状态码不是 4xx会抛出IllegalArgumentException。服务器错误Dev 模式返回包含id异常 ID、requestId、exception.title、exception.description以及完整堆栈的 JSON便于开发时快速定位问题。堆栈的格式化逻辑封装在可重写的formatDevServerErrorException方法中默认使用ExceptionUtils.getStackFrames。服务器错误Prod 模式只返回{error: {id: 异常ID}}不泄露任何堆栈与异常细节避免敏感信息外泄。也就是说JsonHttpErrorHandler在 Dev 与 Prod 模式下对异常的展示做了自动区分开发模式完整呈现异常细节生产模式仅暴露一个异常 ID该 ID 同时会被写入服务器日志方便日志与响应关联排查。混合 HTML 与 JSON 应用按 Accept 头自动选择现代 Web 应用往往同时包含 HTML 页面与 JSON 接口。如果整个应用只用 HTML 错误页或只用 JSON 错误响应体验都不够理想。Play 为此提供了另一个开箱即用的错误处理器HtmlOrJsonHttpErrorHandler。play.http.errorHandler play.api.http.HtmlOrJsonHttpErrorHandler它的工作原理见源码非常直接构造时注入DefaultHttpErrorHandler处理 HTML与JsonHttpErrorHandler处理 JSON并委托给PreferredMediaTypeHttpErrorHandler根据客户端Accept头中的媒体类型偏好决定把错误请求交给哪一个处理器class HtmlOrJsonHttpErrorHandler Inject() ( htmlHandler: DefaultHttpErrorHandler, jsonHandler: JsonHttpErrorHandler ) extends PreferredMediaTypeHttpErrorHandler(text/html - htmlHandler, application/json - jsonHandler)对于大多数应用来说这是相当合适的默认错误处理器浏览器请求会得到 HTML 错误页API 客户端声明Accept: application/json会得到 JSON 错误体。支持更多内容类型扩展 PreferredMediaTypeHttpErrorHandler如果你希望在 HTML 与 JSON 之外还支持其他内容类型的错误响应例如纯文本可以扩展PreferredMediaTypeHttpErrorHandler。其核心逻辑在preferredHandler方法中通过MediaRange.preferred(request.acceptedTypes, supportedTypes)从客户端接受的媒体类型中挑选最匹配的处理器若客户端声明的媒体类型不在支持列表内则回退到构造时传入的第一个 handler 作为defaultHandler当多个媒体类型同时匹配时按声明顺序取第一个匹配项。下面是一个同时支持 JSON、HTML 与text/plain的示例完整代码见 code/ScalaErrorHandling.scalaclass MyHttpErrorHandler Inject() ( jsonHandler: JsonHttpErrorHandler, htmlHandler: DefaultHttpErrorHandler, textHandler: MyTextHttpErrorHandler ) extends PreferredMediaTypeHttpErrorHandler( application/json - jsonHandler, text/html - htmlHandler, text/plain - textHandler )上例复用了 Play 默认的 JSON 与 HTML 处理器并新增了一个自定义处理器MyTextHttpErrorHandler——当客户端请求头声明Accept: text/plain时错误将以纯文本返回。自定义错误处理器两种接入方式方式一重写 BuiltInComponents 的 httpErrorHandler如果你使用BuiltInComponents以编译时依赖注入的方式构造应用只需重写httpErrorHandler方法返回自定义处理器的实例即可。方式二运行时依赖注入Guice 根包 ErrorHandler如果使用运行时依赖注入例如 Guice错误处理器可以在运行时被动态加载。最简单的做法在**根包root package即无包声明**下创建一个名为ErrorHandler的类实现HttpErrorHandler接口例如import scala.concurrent._ import jakarta.inject.Singleton import play.api.http.HttpErrorHandler import play.api.mvc._ import play.api.mvc.Results._ Singleton class ErrorHandler extends HttpErrorHandler { def onClientError(request: RequestHeader, statusCode: Int, message: String): Future[Result] { Future.successful( Status(statusCode)(A client error occurred: message) ) } def onServerError(request: RequestHeader, exception: Throwable): Future[Result] { Future.successful( InternalServerError(A server error occurred: exception.getMessage) ) } }只要把错误处理器放在根包无包名并命名为ErrorHandlerPlay 就会默认使用它——无需任何额外配置。这一按名字发现的机制源自源码中的HttpErrorHandler.bindingsFromConfigurationcore/play/src/main/scala/play/api/http/HttpErrorHandler.scala#L110-L118它通过Reflect.bindingsFromConfiguration读取配置项play.http.errorHandler在未配置时回退到类名ErrorHandler进行反射绑定并提供了 Scala 接口HttpErrorHandler、Java 接口play.http.HttpErrorHandler与 Java 适配器JavaHttpErrorHandlerAdapter之间的桥接。场景二放入包内或按环境区分如果你希望把错误处理器放进某个包内或者为不同环境Dev / Prod配置不同的错误处理器那么在conf/application.conf中配置play.http.errorHandler指向你的自定义错误处理器类即可play.http.errorHandler com.example.ErrorHandler注意此时类名必须带完整包名配置值是一个字符串。为自定义媒体类型添加专属处理器如果希望按客户端偏好的媒体类型分发错误、同时又为某一媒体类型接入自己的处理器同样可以扩展PreferredMediaTypeHttpErrorHandler——上面的MyHttpErrorHandler示例就是典型用法它在默认 JSON/HTML 处理器之外增加了对text/plain的自定义处理。扩展默认错误处理器保留 Dev 调试、定制 Prod 页面Play 默认错误处理器DefaultHttpErrorHandler开箱即用地提供了大量实用功能。最典型的是在 Dev 模式下发生服务器错误时Play 会尝试定位并渲染导致异常的应用程序源码片段让你能快速看到并定位问题所在。如果你希望在生产环境提供自定义服务器错误页同时保留开发模式的这些调试能力不要直接覆写onServerError而是继承DefaultHttpErrorHandler并覆写其提供的便捷方法把自己的逻辑与 Play 的既有行为混合使用。例如只自定义生产环境的服务器错误信息开发模式错误信息保持原样同时提供一个特定的 403 Forbidden 错误页import scala.concurrent._ import jakarta.inject._ import play.api._ import play.api.http.DefaultHttpErrorHandler import play.api.mvc._ import play.api.mvc.Results._ import play.api.routing.Router Singleton class ErrorHandler Inject() ( env: Environment, config: Configuration, sourceMapper: OptionalSourceMapper, router: Provider[Router] ) extends DefaultHttpErrorHandler(env, config, sourceMapper, router) { override def onProdServerError(request: RequestHeader, exception: UsefulException) { Future.successful( InternalServerError(A server error occurred: exception.getMessage) ) } override def onForbidden(request: RequestHeader, message: String) { Future.successful( Forbidden(Youre not allowed to access this resource.) ) } }从源码理解 DefaultHttpErrorHandler 的分派逻辑阅读 HttpErrorHandler.scala 可以更深入地理解这套设计客户端错误分派onClientError依据状态码分发到onBadRequest400、onForbidden403、onNotFound404以及onOtherClientError其余 4xx传入非 4xx 状态码会抛出IllegalArgumentException。这些方法都是protected的可供子类按需覆写。服务器错误分派onServerError首先通过HttpErrorHandlerExceptions.throwableToUsefulException将原始异常转换为有用的异常UsefulException会为异常生成 ID并在 Dev 模式下借助SourceMapper加载抛出异常的源码位置构造PlayException.ExceptionSource随后依据config.showDevErrors决定走onDevServerError还是onProdServerError。Dev / Prod 的判定来源从构造器可以看出showDevErrors由environment.mode ! Mode.Prod决定即非生产模式Dev / Test自动开启调试错误页。这也是为什么官方推荐覆写onProdServerError而非onServerError——前者只影响生产页面开发模式的调试输出原封不动。日志能力logServerError会以! 异常ID - Internal server error, for (method) [uri]的格式记录错误可覆写以追加额外信息如当前认证用户 ID。兜底机制若错误处理本身失败fatalErrorMessage默认返回空字符串作为最后一道防线返回简单消息官方强烈建议该方法只返回简单字符串、不做任何可能再次抛异常的处理。官方测试core/play/src/test/scala/play/api/HttpErrorHandlerSpec.scala以及文档配套的 ScalaErrorHandling.scala 测试 均验证了这套行为例如在 Prod 模式下onServerError返回以A server error occurred:开头的页面而 Dev 模式下该前缀不会出现通过GuiceApplicationBuilder().configure(play.http.errorHandler - ...)即可在测试中快速切换自定义处理器。此外DefaultHttpErrorHandler还支持通过play.editor配置项设置错误页中超链接指向的编辑器DevHttpErrorHandler在加载配置后会自动调用setPlayEditor完成设置方便开发时点击错误页直接跳转到源码编辑器。总结与选型建议Play 的错误处理体系围绕HttpErrorHandler这一单一契约展开各处理器之间的选择关系可以概括为场景推荐配置说明纯 HTML 站点默认不配置使用DefaultHttpErrorHandlerDev 模式展示源码级调试页纯 JSON APIplay.http.errorHandler play.api.http.JsonHttpErrorHandler错误体统一为 JSONProd 模式不泄露堆栈HTML JSON 混合play.http.errorHandler play.api.http.HtmlOrJsonHttpErrorHandler按客户端Accept头自动分发更多内容类型扩展PreferredMediaTypeHttpErrorHandler自定义媒体类型与处理器的映射完全自定义根包ErrorHandler或配置play.http.errorHandler直接实现HttpErrorHandler接口保留 Dev 调试 定制 Prod继承DefaultHttpErrorHandler覆写onProdServerError、onForbidden等便捷方法选择策略很简单大多数混合型应用可直接使用HtmlOrJsonHttpErrorHandler纯 JSON 后端使用JsonHttpErrorHandler需要定制生产错误页时继承DefaultHttpErrorHandler并按需覆写对应方法这样既能获得开箱即用的调试体验又能保证生产环境错误响应的专业性与安全性。赞分享后端Web框架【免费下载链接】playframeworkThe Community Maintained High Velocity Web Framework For Java and Scala.项目地址https://gitcode.com/gh_mirrors/pl/playframework点击查看免费下载相关推荐Play Framework 错误处理完全指南HttpErrorHandler、JSON 错误响应与自定义错误处理器Play Framework 错误处理完全指南HttpErrorHandler、JSON 错误响应与自定义错误处理器 本指南以 documentation/m后端Web框架Play Framework错误处理最佳实践: 自定义错误页与HttpErrorHandler完全指南Play Framework错误处理最佳实践: 自定义错误页与HttpErrorHandler完全指南 在构建 Web 应用时如何优雅地处理错误往往决定了产品后端Web框架Yii 2 错误处理完全指南ErrorHandler 组件原理、自定义错误页与 JSON 错误响应实战Yii 2 错误处理完全指南ErrorHandler 组件原理、自定义错误页与 JSON 错误响应实战 本篇技术指南围绕 Yii 2 框架内置的 yii\we后端Web框架上一篇JetMoE会议论文解读相关学术会议的最新研究下一篇Hermes Agent 容器镜像安全3 个最容易翻车的地方和修法创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考