Tapestry 框架怎么从零配置？从环境到验证的完整步骤

想用 Java 写一个组件化的 Web 页面，又不想在 JSP 和一堆标签库里纠缠，Apache Tapestry 是条干净的路线。一句话结论：从零配置 Tapestry 只要四步——先在 Maven 或 Gradle 里引入 tapestry-core 依赖，再写一对「Page 类 + 同名 .tml 模板」的页面，接着在 web.xml 里映射 TapestryFilter 作为统一请求入口，最后启动容器访问页面验证渲染。作为一款 Java Web 框架，它的核心是把每个页面拆成 Java 组件类和 HTML 模板两部分，模板里用 t: 命名空间绑定组件。下面先用一张表看清配置链路，再逐个给出可复现的代码和常见失败点。

先看结论

记住一条铁律：页面永远是 Page 类 + 同名 .tml 成对出现；模板文件名必须和类同名，否则 Tapestry 找不到模板会直接 500，这是新手配置里最高的失败率来源。

一、Tapestry 的组件化模型与配置边界

要完成 Tapestry 配置，先得理解它和传统 JSP/Servlet 不一样的组件化思路。Apache Tapestry 框架把「页面」拆成两个平行文件：一个普通的 Java 类（组件类）负责逻辑与数据，一个后缀为 .tml 的 HTML 文件（页面模板）负责渲染结构。模板里通过 t: 前缀的命名空间把 HTML 元素和 Java 类里的属性、方法、组件绑定起来，浏览器请求的 URL 最终由框架根据类名自动路由到对应页面。Tapestry 教程 里把组件生命周期、模板表达式和参数传递讲得系统，建议先过一遍再动手，免得把后端 MVC 的习惯硬套上来。

这种模型带来两个关键边界。第一条边界是「类与模板必须同名成对」：比如页面类叫 Index.java，放在 services 包下，框架会按规则去找 Index.tml；两者缺一或名字对不上，页面就渲染不出来。第二条边界是「约定优于配置」：Tapestry 大量依赖命名约定（类放 pages 包、组件放 components 包、资源放 webapp 下），你少写很多 XML 映射，但一旦违反约定就会找不到文件。配置页面之前，先确认 JDK 版本与 Tapestry 大版本匹配——Tapestry 5.8 需要 Java 8 及以上，老项目用 5.4 则要对应更低 JDK。理解组件类与页面模板的关系，是后面每一步配置不跑偏的前提。

除了页面，Tapestry 还把按钮、表单、循环都做成可复用组件，组件本身也是「类 + .tml」成对。也就是说，整个应用是一场「组件树」的嵌套，根组件就是页面。下面先放一张决策图，帮你对着卡点直接挑该配哪一步。

二、引入依赖与项目骨架

Tapestry 配置 的第一步是把框架依赖引进项目，官方推荐用 Maven 或 Gradle 管理。核心依赖只有一个 groupId 为 org.apache.tapestry 的 tapestry-core，它会顺带拉入 tapestry-ioc、tapestry5-annotations 等必需模块，你不必手动逐个加。Java 教程 里关于 Maven 依赖与构建工具的基础，能帮你确认本地 JDK、仓库镜像和打包方式都没问题，避免后面编译期就卡住。

<!-- Maven：pom.xml 中加入 -->
<dependency>
  <groupId>org.apache.tapestry</groupId>
  <artifactId>tapestry-core</artifactId>
  <version>5.8.0</version>
</dependency>

// Gradle：build.gradle 中加入
dependencies {
    implementation 'org.apache.tapestry:tapestry-core:5.8.0'
}

运行 mvn compile 或 gradle build 时，你预期看到依赖被正常下载、没有红线；失败分支最常见的是版本冲突——比如项目里同时引入了不相容的 Jetty、Servlet API 版本，会报 NoClassDefFoundError 或 MethodNotFound。修复办法是锁定 tapestry-core 单一版本，并用 mvn dependency:tree 检查传递依赖里有没有重复的老包。配置 Servlet 容器时，Tapestry 5.8 已内置对 Servlet 3.0+ 的支持，开发阶段用 Jetty 或 Tomcat 都可以，容器版本别太老。另一个坑是仓库镜像没配好导致依赖拉不下来，检查 settings.xml 或 gradle 的仓库地址是否可达即可。骨架就绪后，下一步才是写真正的页面。

三、写 Page 类与同名 .tml 模板

Tapestry 配置 最关键的一步是写页面，而页面永远是「组件类 + 同名 .tml」成对出现。组件类是一个普通 POJO，字段用 @Property 或 public getter 暴露给模板，方法可以是页面事件（如 onActivate、onSuccess）。模板是标准 HTML，加上 xmlns:t="http://tapestry.apache.org/schema/tapestry_5_4.xsd" 命名空间后用 t: 标签绑定。Spring 教程 虽讲 Spring，但其中「控制反转、按约定注入」的思想和 Tapestry 的 IOC 容器同源，对照看能更快理解为什么组件靠约定自动装配。

// pages/Index.java
package pages;
import org.apache.tapestry5.annotations.Property;

public class Index {
    @Property
    private String message = "Hello Tapestry";

    void onActivate() {
        // 页面激活时执行
    }
}

<!-- Index.tml，放在 webapp 或对应资源目录，与类同名 -->
<html xmlns:t="http://tapestry.apache.org/schema/tapestry_5_4.xsd">
  <body>
    <h1>${message}</h1>
    <t:loop source="1..3">...</t:loop>
  </body>
</html>

运行后，访问 /index 路径，框架找到 Index 类与 Index.tml 渲染出页面；你预期在浏览器看到 Hello Tapestry。失败分支集中在三处。第一处是模板命名空间没声明，t: 标签被当成普通文本原样输出，修复就是补上 xmlns:t 那一行。第二处是类与模板不在框架约定的查找路径，找不到时直接 500，检查包名（pages）和文件位置。第三处是表达式写错，比如 ${msg} 但类里字段叫 message，会报未知属性异常。HTML 教程 里关于 HTML 结构与命名空间的章节，能帮你把 .tml 这种「带命名空间的 HTML」和普通网页的差别看明白，避免把模板当纯静态页去写。页面模板与组件类的绑定是 Tapestry 的灵魂，熟了之后写表单、循环都比 JSP 干净。

四、web.xml 映射入口与失败排查

Tapestry 配置 的最后一步是把所有请求交给框架处理，做法是在 web.xml 里注册 TapestryFilter，并把过滤路径映射到 /*（或你想要的目录）。过滤器是统一入口，它会根据 URL 找到对应页面类、渲染对应 .tml，省去你手写每个 Servlet 映射。这是和 Spring 这类框架不一样的地方：Tapestry 自己就是全栈 Web 框架，不需要额外配 DispatcherServlet。CSS 教程 偏样式，但页面模板里照样能引 CSS，理解静态资源路径有助于后面把样式接进来。

<!-- web.xml -->
<filter>
  <filter-name>app</filter-name>
  <filter-class>org.apache.tapestry5.TapestryFilter</filter-class>
</filter>
<filter-mapping>
  <filter-name>app</filter-name>
  <url-pattern>/*</url-pattern>
</filter-mapping>

运行容器后访问首页，你预期看到渲染好的页面；失败分支有几类。第一类是 url-pattern 写错，比如只映射到 /app/ 却访问根路径，会 404，把模式改成 / 即可。第二类是 TapestryFilter 类名或包写错（老版本是 tapestry5 包），会报 ClassNotFoundException，按你用的版本核对 filter-class。第三类是页面类没放在约定的 pages 包，框架扫描不到，报页面未找到。安全方面，生产环境建议关闭 Tapestry 的开发模式（tapestry.production-mode=true），否则异常堆栈和实时类重载会暴露给外部、也有性能损耗。版本上，5.8 与 5.4 的命名空间 schema 版本号不同，模板里 xmlns:t 的 URL 要跟着改，否则校验失败。命令层面，启动后用 curl 打一下首页看返回状态码，配合容器日志定位是依赖缺还是映射错。

本文示例基于 Tapestry 5.8 与官方文档说明（官方文档）。

总结

Tapestry 配置 走的是「约定优于配置」的组件化路线，从零到能访问页面只要四步：引 tapestry-core 依赖搭骨架，写一对同名的 Page 类与 .tml 页面模板，在 web.xml 里用 TapestryFilter 接管 /* 请求，最后启动容器访问页面验证渲染。作为 Java Web 框架，它把页面拆成组件类和页面模板两层，靠命名约定自动装配，比 JSP 标签库更干净。一句话记忆：页面 = Page 类 + 同名 .tml，入口 = 一个 TapestryFilter。踩坑几乎都集中在类模板不同名、命名空间没声明、过滤路径写错这三处，按上面清单逐一验证就能跑通。

延伸学习

• 课程：JAVA 架构师从零开始学全套课程
• 相关笔记：语言对比笔记
• 教程：JavaScript 教程

常见问题

Q：Tapestry 的 Page 类和 .tml 模板为什么必须同名？

因为框架按命名约定自动查找：请求 /index 时，它去约定的 pages 包找 Index 类，再找同名的 Index.tml 渲染。不同名就找不到对应文件，直接报页面不存在的 500。这是 Tapestry「约定优于配置」的核心，少写映射但要求你遵守命名。

Q：web.xml 里过滤路径写成 /app/* 会有什么后果？

只有以 /app/ 开头的请求才会进 TapestryFilter，你访问根路径 / 或 /index 会被容器当成静态资源，结果 404。开发期一般直接配 /* 接管全部请求，等需要和其它 Servlet 共存时再细化路径。

Q：tapestry-core 依赖下载失败或版本冲突怎么排查？

先用 mvn dependency:tree 看传递依赖里有没有重复的老版本 tapestry 或冲突的 Servlet API，锁定单一 tapestry-core 版本即可。若是仓库拉不下来，检查 Maven/Gradle 的镜像地址是否可达、网络是否受限，必要时切换国内镜像源。