Apache Wicket 配置参数详解

Apache Wicket 的配置分散在三处：web.xml 的 context-param 与 filter 初始化参数、WicketApplication 的 init() 方法中的设置 API、以及承载 JVM 的启动参数。本文逐项解析这些参数，全部条目均来自真实服务器实测，给出修改位置、验证命令与实测回显。

一、环境信息

项目	环境 A（内嵌 Jetty 验证）	环境 B（独立 Tomcat 验证）
操作系统	Ubuntu 22.04.5 LTS	CentOS Linux 8（8.5.2111 源）
JDK	OpenJDK 17.0.20.1	OpenJDK 17.0.1+12-LTS
Maven	3.6.3	3.9.16
Apache Wicket	10.11.0（wicket-core）	10.11.0（wicket-core）
承载方式	Jetty 11.0.24（内嵌启动）	Tomcat 10.1.61（war 部署）
端口	8080	8080（上下文 /wicket-demo）

二、前置条件

已按 Maven 工程形态引入 wicket-core 10.11.0，工程能正常执行 mvn package。
读者了解 war 包结构与 web.xml 位置（src/main/webapp/WEB-INF/web.xml）。
验证命令使用 curl 与 jps（随 JDK 安装自带）。

三、参数查看与修改方式

3.1 查看当前运行模式

方式一：访问任一页面观察启动日志。内嵌启动时日志会出现：

********************************************************************
*** WARNING: Wicket is running in DEVELOPMENT mode.              ***
***                               ^^^^^^^^^^^                    ***
*** Do NOT deploy to your live server(s) without changing this.  ***
*** See Application#getConfigurationType() for more information. ***
********************************************************************

方式二：在页面上直接输出配置类型（本文示例应用首页有 mode 标签）：

add(new Label("mode", getApplication().getConfigurationType().name()));

3.2 web.xml 与过滤器初始化参数

Wicket 应用通过 WicketFilter 接入，web.xml 中可声明两类参数：filter 级的 init-param（applicationClassName、filterMappingUrlPattern 等）与 context 级的 context-param（configuration）。修改后需重新打包部署或重启进程。

3.3 Application.init() 设置 API

在 WicketApplication 的 init() 中调用各类设置器，编译后生效。可用 javap 直接查看某个设置类暴露的方法，例如：

javap -cp /tmp org.apache.wicket.settings.RequestCycleSettings | head -8

3.4 JVM 启动参数

内嵌 Jetty 场景通过 MAVEN_OPTS 传递，Tomcat 场景通过 bin/setenv.sh 的 CATALINA_OPTS 传递，修改后重启进程，用 jps -v 验证。

四、参数总览

参数	位置	默认值	说明
configuration	系统属性 wicket.configuration、filter init-param、context-param 三处	未设置时为 DEVELOPMENT	运行模式，决定调试行为
applicationClassName	filter init-param	无（必填）	WicketApplication 子类全限定名
filterMappingUrlPattern	filter init-param	web.xml 声明时自动识别	编程式注册过滤器时必填
defaultMarkupEncoding	MarkupSettings	未设置	HTML 模板读取编码，建议 UTF-8
stripWicketTags	MarkupSettings	false	是否剥离输出中的 wicket 标记
responseRequestEncoding	RequestCycleSettings	未设置	请求参数解码编码
renderStrategy	RequestCycleSettings	REDIRECT_TO_RENDER	页面渲染策略
propertiesLoaders	ResourceSettings	ISO 优先	properties 文件读取编码链
session-timeout	web.xml session-config	30（分钟，由运行环境决定）	会话超时
-Xms / -Xmx	JVM 启动参数	依环境	堆内存，建议 256 至 512MB

五、核心参数分类详解

5.1 运行模式 configuration

Wicket 10 判定运行模式的优先级为：系统属性 wicket.configuration，其次 filter 的 init-param，再次 context-param，均未设置时为 DEVELOPMENT。

两种模式对页面输出有可观测差异。DEVELOPMENT 模式实测输出（保留 wicket:id 与 wicket:panel 调试标记）：

<h1 wicket:id="greeting">Welcome, guest!</h1>
<p>Runtime mode: <span wicket:id="mode">DEVELOPMENT</span></p>
<ul wicket:id="feedback"><wicket:panel>

DEPLOYMENT 模式实测输出（同一应用，标记全部剥离，组件 id 混淆为 id4）：

<h1>Welcome, admin!</h1>
<p>Runtime mode: <span>DEPLOYMENT</span></p>
<ul>
</ul>
<form id="id4" method="post" action="./?5-1.-echoForm">

实测确认：DEPLOYMENT 模式下对返回 HTML 执行 grep -c wicket:id 结果为 0。生产环境必须在 web.xml 的 context-param 中固定 deployment。

5.2 WicketFilter 初始化参数

applicationClassName：指向 WebApplication 子类，缺失时应用无法启动。

filterMappingUrlPattern：在 web.xml 中声明过滤器时无需手工设置；用代码注册 WicketFilter 时必须显式补上，实测缺失时访问任意页面返回 HTTP 500：

<title>Error 500 java.lang.IllegalStateException: filter path was not configured</title>

补上后恢复正常：

FilterHolder wicketFilter = ctx.addFilter(WicketFilter.class, "/*",
        EnumSet.of(DispatcherType.REQUEST, DispatcherType.ERROR));
wicketFilter.setInitParameter("applicationClassName", "com.example.WicketApplication");
wicketFilter.setInitParameter("filterMappingUrlPattern", "/*");

注意：Jetty 的 addFilter 返回的是 org.eclipse.jetty.servlet.FilterHolder 类型，且 setInitParameter 返回布尔值，不能链式调用。

5.3 MarkupSettings

defaultMarkupEncoding：模板读取编码，设为 UTF-8 后响应头实测：

Content-Type: text/html;charset=utf-8

设置位置：

getMarkupSettings().setDefaultMarkupEncoding("UTF-8");

stripWicketTags：控制是否在输出中剥离 wicket:id 与 wicket:panel 等标记。默认关闭时 DEVELOPMENT 模式输出保留调试标记；开启后 DEVELOPMENT 模式输出与 DEPLOYMENT 一致，实测开启后首页正文：

<h1>Welcome, guest!</h1>
<p>Runtime mode: <span>DEVELOPMENT</span></p>

设置位置：

getMarkupSettings().setStripWicketTags(true);

5.4 RequestCycleSettings

responseRequestEncoding：请求参数解码编码，与表单中文参数相关：

getRequestCycleSettings().setResponseRequestEncoding("UTF-8");

renderStrategy：默认 REDIRECT_TO_RENDER，实测首次 GET 与表单提交后均返回 302，跟随重定向后得到 200 页面：

HOME_HTTP=302
code=200 final=http://127.0.0.1:8080/?1

如希望请求内直接渲染可改为 ONE_PASS_RENDER，调试脚本因此必须使用 curl 的 -L 参数。

gatherExtendedBrowserInfo：是否收集浏览器扩展信息（会触发额外的探测请求），确认不需要时保持关闭：

getRequestCycleSettings().setGatherExtendedBrowserInfo(false);

5.5 ResourceSettings 与本地化资源加载

Wicket 10 读取 properties 资源的装载器顺序（对应用内资源实测确认）：扩展名 properties 按 ISO-8859-1 读取，扩展名 utf8.properties 按 UTF-8 读取，扩展名 properties.xml 按 XML 读取。

实测结论：

中文写在普通 properties 文件中出现双重编码乱码，实测乱码回显：æ¬¢è¿åæ¥ï¼è®¿å®¢ï¼（应为欢迎回来，访客）。
将文件改名为 HomePage.utf8_zh_CN.properties 与 HomePage_zh_CN.utf8.properties 两种命名实测均无效，仍被 ISO 装载器抢先读取。
尝试在 init() 中替换装载器列表（清空后加入 UtfPropertiesFilePropertiesLoader）实测会破坏框架内部资源，渲染期报错：

java.util.MissingResourceException: Unable to find property: 'Form.CSS.hidden-fields' for component: echoForm

可靠做法是中文资源采用 unicode 转义（native2ascii 惯例），实测验证通过：

home.greeting=\u6b22\u8fce\u56de\u6765\uff0c{0}\uff01

curl -s -b /tmp/ckzh.txt -L -H "Accept-Language: zh-CN" http://127.0.0.1:8080/ | grep -o "<h1[^>]*>[^<]*"

实测回显：

<h1>欢迎回来，访客！

注意会话语言在会话创建时确定，切换语言需新建会话（更换 cookie 文件）再请求。

5.6 会话配置

自定义会话：继承 WebSession 并在 WicketApplication 中覆写 newSession（Wicket 10 的构造参数为 Request）：

@Override
public Session newSession(Request request, Response response) {
    return new DemoSession(request);
}

会话超时：由 Servlet 规范的 session-config 控制，实测将超时设为 1 分钟并重新部署后，登录成功显示 Welcome, admin，等待 70 秒后再次访问显示 Welcome, guest，会话已失效：

<session-config>
    <session-timeout>1</session-timeout>
</session-config>

路由挂载：mountPage 将页面类映射为友好地址，实测挂载 /login 后访问 http://127.0.0.1:8080/login 返回 200，未挂载的页面只能通过框架生成的链接地址访问：

mountPage("/login", LoginPage.class);

5.7 JVM 堆与编码参数

内嵌 Jetty 场景（MAVEN_OPTS）：

MAVEN_OPTS="-Xms256m -Xmx512m" mvn org.codehaus.mojo:exec-maven-plugin:3.5.0:java -Dexec.mainClass=com.example.Start

Tomcat 场景（bin/setenv.sh）：

CATALINA_OPTS="-Xms256m -Xmx512m -Dfile.encoding=UTF-8"

验证实测回显（Tomcat）：

jps -v | grep -v Jps

677 Bootstrap -Djava.util.logging.config.file=/opt/tomcat/conf/logging.properties -Djava.util.logging.manager=org.apache.juli.ClassLoaderLogManager -Djdk.tls.ephemeralDHKeySize=2048 -Djava.protocol.handler.pkgs=org.apache.catalina.webresources -Dsun.io.useCanonCaches=false -Dorg.apache.catalina.security.SecurityListener.UMASK=0027 --add-opens=java.base/java.lang=ALL-UNNAMED --add-opens=java.base/java.lang.reflect=ALL-UNNAMED --add-opens=java.base/java.io=ALL-UNNAMED --add-opens=java.base/java.util=ALL-UNNAMED --add-opens=java.base/java.util.concurrent=ALL-UNNAMED --add-opens=java.base/java.rmi/sun.rmi.transport=ALL-UNNAMED -Xms256m -Xmx512m -Dfile.encoding=UTF-8 -Dcatalina.base=/opt/tomcat -Dcatalina.home=/opt/tomcat -Djava.io.tmpdir=/opt/tomcat/temp

六、生产配置模板

适用场景：中小型组件化 Web 应用，单实例内存 512MB 以内，war 部署于 Tomcat 10.1。磁盘方面仅 war 包与日志占用（war 约 7MB，日志建议每日轮转并保留 30 天）。

web.xml 生产模板（关键节选）：

<web-app xmlns="https://jakarta.ee/xml/ns/jakartaee"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="https://jakarta.ee/xml/ns/jakartaee
                             https://jakarta.ee/xml/ns/jakartaee/web-app_5_0.xsd"
         version="5.0">
    <display-name>wicket-demo</display-name>
    <context-param>
        <param-name>configuration</param-name>
        <param-value>deployment</param-value>
    </context-param>
    <filter>
        <filter-name>wicket-demo</filter-name>
        <filter-class>org.apache.wicket.protocol.http.WicketFilter</filter-class>
        <init-param>
            <param-name>applicationClassName</param-name>
            <param-value>com.example.WicketApplication</param-value>
        </init-param>
    </filter>
    <filter-mapping>
        <filter-name>wicket-demo</filter-name>
        <url-pattern>/*</url-pattern>
        <dispatcher>REQUEST</dispatcher>
        <dispatcher>ERROR</dispatcher>
    </filter-mapping>
    <session-config>
        <session-timeout>30</session-timeout>
    </session-config>
</web-app>

init() 生产模板：

@Override
protected void init() {
    super.init();
    getMarkupSettings().setDefaultMarkupEncoding("UTF-8");
    getMarkupSettings().setStripWicketTags(true);
    getRequestCycleSettings().setResponseRequestEncoding("UTF-8");
    mountPage("/login", LoginPage.class);
}

启动参数模板（bin/setenv.sh）：

CATALINA_OPTS="-Xms256m -Xmx512m -Dfile.encoding=UTF-8"

修改位置汇总：web.xml 位于 src/main/webapp/WEB-INF（随包部署），init() 位于 WicketApplication 源码，setenv.sh 位于 Tomcat 的 bin 目录。改后用 jps -v 与页面 mode 标签双重验证。

七、常见问题

Q1：生产环境启动日志仍提示 DEVELOPMENT mode？

configuration 参数在系统属性、filter init-param、context-param 三处重复设置时，优先级高的生效。排查系统属性 wicket.configuration 与过滤器 init-param，最终以 context-param 固定 deployment。

Q2：页面 HTML 中残留 wicket:id 影响前端核对？

开发模式默认保留调试标记，便于对照模板。如需干净输出，开启 stripWicketTags 或切换 deployment 模式，两种方式实测均能剥离全部标记。

Q3：中文资源文件已经保存为 UTF-8，页面仍乱码？

Wicket 默认按 ISO-8859-1 读取 properties 文件，且实测 utf8.properties 命名在 zh_CN 语言变体下不生效。将中文内容改为 unicode 转义写法即可。

Q4：替换 properties 装载器为 UTF-8 后大面积报 MissingResourceException？

框架内部资源（如 Form.CSS.hidden-fields）也依赖默认装载链，实测清空装载器会连带破坏框架资源。不建议替换装载器，统一使用转义写法。

Q5：会话频繁失效？

检查 web.xml 的 session-timeout 取值（单位为分钟），以及运行环境层面的会话保持配置；curl 验证时确保 -c 与 -b 使用同一 cookie 文件。

八、参考链接

Apache Wicket 官网：https://wicket.apache.org
Wicket Wiki 与迁移说明：https://cwiki.apache.org/confluence/display/WICKET/Index
Wicket 10 JavaDoc：https://ci.apache.org/projects/wicket/apidocs/10.x/
Maven Central 上的 wicket-core：https://repo1.maven.org/maven2/org/apache/wicket/wicket-core/
Jakarta Servlet 5.0 规范：https://jakarta.ee/specifications/servlet/5.0/