Play Framework 应用目录结构完全指南：从 Play 标准布局到默认 sbt 布局

后端Web框架【免费下载链接】playframeworkThe Community Maintained High Velocity Web Framework For Java and Scala.项目地址https://gitcode.com/gh_mirrors/pl/playframework点击查看免费下载本文以 Play Framework 官方文档《Anatomy of a Play application》为骨架系统讲解一个 Play 应用中每个目录与文件的职责从app/、conf/、public/三大核心目录到target/构建产物、.gitignore最佳实践以及如何通过PlayLayoutPlugin切换到 sbt/Maven 默认布局。读完本文你将能完全读懂一个 Play 项目的目录组织知道每种文件该放哪里、构建时它们去了哪里并能在两种布局之间自由切换。为什么 Play 需要标准化的目录布局Play Framework 的目录布局是标准化的目的是让事情尽可能简单keep things as simple as possible无论你使用 Play Scala 还是 Play Java无论团队中有多少人协作大家拿到一个 Play 项目都能立刻找到控制器、模板、路由和配置文件。更重要的是这个布局不只是约定——它直接由 sbt 插件在构建层面强制落地。Play 的 sbt 插件内置了一个名为PlayLayoutPlugin的 AutoPlugin源码位于 PlayLayoutPlugin.scala它负责把 sbt 默认的 Maven 风格目录重定向到 Play 的传统 Web 应用布局。它由PlayWeb插件自动触发override def trigger allRequirements因此只要是 Web 应用项目无需任何额外配置即可生效。Play 应用的标准布局总览在第一次成功编译之后一个 Play 项目的结构如下这是官方文档给出的标准形态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 项目标记 └ plugins.sbt → sbt 插件声明包括 Play 插件自身 lib → 非托管的库依赖 logs → 日志目录 └ application.log → 默认日志文件 target → 构建生成物 └ resolution-cache → 依赖解析信息 └ scala-2.13 └ api → 生成的 API 文档 └ classes → 编译后的 class 文件 └ routes → 由路由文件生成的源码 └ twirl → 由模板生成的源码 └ universal → 应用打包产物 └ web → 编译后的 Web 静态资源 test → 单元测试或功能测试源码注意target/scala-2.13中的scala-2.13是当前项目使用的 Scala 二进制版本。Play 目前支持 Scala 2.12、2.13 与 3.x见 Versions.scala如2.13.18、3.9.0等该目录名会随你所选的 Scala 版本变化。app/目录所有可执行代码的所在地app目录包含所有可执行工件Java 与 Scala 源码、模板以及需要编译的静态资源源码。按照 MVC 架构模式app下默认有三个包一一对应 MVC 的三个组件app/controllers—— 控制器层app/models—— 业务模型层app/views—— 视图模板层你完全可以添加自己的包例如app/services。并且需要注意在 Play 中controllers、models、views这些包名只是约定convention不是强制规定。如果愿意你可以给所有包加上公司前缀如com.yourcompany.controllers构建系统同样能正常工作——因为 Play 的路由与模板编译并不依赖固定的包名而是读取你配置的包声明。此外app下还有一个可选的app/assets目录用于存放需要预编译的静态资源例如 LESS CSS 源码和 CoffeeScript 源码。从源码层面看PlayLayoutPlugin.scala 明确将Assets / sourceDirectory指向app/assets、TestAssets / sourceDirectory指向test/assets这些资源会经由 sbt-web 管线编译后输出到target/web。public/目录无需编译的静态资源存放在public目录中的资源是静态资源由 Web 服务器直接对外提供不经过任何编译管线。该目录按惯例拆分为三个子目录分别存放图片、CSS 样式表和 JavaScript 文件。官方建议所有 Play 应用都按此方式组织静态资源以保持项目之间的一致性public/ ├── stylesheets/ → CSS 文件 ├── javascripts/ → JavaScript 文件 └── images/ → 图片文件在新建的应用中/public目录默认映射到/assetsURL 路径即浏览器访问/assets/...即可命中public下的文件。这个映射是可配置的你可以轻松更改它甚至配置多个目录来提供静态资源。从构建角度讲Assets / resourceDirectory被指向public见 PlayLayoutPlugin.scala也就是说public中的文件会作为 Web 资源参与打包与发布。conf/目录配置文件与非编译资源conf目录存放应用的配置文件它在构建时会被放入 classpath因此运行时可以通过application.conf被框架加载。其中有两个核心文件application.conf—— 应用的主配置文件采用 HOCON 格式详见 ConfigFile.md涵盖注释、键值分隔、include 合并、变量替换、时长/字节大小格式与系统属性覆盖等完整语法特性。Play 的运行端口、数据库连接、日志级别、HTTP 服务器参数等全部在此配置。routes—— 路由定义文件声明 HTTP 方法、URL 模式与对应控制器方法的映射。如果你需要添加应用特有的配置项直接在application.conf中增加条目即可如果某个第三方库需要独立的配置文件惯例也是放在conf目录下让它可以随 classpath 被加载。路由与模板编译两个目录被生成到哪conf/routes和app/views里的模板并不会直接运行而是在编译期被生成源码。路由编译器RoutesCompiler.scala会为每个 routes 文件生成三类产物见 RoutesCompiler.scala 中的RoutesCompilerTask定义正向路由器forwards router把请求 URL 分发到控制器反向路由器reverse router在代码中按方法调用生成 URLJS 反向路由器JS reverse router供前端 JavaScript 使用的 URL 生成器。这些生成源码被输出到target/scala-2.13/routes/同理app/views下的 Twirl 模板由模板引擎生成 Scala 源码输出到target/scala-2.13/twirl/。lib/目录非托管的 JAR 依赖lib目录是可选的用于存放非托管unmanaged库依赖——也就是你想脱离构建系统手工管理的 JAR 文件。只要把 JAR 丢进这个目录它们就会被自动加入应用的 classpath。当某些私有 JAR 无法发布到 Maven 仓库、又不适合作为源码引入时这是一个简单直接的兜底方案。build.sbt与project/目录构建定义build.sbt—— 位于项目根目录是项目的主要构建声明文件。这里声明项目名称、Scala 版本、依赖如guice、play-slick等、以及启用的插件如PlayScala、PlayJava。project/—— 存放 sbt 构建定义本身plugins.sbt声明本项目使用的 sbt 插件其中包含对 Play 插件本身的声明如addSbtPlugin(org.playframework % sbt-plugin % ...)build.properties指定用于构建本应用的 sbt 版本marker 文件例如sbt.version1.12.15对应 Versions.scala 中的SbtVersions.sbt1。target/目录构建生成的everythingtarget目录包含构建系统生成的一切产物。了解这里的结构对日常开发调试很有帮助classes/—— 所有编译后的 class 文件Java 与 Scala 源码的编译结果classes_managed/—— 仅由框架管理的 class 文件例如路由器与模板系统生成的类。在 IDE 中把它添加为外部 class 目录可以方便地调试或查看框架生成代码resource_managed/—— 生成的资源典型代表是 LESS CSS 与 CoffeeScript 的编译结果src_managed/—— 生成的源码例如模板系统生成的 Scala 源码web/—— 经过 sbt-web 处理的资源覆盖app/assets与public两处来源的处理结果。此外还有target/universal/应用打包产物与target/resolution-cache/依赖解析信息。Play 的默认布局把target固定在项目根目录这一点同样由 PlayLayoutPlugin.scala 控制。典型的.gitignore文件所有生成物目录都不应提交到版本控制。这是官方推荐的一个 Play 应用.gitignore模板logs project/project project/target target tmp dist .bsp .cache RUNNING_PID逐行说明logs、tmp—— 运行时产生的日志与临时文件project/project、project/target—— sbt 构建自身的生成物注意project/project是元构建的嵌套目录target—— 主项目的构建生成物对应上文全部classes/、src_managed/等内容dist—— 发行包目录.bsp—— Build Server Protocol 工作目录IDE 与构建服务器通信用.cache—— 各类缓存RUNNING_PID—— Play 在启动时写下的进程 ID 文件用于优雅停机。切换到默认的 sbt 布局Maven 风格除了 Play 标准布局你还可以选择使用sbt 与 Maven 的默认布局。做法是在build.sbt中禁用PlayLayoutPlugin并为 Twirl 模板设置显式的源码目录监控。完整的配置见 anatomy.sbtlazy val root: Project (project in file(.)) .enablePlugins(PlayScala) // Use sbt default layout .disablePlugins(PlayLayoutPlugin)禁用PlayLayoutPlugin之后Play 不再覆盖 sbt 的默认目录设置项目将呈现 Maven 风格的标准布局build.sbt → 应用构建脚本 src → 应用源码 └ main → 主源码集 └ java → Java 源码 └ controllers → Java 控制器 └ models → Java 业务层 └ scala → Scala 源码 └ controllers → Scala 控制器 └ models → Scala 业务层 └ resources → 配置文件及其他非编译资源位于 classpath └ application.conf → 主配置文件 └ routes → 路由定义 └ twirl └ views → 模板 └ assets → 需要编译的静态资源源码 └ css → 通常是 LESS CSS 源码 └ js → 通常是 CoffeeScript 源码 └ public → 公共静态资源 └ css → CSS 文件 └ js → JavaScript 文件 └ images → 图片文件 └ test → 单元测试或功能测试 └ java → Java 测试源码 └ scala → Scala 测试源码 └ resources → 测试资源 └ universal → 需要打进发行包的任意文件 project → sbt 配置文件 └ build.properties → sbt 项目标记 └ plugins.sbt → sbt 插件声明包括 Play 插件 lib → 非托管库依赖 logs → 日志目录 └ application.log → 默认日志文件 target → 构建生成物 └ scala-2.13 └ cache └ classes → 编译后的 class 文件 └ classes_managed → 受管理的 class 文件模板等 └ resource_managed → 受管理的资源LESS 等 └ src_managed → 生成的源码模板等两种布局的本质区别谁在搬动目录两种布局之间的差异完全由 PlayLayoutPlugin.scala 中的几个 sbt 键决定理解这些映射你就掌握了布局切换的全部秘密sbt 键Play 标准布局默认 sbt 布局禁用插件后Compile / sourceDirectoryappsrc/mainCompile / resourceDirectoryconfsrc/main/resourcesCompile / scalaSource/javaSourceappsrc/main/scala/src/main/javaTwirlKeys.compileTemplates / sourceDirectoriesapp含test需显式指向src/main/twirlAssets / sourceDirectoryapp/assetssrc/main/assetsAssets / resourceDirectorypublicsrc/main/publicUniversal / sourceDirectorydistsrc/universaltarget项目根目录下的targetsbt 默认位置特别要注意的一点在默认布局下必须为 Twirl 模板设置显式的源码目录监控即上面anatomy.sbt中enablePlugins(PlayScala)之后模板编译所需的目录配置因为PlayLayoutPlugin原本负责把模板源目录指向app禁用之后这一映射也随之消失。仓库中的 sbt 脚本测试 maven-layout-twirl-reload/build.sbt 正是对这一场景的回归验证——它在disablePlugins(PlayLayoutPlugin)的前提下启动应用并断言模板渲染结果确保 Maven 布局下 Twirl 模板的重载与渲染依然正确工作。小结从文件放哪到构建去哪把整篇文章浓缩成一张心智地图你写的代码app/控制器、模型、视图模板、assets预编译资源、test/测试你提供的配置conf/application.confroutes进入 classpath你直接发布的静态文件public/映射到/assetsURL可配置你手工管理的 JARlib/构建系统本身build.sbtproject/plugins.sbt声明 Play 插件、build.properties锁定 sbt 版本构建产物全部落入target/classes、routes/twirl 生成源码、web 资源、universal 打包并应通过.gitignore排除布局切换disablePlugins(PlayLayoutPlugin)即可切换到 sbt/Maven 默认布局代价是需要为 Twirl 模板显式配置源码目录。无论采用哪种布局Play 的构建管线路由编译、模板编译、资源处理、打包都只认 sbt 键指向的目录——布局插件只是帮你把这些键搬到约定位置。理解了这一点你就能在两种布局之间自由迁移也能在遇到文件放错了地方的构建错误时第一时间定位是哪个 sbt 键没有指向预期的目录。赞分享后端Web框架【免费下载链接】playframeworkThe Community Maintained High Velocity Web Framework For Java and Scala.项目地址https://gitcode.com/gh_mirrors/pl/playframework点击查看免费下载相关推荐Play Framework 的 sbt Settings 指南理解 build.sbt 与 PlayJava/PlayScala 默认设置Play Framework 的 sbt Settings 指南理解 build.sbt 与 PlayJava/PlayScala 默认设置 导读 本指南围绕后端Web框架iTerm2 WebExtensions Framework 扩展包结构完全指南从 manifest.json 到目录布局的实战解析iTerm2 WebExtensions Framework 扩展包结构完全指南从 manifest.json 到目录布局的实战解析 本篇指南聚焦 iTerm桌面应用AI 应用终极 SecureSocial 指南为 Play Framework 应用打造安全高效的认证系统终极 SecureSocial 指南为 Play Framework 应用打造安全高效的认证系统 SecureSocial 是一款强大的认证模块专为 Pla后端创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考