Play Framework 迁移指南：移除 GlobalSettings，全面转向依赖注入（Scala 与 Java）

后端Web框架【免费下载链接】playframeworkThe Community Maintained High Velocity Web Framework For Java and Scala.项目地址https://gitcode.com/gh_mirrors/pl/playframework点击查看免费下载本文基于 Play Framework 仓库中 GlobalSettings.md 编写面向从 Play 2.3 及更早版本升级的应用。文章以该迁移文档为主体骨架结合仓库内 HttpErrorHandler.scala、HttpRequestHandler.scala、ApplicationLifecycle.scala 等核心实现逐方法说明GlobalSettings各项钩子的替代方案并给出可直接落地的迁移步骤与代码示例。GlobalSettings是 Play 2.3 及更早版本中用于拦截应用生命周期与 HTTP 处理流程的全局钩子类。随着 Play 全面转向依赖注入DI官方强烈建议应用把GlobalSettings实现类中的代码尽可能迁移出去理想情况下彻底删除这个类。本文按方法逐一给出 Scala 与 Java 两种 API 的迁移路径启动逻辑交给 DI 构造器停止逻辑交给ApplicationLifecycle错误处理交给HttpErrorHandler请求处理交给HttpRequestHandler过滤逻辑交给HttpFilters。读完本文你将能够把旧式GlobalSettings完全替换为组件化、可测试、由依赖注入管理的新式实现。背景为什么移除GlobalSettingsGlobalSettings曾经是 Play 应用的万能钩子它同时承担应用启动/停止回调、HTTP 错误处理、请求预处理、路由、过滤器注册、配置加载等大量职责。这种方式有几个明显问题全局可变状态难以测试钩子逻辑游离于组件图之外无法按需注入依赖职责混杂错误处理、路由、过滤等横切逻辑全部堆在一个类里生命周期不可控beforeStart/onStart等回调与依赖的构造顺序没有类型安全的约束。Play 自 2.4 起引入了一套组件化 API 替代这些钩子从 HttpErrorHandler.scala 的since 2.4.0注释可以印证这些组件自该版本起提供。如果你还没有阅读依赖注入相关的指南建议先阅读 Java 依赖注入指南 或 Scala 依赖注入指南再对照本文进行迁移。迁移总原则构造器即启动Lifecycle 即停止在深入逐方法迁移前先掌握两条贯穿全文的核心设计思想在 ApplicationLifecycle.scala 的源码注释中有完整阐述构造器就是启动回调。DI 框架实例化某个类时其构造器中的初始化代码就会执行。这样什么时候启动、谁先启动由组件依赖图决定顺序是类型安全、可验证的。Play 只提供停止回调。因为构造器已经承担了启动Play 只通过ApplicationLifecycle提供停止钩子停止钩子按注册顺序的逆序执行保证组件在被关闭前仍可安全使用它所依赖的组件。Scala 应用迁移指南启动逻辑beforeStart/onStart→ 构造器 急切绑定原来写在GlobalSettings.beforeStart和GlobalSettings.onStart里的代码现在应该放进某个依赖注入类的构造器中——DI 框架加载该类时初始化即会执行。如果这些代码必须在应用真正对外服务之前执行例如预热缓存、连接远程系统则需要急切初始化也就是急切绑定eager binding。在 Scala 中通过Module声明绑定并追加.eagerlyclass MyModule extends play.api.inject.Module { def bindings(environment: play.api.Environment, configuration: play.api.Configuration) Seq( bind[MyStartupService].toSelf.eagerly() ) }关于急切绑定的完整说明参见 Scala 依赖注入指南中的 Eager bindings 一节。需要注意的是急切绑定在开发模式sbt run与生产模式sbt stage下的初始化时机略有差异开发模式下应用启动时创建、但可能延迟到首个请求才完全初始化以便快速热重载生产模式下则会在启动时立即完整初始化。停止逻辑onStop→ApplicationLifecycle停止钩子在需要注册停止钩子的类中注入ApplicationLifecycle依赖把onStop的实现移入传给addStopHook的Future中import play.api.inject.ApplicationLifecycle import jakarta.inject.{Inject, Singleton} import scala.concurrent.Future Singleton class MyConnectionPool Inject() (applicationLifecycle: ApplicationLifecycle) { private val pool new SomeConnectionPool() applicationLifecycle.addStopHook { () Future.successful(pool.shutdown()) } }停止钩子返回的Future应在其完成时兑现如果立即完成并返回成功Future也是允许的。详细的停止/清理说明见 Scala 依赖注入指南。从源码可以看到DefaultApplicationLifecycle 使用ConcurrentLinkedDeque保存钩子并通过hooks.push压栈执行时依次poll从而保证后注册的钩子先执行。服务器错误onError→HttpErrorHandler.onServerError创建继承自HttpErrorHandler的类把GlobalSettings.onError的实现移入HttpErrorHandler.onServerError方法import play.api.http.HttpErrorHandler import play.api.mvc.{RequestHeader, Result, Results} import scala.concurrent.Future class MyErrorHandler extends HttpErrorHandler { def onClientError(request: RequestHeader, statusCode: Int, message: String): Future[Result] Future.successful(Results.Status(statusCode)(sClient error: $statusCode)) def onServerError(request: RequestHeader, exception: Throwable): Future[Result] Future.successful(Results.InternalServerError(Server error occurred)) }onServerError处理 5xx 服务端错误onClientError处理 4xx 客户端错误statusCode 必须大于等于 400 且小于 500源码对此有明确注释。更多细节参见 Scala 错误处理指南。请求接收onRequestReceived→HttpRequestHandler.handlerForRequest创建继承自HttpRequestHandler的类把GlobalSettings.onRequestReceived的实现移入handlerForRequest方法import play.api.http.{DefaultHttpRequestHandler, HttpRequestHandler} import play.api.mvc.{Handler, RequestHeader} class MyRequestHandler extends DefaultHttpRequestHandler { override def handlerForRequest(request: RequestHeader): (RequestHeader, Handler) { // 在这里执行原来 onRequestReceived 的逻辑 super.handlerForRequest(request) } }特别提醒如果你原来的onRequestReceived实现中调用了super.onRequestReceived那么应继承DefaultHttpRequestHandler而非HttpRequestHandler并把所有super.onRequestReceived调用替换为super.handlerForRequest。handlerForRequest允许返回被修改例如被打上路由信息标签的请求和对应的HandlerPlay 会把返回的请求继续传给错误处理器与过滤器相关设计意图见 HttpRequestHandler.scala。参见 Scala 请求处理器指南。路由请求onRouteRequest→DefaultHttpRequestHandler.routeRequest创建继承自DefaultHttpRequestHandler的类把onRouteRequest的实现移入routeRequest方法import play.api.http.DefaultHttpRequestHandler import play.api.mvc.{Handler, RequestHeader} class MyRouter extends DefaultHttpRequestHandler { override def routeRequest(request: RequestHeader): Option[Handler] { // 在这里执行原来 onRouteRequest 的逻辑例如按请求参数选择不同路由器 super.routeRequest(request) } }源码中的默认实现是router.get().handlerFor(request)注释明确说明可以覆写此方法以实现基于请求参数使用不同路由器等自定义路由策略。请求完成回调onRequestCompletion已弃用不再被调用这个方法是已弃用的并且 Play不再调用它。替代方案是创建一个自定义过滤器把onDoneEnumerating回调挂到返回结果流的Enumerator上。过滤器创建方法见 Scala HTTP 过滤器指南。处理器未找到onHandlerNotFound→HttpErrorHandler.onClientError创建继承自HttpErrorHandler的类实现onClientError。注意该方法接收statusCode参数所以你的实现应归结为if (statusCode play.api.http.Status.NOT_FOUND) { // 在这里移入你原来 GlobalSettings.onHandlerNotFound 的实现 }错误请求onBadRequest→HttpErrorHandler.onClientError同样地把onBadRequest的实现放入onClientError并以状态码为判断条件if (statusCode play.api.http.Status.BAD_REQUEST) { // 在这里移入你原来 GlobalSettings.onBadRequest 的实现 }实际上DefaultHttpErrorHandler的内部实现正是这样做的它的 onClientError 用statusCode match把BAD_REQUEST、FORBIDDEN、NOT_FOUND分别分发给onBadRequest、onForbidden、onNotFound这三个 protected 方法。因此更优雅的做法是直接继承DefaultHttpErrorHandler并只覆写onBadRequest/onNotFound方法而不是手动判断状态码。详见 Scala 错误处理指南。配置加载configure/onLoadConfig→ 配置文件或自定义ApplicationLoader把GlobalSettings.configure和GlobalSettings.onLoadConfig中的逻辑改为尽可能把所有配置写入application.conf等配置文件或创建你自己的ApplicationLoader通过GuiceApplicationBuilder.loadConfig加载配置。进阶用法参见 Scala 依赖注入指南 中关于扩展 GuiceApplicationLoader 的内容。过滤器doFilter/WithFilters→HttpFilters创建继承自HttpFilters的类实现filters方法返回过滤器序列import play.api.http.{DefaultHttpFilters, HttpFilters} import play.api.mvc.EssentialFilter class MyFilters extends DefaultHttpFilters( new MyFirstFilter(), new MySecondFilter() )特别注意如果你的Global类混入了WithFilterstrait那么现在应创建一个继承自HttpFilters的过滤器类并且放在空包empty package中。Play 会从配置项play.http.filters读取过滤器类名并实例化具体机制见 HttpFilters.scala 中的bindingsFromConfiguration以及 Scala HTTP 过滤器指南。Java 应用迁移指南Java API 的迁移思路与 Scala 一致只是部分类名与异步类型不同Java 侧使用CompletionStage/Promise而非Future。启动逻辑beforeStart/onStart与 Scala 相同启动时需要做的事情移到依赖注入类的构造器中。若需要急切初始化例如在应用真正启动前执行某些代码定义急切绑定eager binding参见 Java 依赖注入指南 的 Eager bindings 一节。停止逻辑onStop→ApplicationLifecycle.addStopHook在需要注册停止钩子的类中注入ApplicationLifecycle把onStop的实现移入传给addStopHook的Promise即异步结果中import play.inject.ApplicationLifecycle; import jakarta.inject.Inject; import jakarta.inject.Singleton; import java.util.concurrent.CompletableFuture; Singleton public class MyConnectionPool { private final ConnectionPool pool new ConnectionPool(); Inject public MyConnectionPool(ApplicationLifecycle applicationLifecycle) { applicationLifecycle.addStopHook(() - CompletableFuture.completedFuture(pool.shutdown())); } }说明迁移文档写作时Play 2.4 时代Java 侧使用的还是Promise当前仓库中的ApplicationLifecycle已提供接收Callable? extends CompletionStage?的重载见 ApplicationLifecycle.scala因此现代写法直接返回CompletableFuture即可。详见 Java 依赖注入指南 的 Stopping/cleaning-up 一节。服务器错误onError→HttpErrorHandler.onServerError创建实现play.http.HttpErrorHandler接口的类把onError的实现移入onServerErrorimport play.http.HttpErrorHandler; import play.mvc.Http.RequestHeader; import play.mvc.Result; import play.mvc.Results; import java.util.concurrent.CompletionStage; import java.util.concurrent.CompletableFuture; public class MyErrorHandler implements HttpErrorHandler { Override public CompletionStageResult onClientError(RequestHeader request, int statusCode, String message) { return CompletableFuture.completedFuture(Results.status(statusCode, Client error: statusCode)); } Override public CompletionStageResult onServerError(RequestHeader request, Throwable exception) { return CompletableFuture.completedFuture(Results.internalServerError(Server error)); } }接口定义见 HttpErrorHandler.java。完整说明参见 Java 错误处理指南。请求预处理onRequest→DefaultHttpRequestHandler.createAction创建继承自play.http.DefaultHttpRequestHandler的类把onRequest的实现移入createAction方法。DefaultHttpRequestHandler的职责是委托给 Scala 侧的JavaCompatibleHttpRequestHandler见 DefaultHttpRequestHandler.java。参见 Java ActionCreator 指南。路由请求onRouteRequest暂无简单迁移路径Java API 没有简单的迁移方案。如果你确实需要onRouteRequest的能力只能暂时保留你的Global类更长时间或考虑在 Scala 侧通过自定义HttpRequestHandler实现再经 Java 适配层桥接。onHandlerNotFound/onBadRequest→HttpErrorHandler.onClientError与 Scala 相同实现onClientError并按状态码分派if (statusCode play.mvc.Http.Status.NOT_FOUND) { // 在这里移入你原来 GlobalSettings.onHandlerNotFound 的实现 }if (statusCode play.mvc.Http.Status.BAD_REQUEST) { // 在这里移入你原来 GlobalSettings.onBadRequest 的实现 }同样可以继承play.http.DefaultHttpErrorHandler并覆写onNotFound/onBadRequest方法避免手工判断状态码。参见 Java 错误处理指南。配置加载onLoadConfig→ 配置文件或自定义ApplicationLoader把所有配置写进配置文件或者创建你自己的ApplicationLoader通过GuiceApplicationBuilder.loadConfig加载参见 Java 依赖注入指南。过滤器filters→HttpFilters创建实现play.http.HttpFilters接口的类实现filters()方法import play.http.HttpFilters; import play.mvc.EssentialFilter; public class MyFilters implements HttpFilters { Override public EssentialFilter[] filters() { return new EssentialFilter[] { new MyFirstFilter(), new MySecondFilter() }; } }参见 Java HTTP 过滤器指南。源码印证新组件如何协同工作以上迁移并非简单的改名而是把钩子职责拆解到了 Play 请求处理管线的真实组件中。从仓库源码可以印证它们的协同方式错误处理管线DefaultHttpErrorHandler.onServerError 会先通过HttpErrorHandlerExceptions.throwableToUsefulException把异常转换为带 ID、可展示源码位置的UsefulException开发模式会展示调试页生产模式只返回通用错误页并区分onDevServerError与onProdServerError两个可覆写方法。请求处理管线DefaultHttpRequestHandler.handlerForRequest 依次执行开发模式下的WebCommands拦截如 evolutions UI→ 路由查找routeRequest→ HEAD 请求自动回退为 GET 路由 → 未命中返回 404 → 应用过滤器链。过滤器装配HttpFilters.scala 中的EnabledFilters会从配置项play.filters.enabled/play.filters.disabled读取过滤器类名并通过注入器实例化你也可以用DefaultHttpFilters在代码中直接声明过滤器序列。生命周期装配ApplicationLifecycle的停止钩子通过逆序后进先出执行保证依赖安全且自 2.7.0 起stop()是幂等的多次调用只执行一次见 ApplicationLifecycle.scala。迁移检查清单完成迁移后用下面的清单核对你的应用是否已完全脱离GlobalSettings所有启动逻辑移入 DI 类的构造器需要提前执行的用.eagerly()Scala或急切绑定Java声明所有停止逻辑通过注入ApplicationLifecycle注册addStopHook自定义错误页面通过实现HttpErrorHandler提供onServerError与onClientError请求预处理与自定义路由通过HttpRequestHandler/DefaultHttpRequestHandler提供过滤器通过HttpFilters提供配置写入play.http.filters配置加载统一收敛到配置文件或自定义ApplicationLoader已删除GlobalSettings实现类及conf/application.conf中相关的全局设置项迁移完成后你的应用将获得类型安全、可测试、由依赖图驱动的组件生命周期这正是 Play 从 2.4 起推荐并在后续版本强制的架构方向。赞分享后端Web框架【免费下载链接】playframeworkThe Community Maintained High Velocity Web Framework For Java and Scala.项目地址https://gitcode.com/gh_mirrors/pl/playframework点击查看免费下载相关推荐Play Framework 2.4 迁移指南从 2.3 升级到 Java 8、依赖注入与新配置体系Play Framework 2.4 迁移指南从 2.3 升级到 Java 8、依赖注入与新配置体系 本文是 Play Framework 官方 2.4 迁移后端Web框架Play Framework 接入 CAT 实时监控Scala Filter 与 Context 迁移实战指南Play Framework 接入 CAT 实时监控Scala Filter 与 Context 迁移实战指南 导读 本文基于 CAT 开源仓库中的 inte可观测性指标监控告警APM后端链路追踪Play Framework Scala 测试指南用 GuiceApplicationBuilder 与 GuiceInjectorBuilder 配置测试中的依赖注入Play Framework Scala 测试指南用 GuiceApplicationBuilder 与 GuiceInjectorBuilder 配置测试中后端Web框架创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考