后端Web框架【免费下载链接】playframeworkThe Community Maintained High Velocity Web Framework For Java and Scala.项目地址https://gitcode.com/gh_mirrors/pl/playframework点击查看免费下载本篇技术指南以 Play Framework 2.6 官方 JPA 迁移文档documentation/manual/releases/release26/migration26/JPAMigration26.md为主体系统梳理 2.6 版本对play.db.jpa模块的三大变更移除全部静态/全局状态型方法、正式废弃JPA类、并新增针对 Action 内直接使用 JPA 的异步警告。文章结合当前仓库play-java-jpa模块的 JPAApi 接口 与 DefaultJPAApi 实现 源码给出从旧 API 到注入式JPAApi的完整改造方案、自定义执行上下文CustomExecutionContext配置以及withTransaction(...)的底层事务语义帮助读者完成一次可验证、可上线的 JPA 迁移。迁移背景为什么 2.6 要对 JPA API 动刀Play Framework 的 JPA 支持长期以来通过play.db.jpa.JPA静态类提供入口例如JPA.em()、JPA.withTransaction(...)等。这类静态 API 的实现依赖全局状态global stateEntityManager 被绑定在当前线程上并通过 ThreadLocal 之类的机制在控制器、过滤器、异步回调之间传递。这在同步的阻塞式编程模型里尚可运转但在 Play 的异步、非阻塞模型下会引发两个问题线程模型不匹配Play 的渲染线程池被设计为专注于非阻塞渲染一旦 JDBC/JPA 的阻塞调用占用这些线程应用的整体吞吐与延迟都会受到牵连。状态难以管理全局绑定的 EntityManager 生命周期不清晰跨线程传播时极易出现在错误线程上使用 EntityManager这类 JPA 规范违规问题。因此2.6 版本将 JPA 的访问方式统一收敛到可注入的play.db.jpa.JPAApi实例上。迁移文档中的三节内容——移除废弃方法、废弃JPA类、新增异步警告——本质上是同一件事的三个侧面彻底告别全局状态拥抱依赖注入与显式执行上下文。已移除的废弃方法Removed Deprecated MethodsPlay 2.6 中以下四个长期标记为Deprecated的方法被直接删除使用它们的代码将无法再编译已移除方法说明play.db.jpa.JPA.jpaApi静态方法用于获取全局JPAApi实例play.db.jpa.JPA.em(key)静态方法按 key 获取当前线程绑定的EntityManagerplay.db.jpa.JPA.bindForAsync(em)静态方法将EntityManager绑定到异步回调执行的线程play.db.jpa.JPA.withTransaction静态方法在事务中执行代码块官方迁移建议非常明确改用注入的JPAApi实例具体用法参见 documentation/manual/working/javaGuide/main/sql/JavaJPA.md 中的 Using play.db.jpa.JPAApi 一节。迁移示例从静态调用到注入调用改造前Play 2.5 及更早版本public class PersonController extends Controller { // 旧方式静态入口依赖全局状态 public Result list() { EntityManager em JPA.em(default); ListPerson persons em.createQuery(select p from Person p, Person.class) .getResultList(); return ok(Json.toJson(persons)); } }改造后Play 2.6构造器注入JPAApipublic class PersonController extends Controller { private final JPAApi jpaApi; Inject public PersonController(JPAApi jpaApi) { this.jpaApi jpaApi; } public CompletionStageResult list() { return CompletableFuture.supplyAsync(() - { ListPerson persons jpaApi.withTransaction(em - em.createQuery(select p from Person p, Person.class) .getResultList() ); return ok(Json.toJson(persons)); }, ec); // ec 为自定义的数据库执行上下文 } }从源码结构看JPAApi的注入链路在play-java-jpa模块中被完整支持JPAModule.java 负责将JPAApi绑定到DefaultJPAApi.JPAApiProvider将JPAConfig绑定到DefaultJPAConfig.JPAConfigProvider而 JPAComponents.java 则为无框架Compile-Time DI场景提供了jpaApi()/jpaConfig()的构造方式两者最终都收敛到同一个DefaultJPAApi实现。废弃的 JPA 类Deprecated JPA Class迁移文档特别指出自 2.6.1 起play.db.jpa.JPA类被标记为废弃deprecated原因同样是它底层使用全局状态。文档还透露了一个版本细节该废弃标记本应在 2.6.0 中加入但因疏漏被遗漏直到 2.6.1 才补上。需要注意两点语义废弃不等于立即删除与上面四个被直接移除的方法不同JPA类在 2.6.x 中仍然存在并可用只是编译器会给出弃用警告删除动作在后续版本中才发生。废弃是强信号JPA类提供的全部能力——获取 EntityManager、管理事务、绑定异步上下文——都能被注入式JPAApi完整替代因此官方明确要求新代码一律使用JPAApi。在迁移时可以分两步走先消除方法调用层面的依赖将JPA.em(key)、JPA.withTransaction(...)等调用逐一替换为jpaApi.em(name)、jpaApi.withTransaction(...)方法签名对照见下文 JPAApi 一节。再消除类型层面的依赖代码中不再出现play.db.jpa.JPA类型引用全部改为注入JPAApi字段/构造参数。这样迁移完成后你的代码不仅摆脱了废弃警告也彻底切断了对全局状态的依赖。新增的异步警告Added Async Warning迁移文档在 documentation/manual/working/javaGuide/main/sql/JavaJPA.md 中新增了如下警告在 Action 中直接使用 JPA 会限制你使用 Play 异步特性的能力。请考虑将代码组织为所有对 JPA 的访问都包裹在一个自定义的执行上下文中并向 Play 返回java.util.concurrent.CompletionStage。这条警告背后是 Play 的执行模型事实Action 默认运行在 Play 的渲染线程池上而 JPA/JDBC 是阻塞式 I/O。若在渲染线程上直接执行 JPA 查询线程会被阻塞住无法继续处理其他请求的渲染工作从而削弱异步能力。更详细的论述可参见 JavaJPA.md 中 Using a CustomExecutionContext 一节的 NOTEUsing JPA directly in an Action -- which uses Plays default rendering thread pool -- will limit your ability to use Play asynchronously because JDBC blocks the thread its running on.推荐的架构模式Repository 隔离 自定义执行上下文迁移文档建议将 JPA 操作隔离在 Repository / DAO 之后核心原则有三条所有 JPA 操作通过自定义执行上下文执行确保 Play 渲染线程池完全专注于渲染把 CPU 核心让给渲染而非被 JDBC 阻塞。不把持久化感知对象如 EntityManager、实体暴露给应用其他部分JPA 相关类保持包内私有。Session 不跨异步边界存活方法返回CompletionStage即代表异步边界持有 EntityManager 的会话必须在边界之前关闭。从 DDD 的角度看这意味着领域对象聚合根内部持有 Repository 引用通过调用 Repository 获取实体列表与值对象而不是长时间持有 JPA Session 依赖懒加载。线程池配置与连接池匹配的固定线程池关于 JDBC 连接池的线程池规模JavaJPA 指南给出了明确建议固定线程池大小应等于连接池大小使用thread-pool-executor。并引用 HikariCP 的池规模经验公式# db connections ((physical_core_count * 2) effective_spindle_count) fixedConnectionPool 9 database.dispatcher { executor thread-pool-executor throughput 1 thread-pool-executor { fixed-pool-size ${fixedConnectionPool} } }以四核 CPU 加一块磁盘为例连接池大小约为4 * 2 1 9即fixedConnectionPool 9。throughput 1表示任务尽量不排队、直接由线程执行避免阻塞任务积压在队列中。深入 JPAApi注入式 API 的完整能力JPAApi是本次迁移的目标接口位于 persistence/play-java-jpa/src/main/java/play/db/jpa/JPAApi.java。从源码看它提供以下几类能力方法作用start()初始化所有持久化单元的EntityManagerFactory返回自身em(String name)为指定持久化单元创建并返回一个新的EntityManagerwithTransaction(FunctionEntityManager, T)在默认持久化单元的事务中执行代码块并返回结果withTransaction(ConsumerEntityManager)在默认持久化单元的事务中执行代码块无返回值适合批量更新withTransaction(String name, Function/Consumer)指定持久化单元执行事务withTransaction(String name, boolean readOnly, Function/Consumer)指定持久化单元 只读标志执行事务shutdown()关闭所有EntityManagerFactory关于默认持久化单元withTransaction(Function)无参重载内部委托给withTransaction(default, block)即名为default的持久化单元。这也与conf/application.conf中的jpa.defaultdefaultPersistenceUnit配置一一对应见下文配置小节。源码级解读withTransaction 的事务语义DefaultJPAApi.withTransaction(String, boolean, Function) 的实现在源码层面展示了 Play 2.6 之后 JPA 事务的标准生命周期通过em(name)创建新的EntityManager若创建失败返回 null抛出RuntimeException(Could not create JPA entity manager for name )。非只读模式下获取EntityTransaction并begin()。执行业务代码块block.apply(entityManager)。提交阶段检查tx.getRollbackOnly()若事务已被标记为仅回滚则执行rollback()否则commit()。捕获Throwable时若事务仍处于活动状态则回滚回滚失败会记录 error 日志Could not rollback transaction。finally中始终关闭 EntityManager确保连接归还连接池。这段实现回答了几个迁移中常见的问题事务边界withTransaction自动管理 begin/commit/rollback业务代码无需也不应手动调用EntityManager.getTransaction()。异常安全无论业务代码抛出什么异常事务都会回滚EntityManager 都会关闭不会泄漏连接。只读优化readOnly true时跳过begin()由 JPA 提供者决定如何优化例如 Hibernate 的只读会话。注入与生命周期管理DefaultJPAApi.JPAApiProvider见 DefaultJPAApi.java展示了 Play 2.6 之后 JPA 的正确生命周期管理方式构造函数中显式依赖DBApi确保注入JPAApi时数据库连接池已初始化完毕源码注释原文dependency on db api ensures that the databases are initialised。通过lifecycle.addStopHook(...)注册应用停止钩子在应用关闭时调用jpaApi.shutdown()关闭全部EntityManagerFactory。标记为Singleton保证整个应用共享同一个JPAApi与EntityManagerFactory集合。这意味着迁移到JPAApi后EntityManagerFactory 的创建与销毁全部由 Play 的 DI 容器接管不再需要自己管理静态工厂或全局单例。配置迁移要点数据源 JNDI 与持久化单元要配合注入式JPAApi正常工作conf/application.conf与conf/META-INF/persistence.xml的配置需要完整对齐这部分在 JavaJPA.md 中有完整示例1. 通过 JNDI 暴露数据源JPA 规范要求数据源可经 JNDI 访问db.default.jndiNameDefaultDS2. 创建持久化单元文件位于conf/META-INF/persistence.xml?xml version1.0 encodingUTF-8? persistence xmlnshttps://jakarta.ee/xml/ns/persistence xmlns:xsihttp://www.w3.org/2001/XMLSchema-instance xsi:schemaLocationhttps://jakarta.ee/xml/ns/persistence https://jakarta.ee/xml/ns/persistence/persistence_3_2.xsd version3.2 persistence-unit namedefaultPersistenceUnit transaction-typeRESOURCE_LOCAL providerorg.hibernate.jpa.HibernatePersistenceProvider/provider non-jta-data-sourceDefaultDS/non-jta-data-source validation-modeNONE/validation-mode classmodels.MyEntity/class properties property namehibernate.dialect valueorg.hibernate.dialect.H2Dialect/ /properties /persistence-unit /persistence3. 在application.conf中指定默认持久化单元jpa.defaultdefaultPersistenceUnit从源码角度补充一个实现细节当前仓库的 DefaultJPAConfig.java 中JPAConfigProvider通过configuration.getString(play.jpa.config)读取持久化单元映射的配置路径然后将该路径下的每个key - value条目解析为PersistenceUnit(name, unitName)name是 Play 侧使用的逻辑名unitName是persistence.xml中声明的持久化单元名最终通过JPAModule绑定注入。也就是说迁移后持久化单元的解析完全由配置驱动JPAApi.em(name)/withTransaction(name, ...)中的name必须与这份映射中的逻辑名一致。生产部署外部化资源与 persistence.xml 的坑迁移文档与 JavaJPA 指南都强调了一个部署层面的注意事项在build.sbt中需要配置外部化资源externalized resources确保persistence.xml始终位于生成的应用程序 jar内部// 使 persistence.xml 始终保留在生成的 application jar 内 Compile / resourceGenerators ... // 或按项目实际使用的 sbt 版本配置 externalizeResources 相关选项这一点是 JPA 规范JavaPersistence 规范的硬性要求persistence.xml必须与其持久化单元中的实体位于同一个 jar 文件内否则这些实体对持久化单元不可见。指南中特别解释了为什么不能依赖jar-file显式引入实体 jar开发模式下 Play 不会生成 jar 文件jar-file会以FileNotFoundException失败生产模式下生成的 application jar 文件名会随版本号变化硬编码 jar 名无法稳定工作。因此正确做法始终是让persistence.xml与实体类一起被打进应用 jar。更详细的说明参见 JavaJPA.md 的 Deploying Play with JPA 一节。迁移检查清单完成 Play 2.6 的 JPA 迁移后建议按以下清单逐项核对代码层面全局搜索并清除JPA.jpaApi、JPA.em(...)、JPA.bindForAsync(...)、JPA.withTransaction(...)的全部调用这些方法在 2.6 已编译失败。代码中不再直接引用play.db.jpa.JPA类型全部改为注入JPAApi。所有 JPA 操作通过jpaApi.withTransaction(...)执行事务边界由 API 自动管理。异步层面将 JPA 调用包裹在自定义执行上下文如CustomExecutionContext中。Controller 方法返回CompletionStage不在渲染线程上执行阻塞查询。线程池大小与 JDBC 连接池大小匹配使用thread-pool-executor。配置层面conf/application.conf已配置db.default.jndiName与jpa.default。conf/META-INF/persistence.xml中的持久化单元名与jpa.default一致。build.sbt已配置外部化资源persistence.xml位于应用 jar 内。验证开发模式sbt run下 JPA 查询、事务回滚行为正常。生产打包sbt dist后检查应用 jar 内包含META-INF/persistence.xml。总结Play Framework 2.6 的 JPA 迁移可以概括为一句话从全局静态 JPA走向注入式 JPAApi 自定义执行上下文。本次迁移文档的三项变更——移除四个废弃方法、废弃JPA类、新增异步警告——共同指向同一个目标让 JPA 在 Play 的异步世界里以可管理、可测试、不阻塞渲染线程的方式运行。借助当前仓库play-java-jpa模块的 JPAApi、DefaultJPAApi、JPAModule 与 DefaultJPAConfig 源码开发者可以逐行验证迁移后的行为事务由 API 统一管理、EntityManager 始终被关闭、EntityManagerFactory 生命周期由 DI 容器接管。按照本文的迁移步骤与检查清单执行即可平稳跨越 2.6 这道分水岭并为后续版本如 JPA 规范升级与 Jakarta 命名空间迁移打下干净的基础。赞分享后端Web框架【免费下载链接】playframeworkThe Community Maintained High Velocity Web Framework For Java and Scala.项目地址https://gitcode.com/gh_mirrors/pl/playframework点击查看免费下载相关推荐Play Framework 2.6 Cache API 迁移指南从 CacheApi 到 Sync/Async CacheApiPlay Framework 2.6 Cache API 迁移指南从 CacheApi 到 Sync/Async CacheApi 本文是 Play Fram后端Web框架Play Framework 迁移指南移除 GlobalSettings全面转向依赖注入Scala 与 JavaPlay Framework 迁移指南移除 GlobalSettings全面转向依赖注入Scala 与 Java 本文基于 Play Framework后端Web框架Commander.js 废弃功能完全指南已弃用Deprecated与已移除RemovedAPI 迁移手册Commander.js 废弃功能完全指南已弃用Deprecated与已移除RemovedAPI 迁移手册 Commander.js 是 Node.jCLI创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考