企业官网建设流程全解析

• 后端
• Web框架

本文基于 dev-mode/sbt-plugin/src/sbt-test/README.md 展开。该文档是 Play Framework 的 sbt 插件（sbt-plugin）内置 scripted 测试的"总纲"，描述了 Play 如何通过 sbt 官方的 scripted 测试框架，对 Evolutions（数据库演进）、应用优雅关机（Coordinated Shutdown）与资源回收、HTTP 后端（Pekko HTTP / Netty）选择等核心机制做端到端验证。读完本文，你将掌握这些测试套件的逻辑分组、典型脚本写法、支撑命令的底层实现，以及如何在自己的 Play 插件项目中搭建类似的 scripted 测试体系。

一、什么是 sbt scripted 测试，Play 如何组织它们

sbt scripted是 sbt 官方提供的"测试插件本身"的机制：每个测试是一个独立的迷你 sbt 工程（fixture），外加一个名为test的脚本文件。脚本中的>行表示在 sbt 里执行命令，$行表示执行文件操作（如exists、delete、copy-file、sleep），前缀-表示"反向断言"（例如-$ exists表示断言该文件不存在），前缀->表示"该命令应当失败"。

Play 的 sbt 插件把这些测试全部收集在play-sbt-plugin目录下，其目的在 README 中写得非常直白：

They are all in the play-sbt-plugin directory so we can use scripted's "play-sbt-plugin/*1of3" feature to auto-split the tests into groups and run them in parallel build jobs.

也就是说，把测试都放在同一个目录下，是为了能使用 scripted 的play-sbt-plugin/*1of3特性，把测试自动切分成多组、在并行构建任务中运行，从而缩短 CI 耗时。

整个测试目录的实际结构见 dev-mode/sbt-plugin/src/sbt-test/play-sbt-plugin，包含 40 余个以-分隔的 fixture 工程，而 README 按逻辑分组将其归为四大套件：

每个 fixture 工程的project/plugins.sbt通过系统属性引入当前构建中的插件版本，例如 shutdown-happy-path 的 plugins.sbt：

updateOptions := updateOptions.value.withLatestSnapshots(false) addSbtPlugin("org.playframework" % "sbt-plugin" % sys.props("project.version")) addSbtPlugin("org.playframework" % "sbt-scripted-tools" % sys.props("project.version"))

其中sbt-scripted-tools提供了测试脚本里用到的一系列辅助命令（详见本文第五节），sys.props("project.version")确保测试的是当前正在构建的插件版本，而不是发布到仓库的旧版本。

二、Maven Layout 测试套件：maven-layout-

README 对它的定位很简短但意图明确：

This holds a few regression tests. When Maven Layout becomes the default Layout for Play this test suite can be removed.

它存放一批回归测试，防止 Maven 目录布局下的行为退化；一旦 Maven Layout 成为 Play 的默认 Layout，这套测试就会被移除。从源码结构看，它目前处于"过渡期临时存在"的状态。

以 maven-layout-twirl-reload/test 为例，可以直观看到 scripted 脚本如何驱动 dev 模式并验证 Twirl 模板热重载：

# Start dev mode > clean > run # Existing file change detection > verifyResourceContains / 200 Original $ copy-file src/changes/index.scala.html.1 src/main/twirl/views/index.scala.html > verifyResourceContains / 200 First $ copy-file src/changes/index.scala.html.2 src/main/twirl/views/index.scala.html > verifyResourceContains / 200 Second > playStop

几个要点：

• 目录布局：源文件不在src/main/scala下的标准 sbt 布局，而是src/main/twirl/views/，这正是 Maven 布局在 Play 中的体现（模板目录随布局移动）。
• 热重载验证：用copy-file覆盖模板文件后，紧接着的verifyResourceContains请求必须能拿到新内容（Original → First → Second），证明 dev 模式的 watch 服务捕捉到了文件变更并完成增量编译。由于底层文件监听（JDK watch service 可能退化为轮询）存在时间戳粒度问题，verifyResourceContains本身内置了最多 30 次、每次 500ms 的重试（见第五节），这正与 README 中"回归测试"的定位相符：它守护的是文件变更检测这条关键链路不退化。

三、Evolutions 测试套件：evolutions-

这是 README 中描述最详细的一套，验证 Play Evolutions（数据库演进）在 DEV 与 PROD 两种模式下的完整行为。对应目录有evolutions-auto-apply-false、evolutions-auto-apply-true、evolutions-multiple-databases、evolution-path-config四个 fixture。

3.1 DEV 模式

README 列出四条主线，逐一对应脚本实现：

1. 有变更但autoApply=false时，询问后再应用

见 evolutions-auto-apply-false/test：

> run # Needs evolution since autoApply=false for this test > verifyResourceContains / 500 evolution > applyEvolutions /@evolutions/apply/default > verifyResourceContains / 200 1_PlayerFromFirstEvolution 2_PlayerFromStartupInit 3_PlayerFromControllerInit

要点：

• 首次启动时存在待应用的演进，但由于autoApply=false，应用不会自动应用，页面返回500且内容包含evolution字样（即 Play 的"需要演进"提示页）；
• 手动调用applyEvolutions /@evolutions/apply/default（本质是请求http://localhost:9000/@evolutions/apply/default）后，演进被应用，页面恢复200并包含各演进写入的数据标记；
• 随后copy-file changes/2.sql conf/evolutions/default/2.sql放入一个新的演进脚本，文件 watcher 感知后再次出现500 evolution，再次applyEvolutions后新数据出现——这正是 README 中"Detects new evolution as ask to apply"的场景。

2.autoApply=true时无需询问自动应用

见 evolutions-auto-apply-true/test：

> run # Evolutions will be applied automatically since autoApply=true > verifyResourceContains / 200 1_PlayerFromFirstEvolution 2_PlayerFromStartupInit 3_PlayerFromControllerInit # Add a new evolution to verify that it will be applied automatically $ copy-file changes/2.sql conf/evolutions/default/2.sql $ sleep 2000 > verifyResourceContains / 200 4_PlayerFromSecondEvolution 5_PlayerFromStartupInit 6_PlayerFromControllerInit

启动后无需任何干预，第一次请求就是200；放入新演进后，等待 2 秒（$ sleep 2000，给文件 watcher 反应时间），新演进也被自动应用。

3. 演进脚本有错误时展示错误，并支持"标记为已解决"

继续看evolutions-auto-apply-false的后半段：

# Copy evolution with invalid commands $ copy-file changes/3.sql conf/evolutions/default/3.sql $ sleep 2000 # First try to apply evolution > applyEvolutions /@evolutions/apply/default # It will then fail since there is error > verifyResourceContains / 500 evolution # And it can be market as resolved > applyEvolutions /@evolutions/resolve/default/3 > verifyResourceContains / 200 7_PlayerFromThirdEvolution

含非法 SQL 的演进在应用时报错，页面回到500 evolution错误态；此时用户可通过/@evolutions/resolve/default/3将第 3 个演进标记为已手工修复，随后应用恢复正常。这正是 README 中"Accepts the user request to consider the error manually fixed"的完整闭环。

4. 多数据库演进

见 evolutions-multiple-databases/test，它对应 README 列出的四种组合场景（两库都autoApply=false、一库false一库true、对false库询问、对true库自动应用）：

> run # We will see that groups need some evolution > verifyResourceContains /groups 500 groups > applyEvolutions /@evolutions/apply/groups > verifyResourceContains /users 200 Player1 > verifyResourceContains /groups 200 Group1 # Add a new evolution to verify that it will be applied automatically $ copy-file changes/users/2.sql conf/evolutions/users/2.sql $ sleep 2000 > verifyResourceContains /users 200 Player2 # Add a new evolution to the database that requires manual intervention $ copy-file changes/groups/2.sql conf/evolutions/groups/2.sql $ sleep 2000 > verifyResourceContains /groups 500 groups > applyEvolutions /@evolutions/apply/groups > verifyResourceContains /groups 200 Group2 > playStop

可以看到：users库配置为自动应用，新演进无需干预直接生效；groups库需要手动确认，出现500后通过applyEvolutions /@evolutions/apply/groups应用（注意路径中带库名groups）。所有演进 URL 都支持按数据库名区分。

演进配置存放于 fixture 的conf/application.conf，例如 evolutions-auto-apply-false 的配置：

db.default.driver=org.h2.Driver db.default.url="jdbc:h2:mem:auto_apply_evolutions_false" play.modules.enabled += "startup.StartupModule"

演进 SQL 按conf/evolutions/{数据库名}/N.sql的约定存放，脚本通过copy-file动态追加新版本，从而模拟"运行中新增演进"的真实场景。

3.2 PROD 模式

README 的两条 PROD 断言在evolutions-auto-apply-true与evolutions-auto-apply-false脚本尾部均有体现。

autoApply=true：应能正常启动

# Generate a secret so that won't be the cause of the failure > playUpdateSecret # Should start successfully when there are evolutions and `autoApply=true` > runProd --no-exit-sbt $ sleep 4000 $ exists target/universal/stage/RUNNING_PID > verifyResourceContains / 200 1_PlayerFromFirstEvolution 2_PlayerFromSecondEvolution 3_PlayerFromStartupInit 4_PlayerFromControllerInit > stopProd --no-exit-sbt

runProd --no-exit-sbt以 PROD 模式启动（--no-exit-sbt表示不退出 sbt 进程），playUpdateSecret先生成应用密钥以避免"secret 未配置"这一无关因素干扰测试。启动后断言RUNNING_PID文件存在，且所有演进数据（含后来追加的第二版）都已就绪。

autoApply=false：应启动失败

> playUpdateSecret # Should fail to start when there are evolutions and `autoApply=false` -> runProd $ sleep 4000 # And since it fail to start, there should be no pid file -$ exists target/universal/stage/RUNNING_PID

-> runProd断言该命令预期失败（PROD 模式拒绝带未应用演进而启动）；随后 4 秒后断言RUNNING_PID不存在——因为进程根本没能起来。这两条测试把"PROD 模式强约束"的行为固化为可自动验证的回归用例。

四、Shutdown 测试套件：shutdown-

这是 README 中篇幅最大的部分，目标是：

This collection of scripted tests helps ensuring the correct resource de-alloc in as many scenarios as possible.

即在尽可能多的场景下确保资源被正确释放（线程池、ActorSystem、连接等）。Play 3.x 基于 Apache Pekko，应用优雅关机依赖 Pekko 的CoordinatedShutdown（协调关机）机制，它按阶段（Phase）依次执行注册的任务，最后决定是否退出 JVM。

4.1 测试分组与覆盖矩阵

README 明确指出：为降低维护成本与执行时间，测试被合并进少数 scripted 套件（代价是单个测试失败时可见性降低）。两个套件分别是：

• shutdown-happy-path（happy path，正常路径）：
  • 6-：Mode.Dev + 文件变更触发 dev 模式重载
  • 5-：Mode.Dev + Ctrl-D 停止 dev 模式
  • 3-：Mode.Test + 非 fork 测试
  • 1-：Mode.Prod +SIGTERM结束
• shutdown-downing（downing，集群降级路径）：
  • 7-：Mode.Dev +Downing 事件停止 dev 模式
  • 4-：Mode.Test + fork 测试
  • 2-：Mode.Prod +Downing 事件结束

数字编号对应 README "Using default settings" 一节的 1–7 号用例，两个套件合起来正好覆盖全部 7 个场景。

4.2 通用要求：PID 文件

README 的 General requirements 定义了一条硬性规则：

Only when running Play in Mode.Prod requires producing apidfilethat must be deleted when the process completes. That file must only exist during the life-span of a PROD process (never TEST nor DEV).

只有 PROD 模式才需要产生pidfile（即RUNNING_PID），且进程结束时必须删除；TEST 与 DEV 模式永远不应当存在该文件。这条规则在脚本中以正反断言反复出现：DEV/Test 阶段用-$ exists target/universal/stage/RUNNING_PID断言不存在，PROD 阶段用$ exists ...断言存在、关机后用-$ exists ...断言已被删除。

4.3 默认设置下的 7 个用例

逐一对照 shutdown-happy-path/test 与 shutdown-downing/test：

用例 1/2 — Mode.Prod：SIGTERM或程序化事件（Downing）后进程结束

## 1. Start prod mode > runProd --no-exit-sbt $ sleep 1000 > verifyResourceContains / 200 # Mode.Prod creates a PID_FILE $ exists target/universal/stage/RUNNING_PID ## 2. Mode.Prod exits the JVM > assertProcessIsStopped > awaitPidfileDeletion $ exists target/proofs/application-actorsystem-name.txt -$ exists target/universal/stage/RUNNING_PID

assertProcessIsStopped的实现（见 ScriptedTools.scala）非常典型：从RUNNING_PID读取 PID，调用PlayRun.stop发送SIGTERM，然后用jps轮询（最多 30 秒、每 3 秒一次）确认ProdServerStart进程退出；若超时仍存活则抛异常。shutdown-downing的 PROD 分支则用> assertProcessIsStopped simulate-downing，通过请求/simulate-downing端点触发程序化关机（模拟集群Downing 事件）。

用例 3/4 — Mode.Test：非 fork 与 fork 测试

## Run user integration tests > test # Mode.Test doesn't create a PID_FILE but runs CoordinatedShutdown -$ exists target/universal/stage/RUNNING_PID $ exists target/proofs/application-actorsystem-name.txt

两种模式都不产生RUNNING_PID，但都要求Coordinated Shutdown 确实执行过——通过检查"证明文件"target/proofs/application-actorsystem-name.txt是否存在来断言。区别在 JVM 行为上：非 fork 测试执行完毕后不退出 JVM（sbt 进程继续），fork 测试则退出 JVM。README 强调，这类断言很多是隐式的：

some assertions on this test are implicit. e.g. asserting dev.mode doesn't exit the JVM is implicitly asserted by runningMode.Dev testsfirst and asserting the whole test moves on toMode.Test tests

即"dev 模式不退出 JVM"是通过"dev 测试跑完后整个脚本还能继续执行 Mode.Test 部分"来间接证明的——如果 dev 模式把 JVM 退出了，后面的步骤根本不会发生。

用例 5 — Mode.Dev + Ctrl-D（playStop）

## Stopping Mode.Dev runs Coordinated Shutdown in both Server and Application Actor Systems > playStop $ exists target/proofs/application-actorsystem-name.txt

playStop等价于用户在 dev 模式控制台按 Ctrl-D。脚本断言关机后"证明文件"存在，说明 Coordinated Shutdown 已运行。测试文件中的注释也指出了该场景的一个验证难点：

# TODO: assert the `play-dev-mode` CS was executed # Asserting the `play-dev-mode` CS was executed is tricky because it's not available to the user

即 dev 模式自身的关机阶段（play-dev-mode）不对用户暴露，难以直接断言，属于已知的验证盲区。

用例 6 — Mode.Dev + 文件变更触发热重载

# Force a reload (copy a new file + produce a request) $ copy-file changes/HomeController.scala src/main/scala/controllers/HomeController.scala $ sleep 1000 > verifyResourceContains / 200 $ exists target/proofs/application-actorsystem-name.txt $ delete target/proofs/application-actorsystem-name.txt -$ exists target/proofs/application-actorsystem-name.txt

文件变更只应"杀死"Application（触发一次 App 的协调关机），dev 服务器与 JVM 都必须继续存活——所以删除证明文件后再触发一次请求，应用能重新起来并返回200。

用例 7 — Mode.Dev + Downing 事件

见 shutdown-downing/test 的 DEV 分支：

> verifyResourceContains /simulate-downing 200 $ sleep 4000 $ exists target/proofs/application-actorsystem-name.txt # Coordinated shutdown of the App has run but the Dev mode server isn't stopped (only the App) -$ exists target/universal/stage/RUNNING_PID $ sleep 1000 > verifyResourceContains / 200

请求/simulate-downing触发 App 的协调关机，4 秒后证明文件存在、RUNNING_PID不存在（dev 模式本就不该有）；最关键的一步是最后——关机后再请求依然返回 200，证明只有 Application 被回收，dev 服务器仍然健在并能重新拉起应用。

4.4 证明文件机制：Coordinated Shutdown 的"证据"

target/proofs/application-actorsystem-name.txt是怎么产生的？看 shutdown-happy-path 的 HomeController.scala，fixture 应用在启动时向CoordinatedShutdown注册了一个自定义任务：

class HomeController @Inject() ( val controllerComponents: ControllerComponents, actorSystem: ActorSystem, cs: CoordinatedShutdown, futures: Futures )(implicit executionContext: ExecutionContext) extends BaseController { // This task generates a file so scripted tests can assert `CoordinatedShutdown` ran. cs.addTask(CoordinatedShutdown.PhaseServiceUnbind, "application-cs-proof-of-existence") { () => logger.info("Running custom Coordinated Shutdown task.") val f = new java.io.File("target/proofs", actorSystem.name + ".txt") f.getParentFile.mkdirs f.createNewFile() Future.successful(Done) } ... }

任务挂在PhaseServiceUnbind阶段：当协调关机执行到"服务解绑"时，它把当前ActorSystem的名字写入target/proofs/{actorSystemName}.txt。测试脚本只需断言该文件"该出现时出现、该消失时消失"，就能判定关机流程是否走完、走的是哪个 ActorSystem。控制器还提供了一个slow端点（futures.delay(2.seconds)延迟 2 秒响应），供 PROD 用例验证"SIGTERM 时必须先处理完 in-flight 请求再退出"：

# Send a request to the slow action and record the response body > makeRequestAndRecordResponseBody /slow slow-request.txt $ sleep 1000 # Stops the process by sending a SIGTERM > assertProcessIsStopped # In-flight request should be recorded as expected $ exists target/slow-request.txt > checkRecordedRequestContains slow-request.txt DONE

这正是 README 中"SIGTERM-ing Mode.Prod must first finish in-flight requests"的落地：慢请求在关机信号发出时尚未完成，但最终记录下来的响应体仍完整包含DONE。

4.5 自定义设置（WIP，未完成部分）

README 的 "Using custom settings (WIP)" 列出几个对关机行为有重大影响、值得专门测试的设置，并说明"使用其中任一设置，都可能需要对默认设置用例做一项或多项变体测试"：

• a：使用pekko.coordinated-shutdown.exit-jvm是被禁止的——配置了它，Mode.Prod 根本无法启动；
• b：pekko.coordinated-shutdown.reason-overrides....exit-jvm（针对自定义关机原因指定是否退出 JVM）应当被遵守；
• c（TODO）：自定义exit-code应被遵守；
• d（TODO）：为自定义关机原因设置的exit-code应被遵守。

其中 c、d 两项在文档中仍标记为 TODO，说明这套测试还在持续演进——这也从侧面印证了 README 所述"以牺牲部分失败可见性为代价，换取维护成本与执行时间的降低"的取舍。

五、HTTP Backend 测试套件：http-backend-

Play 支持两种 HTTP 服务器实现：Pekko HTTP与Netty。README 指出本套件"针对不同 HTTP 后端提供的少量自定义行为测试"，核心关注点是Test 模式必须使用用户配置：

In Test mode, Play provides tools to handle the Server and Application lifecycles. These tools must create a server using the configured backend and the specified protocols.

即 Play 的测试工具（WithServer、WithApplication等）管理 Server 与 Application 生命周期时，必须按用户的配置选择后端并启用/禁用相应协议。对应两方面的验证：

• 后端是 Pekko HTTP 还是 Netty；
• HTTP/2 是否被启用/禁用。

各 fixture 的验证方式直观：通过检查响应头来判断当前后端。例如 http-backend-pekko-http/test 注释写明：

# Asserts the backend is Pekko HTTP via checking a particular header is added on the response # Asserts tests don't start an HTTP/2 endpoint > evicted > dependencyTree > test

而 http-backend-netty/test 则反向断言"该头部缺失"：

# Asserts the backend is Netty via checking a particular header is missing on the response # Asserts tests don't start an HTTP/2 endpoint > test

HTTP/2 场景由 http-backend-pekko-http-http2/test 覆盖，它断言测试能启动 HTTP/2 端点。此外还有两个特殊 fixture：

• http-backend-system-property：验证通过-Dplay.server.provider系统属性在 dev 模式切换后端。其 test 先以run -Dplay.server.provider=play.core.server.PekkoHttpServerProvider启动（响应含unknown标记），playStop后换成NettyServerProvider（响应含netty标记），再执行> test验证系统属性对测试同样生效；
• http-backend-netty-channel-options：针对 Netty 的 channel options 配置做验证（其目录下包含application.conf与 XML 配置，可推断是验证 Netty 相关底层选项的传递）。

六、测试基础设施：sbt-scripted-tools与辅助命令

所有测试脚本中用到的>命令并非 sbt 内置，而是由 dev-mode/sbt-scripted-tools 提供的。理解它的实现，就能把脚本里的每一行"翻译"成真实的网络与进程行为：

实现细节里有几个值得注意的点：

• 文件监听容错：verifyResourceContainsImpl的重试循环注释明确写道 "Using 30 max attempts so that we can give more chances to the file watcher service. This is relevant when using the default JDK watch service which does uses polling."——即默认 JDK watch service 可能退化为轮询，重试机制正是为了抵消这种不确定性；
• staging 目录稳定性：stableUniversalStagingDirectory把 Universal 的 staging 目录固定为target/universal/stage（L46-L51），并显式加入cleanFiles，原因是 "sbt 2's target is configuration-specific, but these fixtures assert the stable sbt 1 path"——fixture 断言的是稳定的 sbt 1 路径，因此需要跨 sbt 版本固定下来；
• SSL 支持：verifyResourceContainsSsl会先安装信任所有证书的SSLContext（setupSsl），用于https://localhost:9443的 HTTPS 场景。

七、在本地运行这些测试

这些 scripted 测试随 Play 源码库构建时执行，无需单独安装额外依赖。运行方式：

# 在仓库根目录执行，运行 sbt-plugin 的全部 scripted 测试 sbt "sbt-plugin/scripted" # 只运行特定套件（fixture 目录名） sbt "sbt-plugin/scripted play-sbt-plugin/evolutions-auto-apply-true" sbt "sbt-plugin/scripted play-sbt-plugin/shutdown-happy-path" # 利用 1ofN 分片并行（CI 常用），例如只跑 3 个分片中的第 1 片 sbt "sbt-plugin/scripted play-sbt-plugin/*1of3"

fixture 工程通过sys.props("project.version")引用当前源码构建的插件版本，因此必须先对仓库完成一次构建（使本地仓库中存在该版本快照）再运行 scripted，否则插件解析会失败。若希望独立复用这套机制，只需：

1. 在src/sbt-test/<group>/<fixture>/project/plugins.sbt中加入addSbtPlugin("org.playframework" % "sbt-plugin" % version)；
2. 编写test脚本，用>、$、-$、->描述 sbt 命令与文件断言；
3. 若需要verifyResourceContains等辅助命令，加入sbt-scripted-tools插件并在工程中引入ScriptedTools（其trigger = allRequirements，自动生效）。

八、小结：这套测试体系的工程价值

回顾整个src/sbt-test/README.md，可以提炼出 Play 团队设计脚本测试的几条方法论，对任何 sbt 插件作者都有借鉴意义：

1. 按目录前缀分组、按逻辑套件组织：物理上同处一个目录以复用*1ofN并行分片，逻辑上以maven-layout-、evolutions-、shutdown-、http-backend-前缀划分套件，兼顾 CI 并行度与可读性；
2. 用"证明文件"代替进程内状态断言：通过注册CoordinatedShutdown任务写文件（target/proofs/*.txt），让外部脚本能确认内部异步流程（关机）确实发生，是一种低成本、高确定性的验证手法；
3. 隐式断言与容错重试并重：JVM 是否存活这类状态用"脚本能否继续执行"隐式断言；文件监听延迟等不确定性用最多 30 次、每次 500ms 的重试吸收；
4. 区分模式（DEV/Test/PROD）与路径（happy path / downing）：同一能力（如协调关机）在不同模式下行为不同，测试矩阵按"模式 × 触发方式"铺开，覆盖 README 中编号 1–7 的全部用例。

对于阅读者而言，这套测试不仅是 Play 自身质量的保障，更是一份"如何为 sbt 插件编写端到端集成测试"的活教材：从 测试目录 到 辅助命令实现，每一层都有真实、可运行的代码可供对照与复用。

• 后端
• Web框架