Play Framework 新应用创建指南：使用 sbt 与 giter8 模板快速搭建 Java / Scala 项目

Play Framework 新应用创建指南使用 sbt 与 giter8 模板快速搭建 Java / Scala 项目【免费下载链接】playframeworkThe Community Maintained High Velocity Web Framework For Java and Scala.项目地址: https://gitcode.com/gh_mirrors/pl/playframework本文基于 Play Framework 官方文档 NewApplication.md 及当前仓库配套文档Requirements、Anatomy、PlayConsole与 sbt 插件源码编写。核心主题是如何使用sbt new配合 giter8 模板用一条命令创建结构完整、可直接运行的 Play Java / Scala 项目。读完本文你将掌握交互式与命令行直连两种模板用法、创建后的启动验证流程、Play 标准项目布局与 sbt 默认布局的切换原理以及run/compile/test/console等日常开发命令。一、为什么用模板创建一次命令完成全套初始化Play Framework 对应用的项目结构有明确的约定Play 称之为 standardized layout目录组织直接决定 sbt 构建能否正确识别源码、配置与资源。官方为此提供了giter8 模板——一种类似 Maven archetype 的项目脚手架机制通过模板可以一次性完成三件事生成标准化的项目目录app、conf、public、project等写入构建声明build.sbt、project/plugins.sbt配置开发环境版本号、插件、示例控制器与首页模板。整个初始化过程只需要一条sbt new命令随后按提示回答问题即可。创建出的项目在结构上与仓库文档 Anatomy.md 描述的标准布局完全一致。环境前置条件在运行sbt new之前请确认本机满足以下条件依据官方文档 Requirements.mdJava LTS 版本 17 或 21可通过java -version验证输出应显示openjdk version 17.0.x或更高sbt launcher官方推荐安装最新版本。sbt 是 Play 的官方推荐构建工具提供 routes 编译、模板编译与自动重载auto-reloading等增强开发体验因此创建新项目时统一走sbt new。说明Play 应用运行时只依赖发布到 Maven 仓库的 JAR 文件理论上可用任意 Java/Scala 构建工具构建但只有 sbt 能提供完整的 Play 开发体验官方所有示例与文档均以 sbt 为前提。二、交互式创建sbt new进入模板选择菜单在命令行窗口中直接输入sbt newsbt 会加载 giter8 机制并展示可用的模板选择交互菜单。在菜单中选择playframework/play-scala-seed.g8—— 创建一个Play Scala项目playframework/play-java-seed.g8—— 创建一个Play Java项目选定模板后按提示回答问题通常包括项目名称、组织名、包名、Play 版本等不同模板提示略有差异。模板生成完成后进入项目顶层目录例如cd my-first-app执行sbt run首次运行会自动下载依赖并启动系统在浏览器中访问 http://localhost:9000/即可看到欢迎页面。这一流程也是官方文档 Introduction.md 中提到的快速上手路径模板会帮你搭好项目结构与开发环境让你把精力直接投入到业务代码上。三、命令行直连模板跳过交互菜单如果已经确定要使用的语言模板可以直接在命令中指定无需进入交互菜单。Java 模板sbt new playframework/play-java-seed.g8若要创建指定版本分支例如 Play 2.9的 Java 项目使用--branch参数sbt new playframework/play-java-seed.g8 --branch 2.9.xScala 模板sbt new playframework/play-scala-seed.g8指定 2.9 版本分支sbt new playframework/play-scala-seed.g8 --branch 2.9.x--branch参数对应 giter8 模板仓库的分支名可用于锁定模板版本如2.9.x、3.0.x等从而生成与目标 Play 大版本匹配的项目骨架。版本选择Play 2.9 与 3.0 的差异原文档特别提醒除了用 Pekko 替换 Akka 之外Play 3.0 与 Play 2.9 完全一致。如果不了解 Akka 与 Pekko 的区别官方建议直接使用 Play 3.0。关于版本选型的详细讨论可阅读文档 General.md 中 How Play Deals with Akkas License Change 一节。从当前仓库代码可以印证这一点Play 3.0 的 HTTP 服务器实现已经全面迁移到 Pekko 生态例如 PekkoHttpServer 与 play-pekko-http2-support 模块而集群分片功能由 cluster/play-cluster-sharding 提供这些都建立在 Pekko 之上。四、创建后首次启动sbt run与自动重载进入新项目目录后执行sbt run首次运行会解析依赖并启动 HTTP 服务器典型输出如下参考官方文档 PlayConsole.md[info] Loading project definition from /Users/play-developer/my-first-app/project [info] Set current project to my-first-app (in build file:/Users/play-developer/my-first-app/) --- (Running the application from sbt, auto-reloading is enabled) --- [info] play - Listening for HTTP on /0:0:0:0:0:0:0:0:9000 (Server started, use Enter to stop and go back to the console...)两个关键信息默认端口 9000服务器监听所有网卡的 9000 端口浏览器访问 http://localhost:9000/ 查看欢迎页。如需自定义端口可执行sbt run 8080注意 shell 引号自动重载auto-reloading已启用这是 Play 开发模式的标志性能力。在 sbt 交互模式下执行run后每次发起请求时 Play 都会检查源码变更自动重新编译并重启服务器让开发者立即看到修改结果。停止服务器按Enter或CtrlD可退出并返回 sbt shell或系统提示符。五、理解项目布局Play 标准结构新模板生成的项目遵循 Play 标准布局详见 Anatomy.md。首次编译成功后结构如下app → 应用源码 └ assets → 需要编译的资源源文件 └ stylesheets → 通常是 LESS CSS 源文件 └ javascripts → 通常是 CoffeeScript 源文件 └ controllers → 控制器 └ models → 业务层 └ views → 模板 build.sbt → 应用构建脚本 conf → 配置与其他非编译资源位于 classpath └ application.conf → 主配置文件 └ routes → 路由定义 dist → 需要打进分发包的任意文件 public → 公共静态资源 └ stylesheets → CSS 文件 └ javascripts → JavaScript 文件 └ images → 图片文件 project → sbt 工程配置 └ build.properties → sbt 项目标识含 sbt 版本 └ plugins.sbt → sbt 插件声明含 Play 插件本身 lib → 非托管依赖 logs → 日志目录 └ application.log → 默认日志文件 target → 构建产物 └ resolution-cache → 依赖解析信息 └ scala-2.13 └ api → 生成的 API 文档 └ classes → 编译后的 class 文件 └ routes → 由 routes 生成的源码 └ twirl → 由模板生成的源码 └ universal → 应用打包 └ web → 编译后的 web 资源 test → 单元/功能测试源码app/目录app目录存放所有可执行产物Java 与 Scala 源码、模板以及需要编译的资源源文件。默认包含 MVC 架构对应的三个包app/controllersapp/modelsapp/views也可以自行添加包例如app/services。需要特别注意的是controllers、models、views仅是约定命名可以按需修改例如统一加com.yourcompany前缀。另外app/assets是可选目录存放 LESS、CoffeeScript 等需要编译的资源源文件。public/目录public存放由 Web 服务器直接对外服务的静态资源官方建议按images、stylesheets、javascripts三个子目录组织以保持所有 Play 应用的一致性。在新创建的应用中/public目录默认映射到/assetsURL 路径这个映射可自由修改也可以配置多个静态资源目录。conf/目录conf包含应用的全部配置文件其中两个是最核心的application.conf—— 主配置文件格式为 HOCON详见官方文档 ConfigFile.mdroutes—— 路由定义文件负责 URL 与 Action 的映射。应用自身的扩展配置建议直接追加到application.conf第三方库如果要求独立配置文件也应放到conf目录下该目录位于 classpath运行时可加载。lib/目录lib是可选目录用于存放非托管依赖unmanaged dependencies即你希望绕过构建系统手动管理的 JAR 文件。只需把 JAR 丢进该目录就会自动加入应用 classpath。project/目录与target/目录project目录存放 sbt 构建定义plugins.sbt—— 声明本项目使用的 sbt 插件其中包含 Play 插件本身的声明build.properties—— 指定构建本应用所需的 sbt 版本。target目录存放构建系统生成的一切内容其中值得了解的子目录classes/—— 所有编译产物Java 与 Scalaclasses_managed/—— 仅含框架托管生成的类如路由器和模板系统生成的类IDE 中可将其作为外部类目录添加resource_managed/—— 生成的资源典型如 LESS CSS、CoffeeScript 的编译结果src_managed/—— 生成的源码如模板系统生成的 Scala 源码web/—— sbt-web 处理的资源来自app/assets与public。推荐的.gitignore构建产物目录不应纳入版本控制Play 官方推荐的.gitignore内容如下logs project/project project/target target tmp dist .bsp .cache RUNNING_PID六、深入Play 布局插件与 sbt 默认布局的切换从源码层面看Play 之所以默认采用上述app/conf/public结构是因为 sbt 插件中内置了一个名为PlayLayoutPlugin的 AutoPlugin源码位于 dev-mode/sbt-plugin/src/main/scala/play/sbt/PlayLayoutPlugin.scala。该插件的关键逻辑是将标准 sbt/Maven 布局的各个目录重定向到 Play 约定路径Compile / sourceDirectory : baseDirectory.value / app, Test / sourceDirectory : baseDirectory.value / test, Compile / resourceDirectory : baseDirectory.value / conf, Compile / scalaSource : baseDirectory.value / app, Compile / javaSource : baseDirectory.value / app, Assets / sourceDirectory : (Compile / sourceDirectory).value / assets, Assets / resourceDirectory : baseDirectory.value / public, Universal / sourceDirectory : baseDirectory.value / dist即源码目录指向app/、测试指向test/、配置资源指向conf/、静态资源指向public/、分发内容指向dist/同时为 Twirl 模板编译TwirlKeys.compileTemplates与 sbt-web 资源处理Assets配置对应源目录。切换回 sbt 默认布局如果你的团队更习惯 sbt/Maven 的标准布局src/main/java、src/main/scala、src/main/resources等可以禁用布局插件并显式配置 Twirl 模板的监控目录。官方文档 Anatomy.md 给出的示例配置见 code/anatomy.sbtlazy val root: Project (project in file(.)) .enablePlugins(PlayScala) // Use sbt default layout .disablePlugins(PlayLayoutPlugin).disablePlugins(PlayLayoutPlugin)会让 Play 停止覆盖 sbt 的默认目录布局。切换后项目结构变为build.sbt → 应用构建脚本 src → 应用源码 └ main └ java → Java 源码controllers、models ... └ scala → Scala 源码controllers、models ... └ resources → 配置与资源application.conf、routes └ twirl └ views → Twirl 模板 └ assets → 编译资源源文件css、js └ public → 静态资源css、js、images └ test → 测试源码java、scala、resources └ universal → 分发内容 project → sbt 配置build.properties、plugins.sbt lib → 非托管依赖 logs → 日志 target → 构建产物两种布局二选一即可Play 官方默认推荐前者Play 标准布局后者仅为习惯 Maven 布局的团队提供兼容选项。七、创建之后的日常开发命令项目创建完成、进入目录后除了sbt run官方文档 PlayConsole.md 还整理了完整的 sbt 开发循环命令命令用途典型用法run开发模式启动开启自动重载sbt run或sbt run 8080指定端口compile只编译、不启动服务器错误显示在终端[my-first-app] $ compiletest运行全部测试[my-first-app] $ testtestOnly只运行指定测试类[my-first-app] $ testOnly com.acme.SomeClassTestconsole进入 Scala 控制台交互式测试代码[my-first-app] $ consolehelp查看命令帮助[my-first-app] $ help runsbt 的两种使用方式单条命令模式每次执行sbt command都会重启一个 sbt 进程适合一次性操作交互模式在项目目录直接输入sbt进入 shell之后逐条输入命令。交互模式长期运行效率更高sbt 只需启动一次官方建议日常开发使用。也可以在一条命令中串联多个任务后再进入 shell例如sbt clean compile shell。触发式执行triggered execution利用 sbt 的~前缀可实现文件变更自动触发[my-first-app] $ ~ compile # 源码变更即自动编译 [my-first-app] $ ~ test # 源码变更即自动运行测试 [my-first-app] $ ~ testOnly com.acme.SomeClassTest # 配合 testOnly 只跑指定测试调试与 Scala 控制台需要远程调试时用sbt -jvm-debug port启动JVM 会开启 JPDA 调试端口$ sbt -jvm-debug 9999启动日志中出现Listening for transport dt_socket at address: 9999即表示调试端口已就绪可用 Java 调试器连接。在 sbt 交互模式中输入console可进入 Scala REPL结合官方示例 code/PlayConsole.scala 的写法可以在 REPL 中启动一个完整的 Play 应用实例例如用于访问数据库import play.api._ val env Environment(new java.io.File(.), this.getClass.getClassLoader, Mode.Dev) val context ApplicationLoader.Context.create(env) val loader ApplicationLoader(context) val app loader.load(context) Play.start(app)这段代码体现了 Play 的编程式启动机制ApplicationLoader根据Environment包含目录、类加载器与运行模式Mode.Dev构造应用上下文并加载应用Play.start将其启动为运行实例——与sbt run的底层加载路径一致。八、总结从模板到运行的完整链路以本文介绍的方式创建并运行一个 Play 应用完整流程可以概括为确认本机具备Java 17/21与sbtsbt new交互选模板或sbt new playframework/play-scala-seed.g8/sbt new playframework/play-java-seed.g8直连模板需要锁定版本时追加--branch 2.9.x进入生成的项目目录执行sbt run下载依赖并启动浏览器访问 http://localhost:9000/ 验证欢迎页按 Anatomy.md 的标准布局理解项目组织必要时通过disablePlugins(PlayLayoutPlugin)切换为 sbt 默认布局用compile/test/console/~触发执行等命令进入常规开发循环。模板化创建省去了手工搭建目录、编写构建脚本的重复劳动让新项目从第一秒起就处于可编译、可运行、可热重载的状态——这正是 Play High Velocity 开发体验的起点。【免费下载链接】playframeworkThe Community Maintained High Velocity Web Framework For Java and Scala.项目地址: https://gitcode.com/gh_mirrors/pl/playframework创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考