Play 2.3 迁移指南:从 Play 2.2 平滑升级到 2.3 的完整实战手册
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 new:创建新项目,参见 Creating a new application;activator:进入交互式控制台,参见 Using the Play console;activator ui:新增命令,启动一个 Web 图形用户界面。
需要特别说明的是:新的 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.PlainResultplay.api.mvc.ChunkedResultplay.api.mvc.AsyncResultplay.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.asyncplay.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改为request2Sessionflash改为flash2Sessionlang改为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 时建议按以下顺序逐项核对:
- 命令行工具:
play→activator,并了解activator ui与 mini 发行版; - 构建定义:
project/build.properties升级到 sbt 0.13.5;plugins.sbt中更新 Play 插件到2.3.XXX;playJavaSettings/playScalaSettings→enablePlugins(PlayJava)/enablePlugins(PlayScala);显式声明scalaVersion;通过PlayKeys引用 Play 提供的 key; - 资产管线:按需引入 sbt-web 系列插件(CoffeeScript、LESS、JSHint、rjs、digest、gzip 等),用
unmanagedResourceDirectories in Assets替代playAssetsDirectories,通过 WebJars / npm 管理前端依赖,配置pipelineStages; - ivy 仓库:将依赖重新发布到主目录
.ivy2的本地 ivy 仓库; - 结果类型:移除
AsyncResult/Async/Results.async等,从SimpleResult切换到Result; - 模板:
play.mvc.Content→play.twirl.api.Content,templatesImport/templatesTypes→TwirlKeys.templateImports/TwirlKeys.templateFormats,Html.empty→HtmlFormat.empty; - WS:Java 项目添加
javaWs依赖并改用play.libs.ws包,Scala 项目添加ws依赖,WS.client返回WSClient; - Anorm:消除
Any参数,必要时用anorm.Object,Pk[A]迁移到Option[A],参数名仅用String/Symbol; - 配置:删除对内置 Bootstrap 字段构造器的依赖,为
session.maxAge补上时间单位; - 测试:利用
WithApplication/WithServer/WithBrowser自带的@Before,需要自定义时覆写provideFakeApplication; - 隐式参数:将显式调用的
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。把迁移过程视为一次"理解新架构"的机会,升级就能顺利完成。