Play 2.3 迁移指南:从 Play 2.2 平滑升级到 2.3 的完整实战手册

原创2026-09-23 21:06:051,674 阅读
文章标签:后端Web框架

Play 2.3 迁移指南:从 Play 2.2 平滑升级到 2.3 的完整实战手册

本文是 Play Framework 官方 2.2 → 2.3 迁移指南的深度解读与仓库源码佐证版。Play 2.3 是一次里程碑式的内部重构:构建系统全面切换到 sbt 0.13.5 的 Auto Plugins 机制,play 命令被 activator 取代,Html/CSS/JavaScript 资产处理被整体抽取为独立的 sbt-web 插件生态,模板引擎独立为 Twirl,WS 客户端变为可选库,结果类型(Result)体系完成收尾重构。阅读本文后,你将掌握从构建定义、资产管线、模板、WS、Anorm 到测试基类与 Session 配置的完整迁移路径,并能在当前仓库中逐一对证每一项变更的源码实现。

提示:如果你需要从更早的版本迁移,请先阅读 Play 2.2 迁移指南,再按本文步骤升级到 2.3。

Activator:从 play 命令到 activator 命令

Play 2.3 中最直观的变化是命令行入口:原来的 play 命令被 activator 命令取代,Play 全面转向使用 Activator(一个基于 sbt 的增强启动器)。

Activator 命令

原来 play 命令提供的所有能力在 activator 命令中全部保留:

需要特别说明的是:新的 activator 命令和旧的 play 命令本质上都是 sbt 的包装器。如果你更习惯底层工具,完全可以跳过 Activator 直接使用 sbt 命令。不过,直接使用 sbt 会丢失 Activator 的部分独有特性,例如项目模板(activator new)和 Web UI(activator ui)。sbt 与 Activator 都支持全部常规控制台命令,如 test 和 run。

Activator 发行版

Play 以 Activator 发行版的形式发布,该发行版内含 Play 的全部依赖,可从 Play 官方下载页面获取。两种获取方式:

  • 下载完整 Activator 发行版(包含 Play 所有依赖,开箱即用);
  • 从 Activator 站点下载约 1MB 的 mini 版("mini" 发行版),它只在需要时才按需下载依赖。

由于 Activator 是 sbt 的包装器,你同样可以直接下载并使用 sbt。

构建系统变更:sbt 0.13.5 与 Auto Plugins

Play 2.3 的构建体系发生了自 2.0 以来最大规模的重构,涉及 sbt 版本、插件机制、Play 插件启用方式与 Scala 版本声明四个层面。

升级 sbt 版本

Play 2.3 基于 sbt 0.13.5。升级现有项目时,将 project/build.properties 修改为:

sbt.version=0.13.5

升级 Play 插件版本

在 project/plugins.sbt 中修改 Play 插件版本:

addSbtPlugin("com.typesafe.play" % "sbt-plugin" % "2.3.XXX")

其中 2.3.XXX 是你想使用的具体 Play 版本号。此外,你还需按下文 sbt-web 一节的说明添加若干 sbt-web 插件。

Auto Plugins 与插件启用方式

sbt 0.13.5 引入了名为 "auto plugins" 的新特性,它改变了插件在构建中的启用语义:

  • 插件仍然像以前一样在 project 目录(通常是 plugins.sbt)中声明;
  • 变化在于:插件现在可以声明自己对其他插件的依赖,以及它在什么条件下被某个构建启用;
  • 在 auto plugins 之前,添加到构建中的插件总是对所有模块生效;现在插件可以对指定模块选择性启用。

这意味着仅仅声明 addSbtPlugin 可能不再足以让插件生效(对那些使用了 auto plugin 机制的插件而言)。这是一件好事——你可以按需选择项目中的哪些模块启用哪些插件,例如:

lazy val root = (project in file(".")).enablePlugins(SbtWeb)

上面的例子把 SbtWeb 添加到了构建的根项目。SbtWeb 是一类插件的 "root" 插件:如果同时通过 addSbtPlugin 添加了 sbt-less-plugin,那么只要 SbtWeb 被启用,该插件也会随之自动启用。

Play 自身也改用了 auto plugin 机制。Play 2.2 中通过 playJavaSettings / playScalaSettings 启用插件的做法已被移除,取而代之的是:

lazy val root = (project in file(".")).enablePlugins(PlayJava)

或(Scala 项目):

lazy val root = (project in file(".")).enablePlugins(PlayScala)

如果你以前使用 play.Project,例如一个 Scala 项目:

object ApplicationBuild extends Build {

  val appName = "myproject"
  val appVersion = "1.0-SNAPSHOT"

  val appDependencies = Seq()

  val main = play.Project(appName, appVersion, appDependencies).settings(
  )

}

……那么可以改用原生 sbt 的等价写法:

object ApplicationBuild extends Build {

  val appName = "myproject"
  val appVersion = "1.0-SNAPSHOT"

  val appDependencies = Seq()

  val main = Project(appName, file(".")).enablePlugins(play.PlayScala).settings(
    version := appVersion,
    libraryDependencies ++= appDependencies
  )

}

切换到上述风格后,插件一旦启用,其设置会被自动导入,不再需要手动 .settings(...) 导入。

PlayKeys:Play 提供的 sbt key 需限定引用

Play 提供的 key 现在必须通过 PlayKeys 对象引用。例如引用 playVersion 时,要么先导入:

import PlayKeys._

要么用全限定名 PlayKeys.playVersion。

如果不使用 .sbt 文件(即用完整 Scala 语法描述构建),可以在作用域内引入 PlayKeys:

import play.Play.autoImport._
import PlayKeys._

显式声明 scalaVersion

Play 2.3 同时支持 Scala 2.11 和 Scala 2.10。此前 Play 插件会自动为你设置 scalaVersion;现在需要你明确指定。在 build.sbt 或 Build.scala 中加入 Scala 版本:

  • 使用 Scala 2.11:
scalaVersion := "2.11.1"
  • 使用 Scala 2.10:
scalaVersion := "2.10.4"

sbt-web:资产处理全面外置

Play 2.3 最大的新特性是引入 sbt-web,它把 Html、CSS 与 JavaScript 相关的处理能力从 Play 核心中剥离,形成一族纯粹的 sbt 插件。这带来两大好处:

  • Play 对 Html/CSS/JavaScript 的立场不再那么"固执己见";
  • sbt-web 可以拥有自己的社区,与 Play 并行发展。

此外,sbt-web 插件可以在 JVM 内通过 Trireme 运行,也可以原生使用 Node.js 运行。需要注意:sbt-web 是开发期环境,不参与 Play 应用的运行期执行。Trireme 是默认引擎;如果你安装了 Node.js,并希望构建更快,可以通过 sbt 的 SBT_OPTS 环境变量指定系统属性来切换:

export SBT_OPTS="$SBT_OPTS -Dsbt.jse.engineType=Node"

sbt-web 的一个特性是:它不关心你的目录叫 javascripts 还是 stylesheets,只要文件扩展名匹配,就会被从 app/assets 目录中过滤出来参与处理。

资产目录:全部从 public 提供

sbt-web 的一个细节变化是:所有资产都从 public 目录提供。如果你此前将资产放在 public 之外,例如使用过 playAssetsDirectories 设置:

playAssetsDirectories <+= baseDirectory / "foo"

那么现在应改为:

unmanagedResourceDirectories in Assets += baseDirectory.value / "foo"

但要注意:放在那里的文件会被聚合进最终的 public 目录。这意味着 public/a.js 会被 foo/a.js 覆盖。另一种做法是在项目的 public 目录下使用子目录来做命名空间隔离。

sbt-web 相关组件与版本清单

以下是 Play 2.3 发布时点全部 sbt-web 相关组件及其版本:

Libraries(库)

"com.typesafe" %% "webdriver" % "1.0.0"
"com.typesafe" %% "jse" % "1.0.0"
"com.typesafe" %% "npm" % "1.0.0"

sbt plugins(插件)

"com.typesafe.sbt" % "sbt-web" % "1.0.0"
"com.typesafe.sbt" % "sbt-webdriver" % "1.0.0"
"com.typesafe.sbt" % "sbt-js-engine" % "1.0.0"

"com.typesafe.sbt" % "sbt-coffeescript" % "1.0.0"
"com.typesafe.sbt" % "sbt-digest" % "1.0.0"
"com.typesafe.sbt" % "sbt-gzip" % "1.0.0"
"com.typesafe.sbt" % "sbt-less" % "1.0.0"
"com.typesafe.sbt" % "sbt-jshint" % "1.0.0"
"com.typesafe.sbt" % "sbt-mocha" % "1.0.0"
"com.typesafe.sbt" % "sbt-rjs" % "1.0.1"

WebJars:前端依赖的声明式管理

WebJars 在 Play 2.3 的资产供给中扮演了重要角色。例如声明使用流行的 Bootstrap 库,只需在构建文件中加入依赖:

libraryDependencies += "org.webjars" % "bootstrap" % "3.2.0"

WebJars 会被自动解压到 public 资产相对路径下的 lib 文件夹中。例如声明了对 RequireJs 的依赖后,可以在视图中这样引用:

<script data-main="@routes.Assets.at("javascripts/main.js")" type="text/javascript" src="@routes.Assets.at("lib/requirejs/require.js")"></script>

注意 lib/requirejs/require.js 这个路径:lib 表示解压后的 WebJar 资产,requirejs 对应 WebJar 的 artifactId,require.js 是 WebJar 根目录下的目标资产文件。

npm:与 WebJars 并行的资产来源

除了 WebJars,还可以使用 npm:在项目根目录声明一个 package.json 即可。npm 包中的资产会被解压到与 WebJars 相同的 lib 文件夹,因此从代码视角看,无需关心资产究竟来自 WebJar 还是 npm 包。

CoffeeScript

必须在 plugins.sbt 中显式声明插件:

addSbtPlugin("com.typesafe.sbt" % "sbt-coffeescript" % "1.0.0")

CoffeeScript 的选项相比 2.2 有所变化,新选项为:

  • sourceMap:为真时生成 sourceMap 文件,默认 true。

    CoffeeScriptKeys.sourceMap := true

  • bare:为真时生成不带顶层函数安全包装的 JavaScript,默认 false。

    CoffeeScriptKeys.bare := false

LESS

必须在 plugins.sbt 中显式声明插件:

addSbtPlugin("com.typesafe.sbt" % "sbt-less" % "1.0.0")

入口点现在通过过滤器(filter)声明。例如声明需要编译 foo.less 和 bar.less:

includeFilter in (Assets, LessKeys.less) := "foo.less" | "bar.less"

如果你以前使用"下划线开头的 less 文件被忽略、其余全部编译"的行为,则使用以下过滤器组合:

includeFilter in (Assets, LessKeys.less) := "*.less"

excludeFilter in (Assets, LessKeys.less) := "_*.less"

与 Play 2.2 不同,sbt-less 插件允许任何用户下载原始 LESS 源文件和生成的 source map,方便在现代浏览器中调试——该特性在生产模式下同样开启。

sbt-less 插件的选项如下:

Option Description
cleancss 使用 clean-css 压缩输出。
cleancssOptions 向 clean css 传递选项,使用 https://github.com/GoalSmashers/clean-css 的 CLI 参数。
color LESS 输出是否着色。
compress 通过移除部分空白来压缩输出。
ieCompat 进行 IE 兼容性检查。
insecure 允许从不安全的 https 主机导入。
maxLineLen 最大行长度。
optimization 设置解析器的优化级别。
relativeUrls 将相对 URL 重写为相对于基准 less 文件。
rootpath 为相对导入和 url 中的 url 重写设置 rootpath。
silent 抑制错误消息输出。
sourceMap 输出 v3 sourcemap。
sourceMapFileInline source map 是否内嵌到输出文件中。
sourceMapLessInline 是否将 less 代码内嵌到 source map 中。
sourceMapRootpath 将该路径附加到 sourcemap 文件名和 less 文件路径上。
strictImports 导入是否严格。
strictMath 要求使用括号。该选项未来可能默认为 true 并被移除。
strictUnits 所有单位是否严格,或允许混合单位。
verbose 输出详细信息。

Closure Compiler 被 JSHint 与 UglifyJS 2 取代

Closure Compiler 已被替换。它的两个重要职能——校验 JavaScript 与压缩 JavaScript——被分别拆分到 JSHint 和 UglifyJS 2 中。

使用 JSHint 需在 plugins.sbt 中声明:

addSbtPlugin("com.typesafe.sbt" % "sbt-jshint" % "1.0.0")

选项遵循 JSHint 官方网站的约定,并共享同一组默认值。设置方式:在项目根目录提供 .jshintrc 文件;如果项目根目录没有该文件,则会在你的主目录中查找 .jshintrc。此行为可通过插件的 JshintKeys.config 设置覆盖,它用于指定配置文件的位置。

UglifyJS 2 目前经由 RequireJS 插件(见下)提供,未来计划为不使用 RequireJS 的场景提供独立的 UglifyJS 2 插件。

RequireJS(rjs):全新的资产管线优化器

RequireJS Optimizer(rjs)被整体替换为更易用的新实现,它属于 sbt-web 的资产管线(asset pipeline)功能。与旧版每次构建都执行不同,新 rjs 仅在通过 stage 或 dist 任务生成发行包时才被调用。

在 plugins.sbt 中声明插件:

addSbtPlugin("com.typesafe.sbt" % "sbt-rjs" % "1.0.1")

将插件加入资产管线:

pipelineStages := Seq(rjs)

官方同时推荐把 sbt-digest 和 sbt-gzip 也纳入管线:sbt-digest 为 Play 的资产控制器提供文件指纹(fingerprint)能力,便于对资产做远期缓存(far-future caching);sbt-gzip 生成资产的 gzip 版本,资产控制器在请求时会优先返回 gzip 版本。此时 plugins.sbt 为:

addSbtPlugin("com.typesafe.sbt" % "sbt-digest" % "1.0.0")

addSbtPlugin("com.typesafe.sbt" % "sbt-gzip" % "1.0.0")

管线配置变为:

pipelineStages := Seq(rjs, digest, gzip)

管线的顺序很重要:应先优化文件,再生成摘要,最后对所有产物生成 gzip 版本。

RequireJS 优化的选项已完全改变,新选项如下:

Option Description
appBuildProfile 项目构建 profile 的内容。
appDir 存放应用 js 文件的顶层目录。实际上就是 rjs 读取的源文件夹。
baseUrl 相对于 assets 或 public 文件夹、存放 js 文件的目录。默认取 "js"、"javascripts" 或 "."(前两者都找不到时取 ".")。
buildProfile 在 appBuildProfile 提供的默认值之外附加的 build profile key -> value 设置,这里的设置也会替换任何默认值。
dir 默认情况下所有模块都相对于该路径定位,实际上是 rjs 的目标目录。
generateSourceMaps 默认生成 source maps。
mainConfig 默认使用 'main' 作为配置模块。
mainConfigFile 上述模块的完整路径。
mainModule 默认使用 'main' 作为模块。
modules 模块的 json 数组。
optimize 优化器名称,默认 uglify2。
paths 模块 id 到(构建路径,生产路径)二元组的 RequireJS 路径映射。默认情况下所有 WebJar 库都从 CDN 提供,其映射可以在这里找到(除非 cdn 被设为 None)。
preserveLicenseComments 是否保留注释。鉴于 source maps,默认 false(参见 requirejs.org 的 sourcemapcomments 错误说明)。
webJarCdns 用于定位 WebJars 的 CDN。默认将 "org.webjars" 映射到 "jsdelivr"。
webJarModuleIds 要使用的 webjar 模块 id 序列。

默认 ivy 本地仓库与缓存的变化

由于 Play 改用 Activator 作为启动器,现在它使用默认的 ivy 缓存和本地仓库。这意味着:任何你之前发布到 Play ivy 缓存、且仍然依赖的内容,都需要重新发布到主目录下 .ivy2 目录中的本地 ivy 仓库。

Results 结果类型重构收尾

Play 2.2 中已弃用一批结果类型,并引入部分新类型以帮助迁移;Play 2.3 完成了这次重构。

Scala 结果类型

以下来自 Play 2.1 的弃用类型与辅助方法已被移除:

  • play.api.mvc.PlainResult
  • play.api.mvc.ChunkedResult
  • play.api.mvc.AsyncResult
  • play.api.mvc.Async

如果你的代码仍在使用它们,请参考 Play 2.2 迁移指南 了解如何迁移到新的结果结构。

按 2.2 时的规划,2.3 将 play.api.mvc.SimpleResult 改名为 play.api.mvc.Result(取代原有的 Result trait)。为方便迁移引入了类型别名,因此你的 Play 2.2 代码在 2.3 下通常源码兼容;不过这个别名最终会被移除,官方已将其标记为弃用,推荐直接切换到 Result。在当前仓库的 Results.scala 中可以看到这一设计的最终形态:Result 是一个 case class,由 ResponseHeader(状态码 + HTTP 头)与 HttpEntity(响应体)组成,并附带 newSession、newFlash、newCookies、attrs 等可选字段,同时提供 withHeaders、withCookies 等一套不可变组合方法——这正是"简单结果(SimpleResult)"理念的现代实现。

Java 结果类型

以下来自 Play 2.1 的弃用类型与辅助方法已被移除:

  • play.mvc.Results.async
  • play.mvc.Results.AsyncResult

同样的,2.3 将 play.mvc.SimpleResult 改名为 play.mvc.Result。这对大多数 Java 代码是透明的,受影响最明显的地方是 Global.java 的错误回调和自定义 action 中。

模板引擎独立为 Twirl

Play 2.3 将模板引擎拆分为独立的 Twirl 项目,随之而来的是包名与 sbt 设置的变化。

内容类型迁移到 twirl 包

模板内容类型移到了 twirl 包。如果代码引用了 play.mvc.Content 类型,需更新为 play.twirl.api.Content。例如 Play Java 项目中的以下代码:

import play.mvc.Content;

Content html = views.html.index.render("42");

会产生编译错误:

[error] ...: incompatible types
[error] found   : play.twirl.api.Html
[error] required: play.mvc.Content

需要改为导入 play.twirl.api.Content。

sbt 设置变化

模板的 sbt 设置改由 sbt-twirl 插件提供。

此前向模板添加额外导入的写法:

templatesImport += "com.abc.backend._"

现在是:

TwirlKeys.templateImports += "org.abc.backend._"

此前指定自定义模板格式的写法:

templatesTypes += ("html" -> "my.HtmlFormat.instance")

现在是:

TwirlKeys.templateFormats += ("html" -> "my.HtmlFormat.instance")

对于使用完整 Scala 语法描述的 sbt 构建,可以通过以下方式导入 TwirlKeys:

import play.twirl.sbt.Import._

Html.empty 改为 HtmlFormat.empty

如果之前使用 Html.empty(即 play.api.templates.Html.empty),现在必须改用 play.twirl.api.HtmlFormat.empty。

Play WS 变为可选库

WS 客户端在 2.3 中成为可选库。如果项目中使用 WS,需要显式添加库依赖;Java 项目还需要更新包名。

Java 项目

在 build.sbt 中添加库依赖:

libraryDependencies += javaWs

将源文件中的导入更新为新包:

import play.libs.ws.*;

(从当前仓库 transport/client/play-ws 模块的源码看,Java WS API 如今正是位于 play.libs.ws 包下,这与迁移后的目标形态一致。)

Scala 项目

在 build.sbt 中添加库依赖:

libraryDependencies += ws

此外,使用 WS 客户端现在要求作用域内存在 Play 应用,通常通过以下导入实现:

import play.api.Play.current

WS API 本身也略有变化:WS.client 现在返回 WSClient 实例,而不再是底层的 AsyncHttpClient 对象。如需底层客户端,可通过 WS.client.underlying 获取。

Anorm 的类型安全强化

Play 2.3 的 Anorm 包含多项变更,核心方向是提升类型安全。

为了让查询参数被正确转换,参数的类型必须是可见的。现在直接使用 Any 作为参数值(无论是显式声明还是由于类型擦除导致)都会产生编译错误:No implicit view available from Any => anorm.ParameterValue。

// 错误
val p: Any = "strAsAny"
SQL("SELECT * FROM test WHERE id={id}").
  on('id -> p) // 错误 - 没有 Any => ParameterValue 的转换

// 正确
val p = "strAsString"
SQL("SELECT * FROM test WHERE id={id}").on('id -> p)

// 错误
val ps = Seq("a", "b", 3) // 被推断为 Seq[Any]
SQL("SELECT * FROM test WHERE (a={a} AND b={b}) OR c={c}").
  on('a -> ps(0), // ps(0) - 没有 Any => ParameterValue 的转换
    'b -> ps(1),
    'c -> ps(2))

// 正确
val ps = Seqanorm.ParameterValue // Seq[ParameterValue]
SQL("SELECT * FROM test WHERE (a={a} AND b={b}) OR c={c}").
  on('a -> ps(0), 'b -> ps(1), 'c -> ps(2))

如果确实需要传递不经过安全转换的值,可以使用 anorm.Object(anyVal) 设置一个不透明参数。

同时,参数值的类型擦除问题也已修复:类型不再写作 ParameterValue[_],而是直接写 ParameterValue。

参数名称的类型也统一了(使用 .on(...) 时):现在只支持 String 和 Symbol 作为名称。

Pk[A] 弃用

Pk[A] 类型已被弃用。你仍然可以在列映射中使用它,但作为查询参数时必须显式传 Id[A] 或 NotAssigned(这是类型安全改进的直接后果):

// 列映射,已弃用但可用
val pk: Pk[Long] = SQL("SELECT id FROM test WHERE name={n}").
  on('n -> "mine").as(get[Pk[Long]].single)

// 错误的参数
val pkParam: Pk[Long] = Id(1l)
val name1 = "Name #1"
SQL"INSERT INTO test(id, name) VALUES($pkParam, $name1)".execute()
// ... pkParam 作为 Pk 传入查询参数,
// 现在作为参数类型是错误的(无法编译)

// 正确的参数 Id
val idParam: Id[Long] = Id(2l) // 与 pkParam 相同但保持显式 Id 类型
val name2 = "Name #2"
SQL"INSERT INTO test(id, name) VALUES($idParam, $name2)".execute()

// 正确的参数 NotAssigned
val name2 = "Name #3"
SQL"INSERT INTO test(id, name) VALUES($NotAssigned, $name2)".execute()

由于被弃用的 Pk[A] 与 Option[A] 类似,而 Anorm 在列映射和查询参数中都支持 Option[A],因此更推荐用 Some[A] 替换 Id[A]、用 None 替换 NotAssigned:

// 列映射,已弃用但可用
val pk: Option[Long] = SQL("SELECT id FROM test WHERE name={n}").
  on('n -> "mine").as(get[Option[Long]].single)

// 已赋值的主键作为参数
val idParam: Option[Long] = Some(2l)
val name1 = "Id"
SQL"INSERT INTO test(id, name) VALUES($idParam, $name1)".execute()

// 正确的参数 NotAssigned
val name2 = "NotAssigned"
SQL"INSERT INTO test(id, name) VALUES($None, $name2)".execute()

Bootstrap 字段构造器弃用

Play 内置的 Bootstrap 字段构造器(field constructor)已被弃用,将在未来版本中移除。原因有二:

  • Bootstrap 在不同版本间变化过于剧烈且频繁,Play 内置的任何支持很快就会过时,无法与当前 Bootstrap 版本兼容;
  • 当前 Bootstrap 对 CSS class 的需求无法仅靠 Play 的字段构造器实现,还需要自定义的输入模板(input template)。

官方观点是:如果这对社区有价值,可以由第三方模块针对特定 Bootstrap 版本提供一套独立的 Bootstrap 表单辅助模板,从而获得远比 Play 内置支持更好的用户体验。

Session 超时配置:从整数秒到 Duration

session.maxAge 配置项过去是整数,单位是秒;现在它被定义为 Duration(时长),可以用 1h 或 30m 这样的值来指定。

注意陷阱:如果省略时间单位,默认单位是毫秒。因此配置值 3600 过去表示 1 小时,现在只相当于 3.6 秒!你需要更新配置,为 session.maxAge 加上时间单位,例如:

play.http.session.maxAge = 1h

从当前仓库 Session.scala 的 SessionCookieBaker可以看到这一设计在源码层面的落点:Session cookie 的 maxAge 由 config.maxAge(一个 Option[Duration])经 .toSeconds.toInt 转换而来,即配置层接受时长(Duration),底层 cookie 仍按秒输出——配置语义与 HTTP cookie 语义在此完成衔接。

Java JUnit 测试超类:自动启动应用

Java 的 WithApplication、WithServer 和 WithBrowser JUnit 测试超类都新增了 @Before 注解的方法。此前你需要显式启动应用:

@Before
public void setUp() {
    start();
}

现在不再需要。如果需要提供自定义应用,可以覆写 provideFakeApplication 方法:

@Override
protected Application provideFakeApplication() {
    return Helpers.fakeApplication(Helpers.inMemoryDatabase());
}

这一设计延续至今:在当前仓库的 WithApplication.java中,@Before public void startPlay() 会调用 provideApplication()(其默认实现返回 Helpers.fakeApplication())并启动应用,测试结束后的 @After 方法负责停止应用,测试期间可通过受保护的 app 字段访问运行中的应用。WithServer 与 WithBrowser 在此基础上扩展了服务器与浏览器支持(WithBrowser.java 直接继承 WithServer)。

Session 与 Flash 隐式参数改名

Scala 的 Controller 提供隐式的 Session、Flash 和 Lang 参数,它们接收隐式 RequestHeader。这些参数是为了方便:例如模板可以接收隐式参数,在 Controller 中会被自动提供。为了避免这些参数名与应用局部同名变量发生遮蔽冲突,它们的名字被改了:

  • session 改为 request2Session
  • flash 改为 flash2Session
  • lang 改为 lang2Session

任何显式调用这些旧名字的代码都会因此编译失败。在当前仓库的 Controller.scala中可以看到这一约定的实现:trait RequestImplicits 定义了 implicit def request2session(implicit request: RequestHeader): Session = request.session 与 implicit def request2flash(implicit request: RequestHeader): Flash = request.flash。

官方不推荐显式调用这些隐式方法:session、flash 和 lang 都直接暴露在 RequestHeader 上,直接使用 RequestHeader 的属性会让代码读起来更清楚来源。因此,如果代码使用了旧方法,建议改为直接访问 RequestHeader 上对应的属性。

迁移检查清单

综合全文,从 Play 2.2 升级到 2.3 时建议按以下顺序逐项核对:

  1. 命令行工具:play → activator,并了解 activator ui 与 mini 发行版;
  2. 构建定义:project/build.properties 升级到 sbt 0.13.5;plugins.sbt 中更新 Play 插件到 2.3.XXX;playJavaSettings/playScalaSettings → enablePlugins(PlayJava)/enablePlugins(PlayScala);显式声明 scalaVersion;通过 PlayKeys 引用 Play 提供的 key;
  3. 资产管线:按需引入 sbt-web 系列插件(CoffeeScript、LESS、JSHint、rjs、digest、gzip 等),用 unmanagedResourceDirectories in Assets 替代 playAssetsDirectories,通过 WebJars / npm 管理前端依赖,配置 pipelineStages;
  4. ivy 仓库:将依赖重新发布到主目录 .ivy2 的本地 ivy 仓库;
  5. 结果类型:移除 AsyncResult/Async/Results.async 等,从 SimpleResult 切换到 Result;
  6. 模板:play.mvc.Content → play.twirl.api.Content,templatesImport/templatesTypes → TwirlKeys.templateImports/TwirlKeys.templateFormats,Html.empty → HtmlFormat.empty;
  7. WS:Java 项目添加 javaWs 依赖并改用 play.libs.ws 包,Scala 项目添加 ws 依赖,WS.client 返回 WSClient;
  8. Anorm:消除 Any 参数,必要时用 anorm.Object,Pk[A] 迁移到 Option[A],参数名仅用 String/Symbol;
  9. 配置:删除对内置 Bootstrap 字段构造器的依赖,为 session.maxAge 补上时间单位;
  10. 测试:利用 WithApplication/WithServer/WithBrowser 自带的 @Before,需要自定义时覆写 provideFakeApplication;
  11. 隐式参数:将显式调用的 session/flash/lang 改为 RequestHeader 上的属性。

从 sbt 构建机制、资产管线到运行期 API,Play 2.3 的每一项变化都可以在当前仓库源码中逐一印证:构建与插件机制对应 project 目录下的构建定义,结果类型对应 Results.scala,Session 配置对应 Session.scala,隐式参数对应 Controller.scala,WS 客户端对应 transport/client/play-ws,测试超类对应 testkit/play-test。把迁移过程视为一次"理解新架构"的机会,升级就能顺利完成。

登录后查看全文
playframework