Skip to content

SSR-JSP-JSTL ​

[TOC]

概述 ​

JSTL 定位 ​

JSTL(JSP Standard Tag Library,JSP 标准标签库)是由 JCP(Java Community Process)制定的一套标准自定义标签规范,核心目标是消除 JSP 页面中的 Java 脚本代码(Scriptlet,如 <% ... %>),使视图层回归纯粹的标记语言结构。

在经典的 Java Web MVC 分层架构中,Servlet 负责接收请求并调度业务逻辑,JSP 负责将数据渲染为 HTML 响应。单纯使用 EL(Expression Language)表达式只能完成作用域数据读取与简单运算,无法表达条件分支、集合迭代、本地化格式化等控制流逻辑。JSTL 补齐了视图层的流程控制与数据处理能力,二者通常按以下分工协作:

  1. Servlet 准备业务数据并将其写入 request、session 或 application 等作用域。

  2. JSTL 以标准 XML 标签形式承担流程控制(判断、循环)、文本转义输出、国际化与格式化以及 URL 重写等结构化操作。

  3. EL 嵌入在 JSTL 标签属性与模板文本中,负责从作用域提取对象属性并计算动态条件。

image-20261119114418935

通过将流程控制收敛到标准标签库,JSP 页面不仅更易于前端与后端协作维护,还能借助标签内部实现的默认转义、连接池兼容与作用域隔离规避大量手工编写 Java 脚本带来的安全与可维护性隐患。

版本演进 ​

JSTL 规范随着 Servlet 与 JSP 容器的演进而经历了从 Java EE 到 Jakarta EE 的命名空间迁移。不同版本的运行时容器对依赖坐标、包名及标签库 URI 存在明确边界,配置错误会导致页面解析失败或运行期抛出 NoClassDefFoundError。

javax.servlet.jsp.jstl ​

涵盖 JSTL 1.0、1.1 与 1.2 版本,运行于遵循 Java EE 规范的 Servlet 容器(如 Tomcat 7、Tomcat 8、Tomcat 9)。

  • JSTL 1.0:诞生于 JSP 1.2 时代,当时 JSP 容器尚未原生支持 EL,因此提供了独立的 EL 计算实现(RT 版与 EL 版标签库分离)。
  • JSTL 1.1 与 1.2:适配 JSP 2.0 及以上规范,EL 正式纳入 JSP 与统一表达式语言(Unified EL)规范,JSTL 将表达式求值交由容器处理,标签库 URI 统一升级为 [http://java.sun.com/jsp/jstl/](http://java.sun.com/jsp/jstl/)* 前缀。JSTL 1.2 是传统 Java EE 体系中最稳定、应用最广泛的版本。

jakarta.servlet.jsp.jstl ​

涵盖 Jakarta Standard Tag Library 2.0 与 3.0 版本,运行于遵循 Jakarta EE 9 及以上规范的 Servlet 容器(如 Tomcat 10、Tomcat 10.1、Tomcat 11)。

  • 包名迁移:所有规范接口与实现类由 javax.servlet.jsp.jstl.* 整体迁移至 jakarta.servlet.jsp.jstl.*,与旧版 JSTL 1.2 二进制不兼容。
  • URI 演进:Jakarta JSTL 3.0 推荐使用简洁的 URN 形式命名空间(如 jakarta.tags.core),同时部分实现保留了对旧版 [http://java.sun.com/jsp/jstl/](http://java.sun.com/jsp/jstl/)* URI 的兼容映射。
版本阶段适用容器示例规范包前缀Core 标签库 URI
JSTL 1.0Tomcat 4 / JSP 1.2javax.servlet.jsp.jstl[http://java.sun.com/jstl/core](http://java.sun.com/jstl/core)
JSTL 1.1 / 1.2Tomcat 7 ~ 9 / JSP 2.0 ~ 2.3javax.servlet.jsp.jstl[http://java.sun.com/jsp/jstl/core](http://java.sun.com/jsp/jstl/core)
Jakarta JSTL 2.0Tomcat 10.0 / Jakarta EE 9jakarta.servlet.jsp.jstl[http://java.sun.com/jsp/jstl/core](http://java.sun.com/jsp/jstl/core)
Jakarta JSTL 3.0Tomcat 10.1+ / Jakarta EE 10jakarta.servlet.jsp.jstljakarta.tags.core

标签库组成 ​

JSTL 规范按职责将全部标准标签划分为五个独立的功能库。每个标签库拥有专属的 URI、约定前缀与对应的 TLD(Tag Library Descriptor)描述文件,按需引入即可生效。

Core ​

核心标签库(约定前缀 c),是日常开发中使用频率最高的模块。涵盖作用域变量读写、XSS 安全输出、异常捕获、单分支与多分支条件判断、集合与分隔符迭代以及 URL 参数编码与页面重定向。

Formatting ​

国际化与格式化标签库(约定前缀 fmt),用于处理多语言资源与本地化显示格式。支持区域设置(Locale)切换、时区管理、资源包(ResourceBundle)消息读取,以及数值、货币、百分比与日期时间的格式化和反向解析。

Functions ​

EL 函数库(约定前缀 fn),并非传统意义上的 JSP 自定义标签,而是一组可直接嵌入 EL 表达式中调用的静态字符串与集合工具函数,常用于判断包含关系、截取子串、大小写转换、XML 转义以及获取集合或字符串长度。

XML ​

XML 处理标签库(约定前缀 x),基于 XPath 表达式提供声明式的 XML 文档解析、节点筛选、条件遍历以及 XSLT 样式表转换能力。运行期依赖额外的 Xalan 等 XSLT/XPath 实现库,在以 JSON 为主流数据交换格式的现代项目中已较少使用。

SQL ​

数据库访问标签库(约定前缀 sql),允许直接在 JSP 页面中配置数据源、执行查询与更新语句并控制事务边界。由于在视图层直接嵌入数据库访问违背 MVC 分层原则,该库仅适用于小型原型演示或快速报表验证,生产环境通常严禁使用。

标签库约定前缀JSTL 1.2 URIJakarta JSTL 3.0 URI核心用途
Corec[http://java.sun.com/jsp/jstl/core](http://java.sun.com/jsp/jstl/core)jakarta.tags.core变量操作、流程控制、迭代与 URL 管理
Formattingfmt[http://java.sun.com/jsp/jstl/fmt](http://java.sun.com/jsp/jstl/fmt)jakarta.tags.fmt国际化消息、数值与日期格式化
Functionsfn[http://java.sun.com/jsp/jstl/functions](http://java.sun.com/jsp/jstl/functions)jakarta.tags.functionsEL 内联字符串与集合处理函数
XMLx[http://java.sun.com/jsp/jstl/xml](http://java.sun.com/jsp/jstl/xml)jakarta.tags.xmlXML 文档解析、XPath 遍历与 XSLT 转换
SQLsql[http://java.sun.com/jsp/jstl/sql](http://java.sun.com/jsp/jstl/sql)jakarta.tags.sql数据源声明、SQL 读写与事务控制

依赖配置 ​

Tomcat 等轻量级 Servlet 容器默认仅内置 Servlet、JSP 与 EL 规范实现,不包含 JSTL 的 API 与运行时实现。启用 JSTL 前必须将与容器版本匹配的 JAR 包引入项目的运行时类路径。

Maven ​

在 Tomcat 9 及以下(Java EE / javax 体系)项目中,推荐引入 Apache Standard Taglib 提供的规范包与实现包:

xml
<!-- 1. JSTL 1.2 API 规范包(Tomcat 9 及以下使用 javax 命名空间) -->
<!-- 仅声明接口与抽象基类,需配合实现包共同使用 -->
<dependency>
    <groupId>org.apache.taglibs</groupId>
    <artifactId>taglibs-standard-spec</artifactId>
    <version>1.2.5</version>
</dependency>

<!-- 2. Apache Standard Taglib 运行时实现包 -->
<!-- 提供标签处理器实现类与内置 TLD 描述文件 -->
<dependency>
    <groupId>org.apache.taglibs</groupId>
    <artifactId>taglibs-standard-impl</artifactId>
    <version>1.2.5</version>
</dependency>

在 Tomcat 10.1 及以上(Jakarta EE 10 / jakarta 体系)项目中,必须切换为 Jakarta 坐标,否则容器无法加载 jakarta.servlet.jsp.tagext 对应的标签处理器:

xml
<!-- 1. Jakarta JSTL 3.0 规范 API(Tomcat 10 及以上使用 jakarta 命名空间) -->
<dependency>
    <groupId>jakarta.servlet.jsp.jstl</groupId>
    <artifactId>jakarta.servlet.jsp.jstl-api</artifactId>
    <version>3.0.0</version>
</dependency>

<!-- 2. GlassFish 提供的 Jakarta JSTL 运行时实现包 -->
<dependency>
    <groupId>org.glassfish.web</groupId>
    <artifactId>jakarta.servlet.jsp.jstl</artifactId>
    <version>3.0.1</version>
</dependency>

WEB-INF/lib ​

对于未使用 Maven 或 Gradle 构建的传统动态 Web 工程,需将上述对应的规范包与实现包 JAR 文件手动复制到 WEB-INF/lib 目录中,并确保 IDE 已将其加入部署构建产物的输出目录(Artifact)。

注意:不要在 WEB-INF/lib 中同时混放 javax.servlet:jstl(如 jstl-1.2.jar)与 taglibs-standard-spec / taglibs-standard-impl,也不要混放 javax 与 jakarta 两套实现,以免 TLD 扫描冲突或类加载异常。

taglib 指令 ​

依赖引入完成后,JSP 容器会在启动或首次编译时自动扫描 JAR 包中 META-INF/*.tld 描述文件,建立 URI 与标签处理器类之间的映射关系。开发时只需在 JSP 文件顶部通过 <%@ taglib %> 指令声明要使用的标签库 uri 与自定义前缀 prefix:

jsp
<%-- 1. JSTL 1.2(Tomcat 9 及以下)引入 Core 与 Formatting 标签库 --%>
<%@ taglib prefix="c" uri="http://java.sun.com/jsp/jstl/core" %>
<%@ taglib prefix="fmt" uri="http://java.sun.com/jsp/jstl/fmt" %>

<%-- 2. Jakarta JSTL 3.0(Tomcat 10 及以上)推荐使用新版 URN 形式 URI --%>
<%@ taglib prefix="c" uri="jakarta.tags.core" %>
<%@ taglib prefix="fmt" uri="jakarta.tags.fmt" %>

指令中的 uri 是用于定位 TLD 文件的逻辑唯一标识,并非容器在运行期访问的外部网络地址,因此离线环境下同样可以正常解析。prefix 虽然语法上允许自定义,但工程实践中应严格遵守 c、fmt、fn、x、sql 这一行业通用约定。

示例: JSTL 页面渲染 ​

下面以商品列表展示为例,演示 Servlet、EL 与 JSTL Core 标签库的标准协作方式。首先由 Servlet 准备集合数据并存入 request 作用域后转发至视图:

java
package com.example.web;

import javax.servlet.ServletException;
import javax.servlet.annotation.WebServlet;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import java.io.IOException;
import java.util.Arrays;
import java.util.List;

// 1. 定义控制器 Servlet,负责准备业务数据并转发至 JSP 视图
@WebServlet("/products")
public class ProductListServlet extends HttpServlet {

  // 2. 处理 GET 请求,组装商品名称集合
  @Override
  protected void doGet(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException {
    List<String> productList = Arrays.asList("机械键盘", "无线鼠标", "显示器支架");

    // 3. 将数据存入 request 作用域,供 JSTL 与 EL 读取
    req.setAttribute("products", productList);

    // 4. 请求转发到 JSP 页面完成视图渲染
    req.getRequestDispatcher("/WEB-INF/views/products.jsp").forward(req, resp);
  }
}

随后在 products.jsp 中引入 Core 标签库,结合 EL 完成空集合判断、循环迭代以及防 XSS 的安全输出,整个页面无需编写任何 Java 脚本代码:

jsp
<%-- 1. 声明页面编码并引入 JSTL Core 标签库 --%>
<%@ page contentType="text/html;charset=UTF-8" language="java" %>
<%@ taglib prefix="c" uri="http://java.sun.com/jsp/jstl/core" %>

<html>
<body>
    <%-- 2. 使用 JSTL 条件分支替代 Java 的 if/else 脚本 --%>
    <c:choose>
        <c:when test="${empty products}">
            <p>暂无商品数据</p>
        </c:when>

        <%-- 3. 使用 JSTL 迭代标签遍历集合并配合 EL 取值 --%>
        <c:otherwise>
            <ul>
                <c:forEach var="item" items="${products}" varStatus="st">
                    <%-- 4. 通过 c:out 安全输出内容,默认开启 XML 特殊字符转义 --%>
                    <li>${st.count}. <c:out value="${item}" /></li>
                </c:forEach>
            </ul>
        </c:otherwise>
    </c:choose>
</body>
</html>

请求到达 /products 时,JSP 引擎在首次访问阶段会将 <c:choose>、<c:forEach> 与 <c:out> 转译为标准标签处理器对象的生命周期方法调用,最终生成纯净的 HTML 列表返回给浏览器。

Core 标签库 ​

Core 标签库是 JSTL 中最核心、使用最频繁的标准模块,约定前缀为 c,在 JSTL 1.2 中对应 URI [http://java.sun.com/jsp/jstl/core](http://java.sun.com/jsp/jstl/core)(Jakarta JSTL 3.0 为 jakarta.tags.core)。它将视图层常见的变量读写、XSS 安全输出、条件分支、集合迭代与 URL 处理封装为 14 个标准标签,彻底替代 JSP 中的 Java 脚本控制逻辑。

image-20261119114440334

通用标签 ​

通用标签负责作用域属性的读取、赋值、移除以及页面级异常捕获,覆盖视图渲染中最基础的数据操作。

c:out ​

<c:out> 用于计算表达式结果并将其写入当前 JspWriter 输出流。相比直接在页面中书写 ${expr},<c:out> 具备两项关键工程价值:

  • 默认 XML 转义:escapeXml 属性默认为 true,输出前会自动将 <、>、&、'、" 五个特殊字符转换为对应的字符实体(&lt;、&gt;、&amp;、&#039;、&#034;),从源头阻断用户输入引发的反射型或存储型 XSS 攻击。
  • 空值回退:当 value 计算结果为 null 时,自动输出 default 属性值或标签体内的备选文本。
jsp
<%-- 1. 默认开启 XML 转义,防止评论中的脚本被浏览器执行 --%>
<p><c:out value="${comment.content}" default="暂无评论" /></p>

<%-- 2. 使用标签体作为空值回退默认值 --%>
<p><c:out value="${user.nickname}">匿名用户</c:out></p>

<%-- 3. 显式关闭转义以渲染受信任的富文本 HTML(谨慎使用) --%>
<div><c:out value="${article.trustedHtml}" escapeXml="false" /></div>

安全约束:仅在内容已由服务端富文本白名单过滤组件完成净化时,才允许将 escapeXml 设为 false。对于普通用户输入内容,应始终保持默认值或优先使用 <c:out> 替代裸写的 EL 表达式。

c:set ​

<c:set> 承担两类职责:向指定 Web 作用域写入变量,或者修改作用域中已有 JavaBean 与 Map 对象的属性。

  • 作用域变量模式:使用 var 指定属性名、value(或标签体)指定值、scope 指定作用域(默认为 page)。若 value 计算结果为 null,标签会从指定作用域移除该属性;若同时省略 scope,则会清除四个作用域中所有同名属性。
  • 目标对象属性模式:使用 target 指定目标对象(必须通过 EL 传入非 null 的 JavaBean 或 Map 实例,不能传字符串字面量)、property 指定属性名或键名。对于 JavaBean 会调用对应的 Setter 方法;对于 Map,当 value 为 null 时会移除该键,否则写入键值对。
jsp
<%-- 1. 向 session 作用域写入字符串变量 --%>
<c:set var="theme" value="light" scope="session" />

<%-- 2. 通过标签体设置复杂拼接值,默认存入 page 作用域 --%>
<c:set var="welcomeMsg">
    欢迎回来,${sessionScope.loginUser.name}
</c:set>

<%-- 3. 修改作用域中已有 JavaBean 或 Map 的属性 --%>
<c:set target="${order}" property="status" value="PAID" />

c:remove ​

<c:remove> 用于从 Web 作用域中删除指定名称的属性,常用于清理一次性提示消息或临时会话状态。

  • 指定 scope 时,仅删除对应作用域中的属性,其他作用域中的同名属性不受影响。
  • 省略 scope 时,标签底层会调用 pageContext.removeAttribute(var),依次清除 page、request、session、application 四个作用域中的全部同名属性。
jsp
<%-- 1. 仅移除 session 作用域中的临时验证码 --%>
<c:remove var="captchaCode" scope="session" />

<%-- 2. 省略 scope 时,依次清除四个作用域中的同名属性 --%>
<c:remove var="flashMessage" />

c:catch ​

<c:catch> 用于包裹可能抛出异常的标签片段,拦截标签体执行期间产生的 Throwable 对象,避免异常直接穿透到 JSP 错误页导致整页渲染中断。

如果指定了 var 属性,捕获到的异常对象会被存入 page 作用域(不存在 scope 属性);若标签体正常执行完毕,容器会将 page 作用域中同名的 var 属性清除。

jsp
<%-- 1. 捕获外部片段加载失败时抛出的异常并存入 page 作用域 --%>
<c:catch var="loadError">
    <c:import url="http://notice.example.internal/banner.html" />
</c:catch>

<%-- 2. 检测到异常对象时展示降级提示内容 --%>
<c:if test="${not empty loadError}">
    <p>公告暂不可用:<c:out value="${loadError.message}" /></p>
</c:if>

设计边界:<c:catch> 适用于非关键视图区块(如侧边栏推荐、外部静态公告)的容错降级,不应替代控制器层和业务层的统一异常处理体系。

条件控制 ​

Core 标签库提供单分支与多分支两套条件标签。其条件标签处理器通常继承自标准抽象基类 ConditionalTagSupport,由基类统一负责条件求值、作用域结果导出与标签体放行判定。

c:if ​

<c:if> 用于单分支条件判断,核心属性为 test,接收布尔类型的 EL 表达式。当 test 为 true 时执行标签体,否则跳过。

<c:if> 本身没有配套的 else 标签。在需要复用复杂条件判断结果或编写互补分支时,可以通过 var 与 scope 将布尔求值结果缓存到指定作用域中,避免重复计算同一表达式。

jsp
<%-- 1. 校验管理员权限并将布尔结果缓存在 request 作用域 --%>
<c:if test="${sessionScope.user.role == 'ADMIN'}" var="isAdmin" scope="request">
    <a href="/admin/dashboard">进入管理后台</a>
</c:if>

<%-- 2. 复用已缓存的布尔结果实现反向分支判断 --%>
<c:if test="${not isAdmin}">
    <span>当前为普通访客视角</span>
</c:if>

c:choose ​

<c:choose> 与子标签 <c:when>、<c:otherwise> 组合构成多分支互斥判断结构,语义等价于 Java 中的 if / else if / else。运行时按照书写顺序自上而下逐一计算 <c:when> 的 test 条件,一旦命中首个为 true 的分支即执行其标签体并短路跳过后续所有分支;若全部 <c:when> 均不满足,则执行 <c:otherwise>。

使用 <c:choose> 必须遵守以下结构约束:

  1. <c:choose> 内部必须至少包含一个 <c:when> 子标签。

  2. <c:otherwise> 最多只能出现一次,且必须位于所有 <c:when> 之后。

  3. <c:choose> 与子标签之间只能出现空白字符或 JSP 注释,不能夹杂普通 HTML 文本或其他标签。

jsp
<%-- 1. 多分支条件匹配,命中首个为真的 c:when 后立即结束 --%>
<c:choose>
    <c:when test="${order.status == 'PENDING'}">
        <%-- 2. 待支付分支 --%>
        <span class="tag-warn">待支付</span>
    </c:when>

    <c:when test="${order.status == 'SHIPPED'}">
        <%-- 3. 已发货分支 --%>
        <span class="tag-info">配送中</span>
    </c:when>

    <c:otherwise>
        <%-- 4. 默认兜底分支,必须位于最后 --%>
        <span class="tag-default">已完成或已取消</span>
    </c:otherwise>
</c:choose>

循环迭代 ​

Core 标签库将循环能力抽象为标准迭代协议 LoopTag 与模板基类 LoopTagSupport,同时通过 LoopTagStatus 暴露当前轮次的索引、计数与首尾状态,覆盖集合遍历与字符串分词两类高频场景。

c:forEach ​

<c:forEach> 是最核心的循环标签,支持集合遍历与计数循环两种运行模式:

  • 集合遍历模式:通过 items 传入待遍历目标,原生支持 Collection、数组(含基本类型数组)、Map(元素类型为 Map.Entry,可通过 .key 与 .value 访问)、Iterator、Enumeration 以及英文逗号分隔的字符串。此时 begin 与 end 表示从 0 开始的包含式索引范围。
  • 计数循环模式:省略 items 属性,同时提供 begin 与 end(以及可选的 step,默认为 1 且必须大于等于 1),直接按步长递增生成整数序列,常用于分页页码渲染。

每次迭代开始前,容器会将当前元素绑定到 var 变量,并将封装迭代上下文的 LoopTagStatus 对象绑定到 varStatus 变量。这两个变量均固定存放在 page 作用域中,循环结束后自动销毁或恢复原值,不会污染外部作用域。

varStatus 属性含义说明
current当前正在迭代的元素对象
index当前迭代基于 0 的索引(计数模式下等于当前计数值)
count当前是第几次执行循环体,始终从 1 开始递增
first布尔值,标识当前是否为第一轮迭代
last布尔值,标识当前是否为最后一轮迭代
begin / end / step对应标签上配置的起止边界与步长参数

image-20261119114550770

jsp
<%-- 1. 遍历 List 集合,通过 varStatus 获取序号与首尾状态 --%>
<c:forEach var="book" items="${bookList}" varStatus="st">
    <tr class="${st.index % 2 == 0 ? 'even' : 'odd'}">
        <td>${st.count}</td>
        <td><c:out value="${book.title}" /></td>
    </tr>
</c:forEach>

<%-- 2. 遍历 Map 集合,迭代变量类型为 Map.Entry --%>
<c:forEach var="entry" items="${categoryMap}">
    <li><c:out value="${entry.key}" />:<c:out value="${entry.value}" /></li>
</c:forEach>

<%-- 3. 省略 items 属性,实现固定步长的计数循环 --%>
<c:forEach var="pageNo" begin="1" end="${totalPages}" step="1">
    <a href="?page=${pageNo}">${pageNo}</a>
</c:forEach>

边界注意:当 items 为 null 或空集合时,<c:forEach> 会静默跳过循环体而不会抛出 NullPointerException。此外,若迭代对象为 Iterator 或 Enumeration,由于单向迭代器无法提前预知剩余元素,应避免在同一页面中重复遍历同一迭代器实例。

c:forTokens ​

<c:forTokens> 专门用于按指定分隔符拆分字符串并逐段迭代,除 items(必填字符串)和 delims(必填分隔符集合)外,同样支持 var、begin、end、step 与 varStatus。

底层依托 java.util.StringTokenizer 实现,delims 字符串中的每一个字符都会被视为独立的分隔符,而不是将整个 delims 作为正则表达式或多字符整体匹配。

jsp
<%-- 1. 按逗号与分号任一字符拆分标签字符串并依次遍历 --%>
<c:forTokens var="tag" items="Java,Servlet;JSP,JSTL" delims=",;">
    <span class="badge"><c:out value="${tag}" /></span>
</c:forTokens>

URL 管理 ​

Web 应用在不同部署路径(Context Path)下运行时,硬编码绝对路径极易导致链接失效,同时手工拼接中文查询参数也容易引发乱码与注入风险。Core 标签库通过 URL 管理标签统一处理路径补全、参数编码、会话重写与跨资源引入。

c:url ​

<c:url> 用于规范化构造请求地址,核心行为包含三点:

  1. 上下文路径自动补全:当 value 以 / 开头时,自动拼接当前 Web 应用的上下文路径(如 /mall);若同时指定 context 属性(须以 / 开头),则拼接目标跨应用的上下文路径。

  2. 会话 ID 自动重写:对于相对 URL,内部调用 HttpServletResponse.encodeURL(),当客户端禁用 Cookie 时自动追加 ;jsessionid=... 以维持会话。

  3. 参数拼接与输出控制:支持嵌套 <c:param> 追加查询参数;指定 var 与 scope 时将结果存入作用域,省略 var 时直接输出到页面。

jsp
<%-- 1. 构建带上下文路径与 URL 编码查询参数的链接,并存入 page 作用域 --%>
<c:url var="searchUrl" value="/books/search">
    <c:param name="keyword" value="Java 编程" />
    <c:param name="page" value="1" />
</c:url>

<%-- 2. 在超链接中引用已生成的完整安全地址 --%>
<a href="${searchUrl}">查看检索结果</a>

c:param ​

<c:param> 作为辅助子标签嵌套在 <c:url>、<c:redirect> 或 <c:import> 内部使用,负责向目标 URL 追加查询参数。标签会自动根据当前响应字符编码对 name 与 value(或标签体内容)执行百分号 URL 编码,避免中文字符、&、= 或空格破坏查询字符串结构。若 name 为空字符串或 null,该参数会被忽略。

c:redirect ​

<c:redirect> 用于向客户端发送 HTTP 302 临时重定向响应,支持 url、context 属性及嵌套 <c:param> 子标签。

与在 Servlet 中直接调用 response.sendRedirect("/login.jsp") 不同,<c:redirect url="/login.jsp" /> 会自动在以 / 开头的路径前补全当前应用的上下文路径,并对相对路径执行会话重写。重定向触发后,当前 JSP 页面的剩余内容不再继续执行。

jsp
<%-- 1. 重定向至登录页并自动对回调地址进行 URL 编码 --%>
<c:redirect url="/login.jsp">
    <c:param name="from" value="/user/orders" />
</c:redirect>

c:import ​

<c:import> 用于在运行期动态引入外部或内部文本资源的内容,支持站内相对路径、同容器跨上下文路径(配合 context)以及完整的外部协议地址(如 http://、https://)。

相比 JSP 原生包含机制,<c:import> 具备更灵活的资源来源与输出去向控制:

特性<%@ include %><jsp:include><c:import>
执行时机静态转译期合并源码运行期动态包含运行期动态包含
资源范围仅限当前 Web 应用仅限当前 Web 应用当前应用、跨上下文应用及外部 URL
捕获至变量不支持不支持支持 var(字符串)与 varReader(字符流)
编码指定沿用主页面指令依赖目标响应编码支持 charEncoding 显式指定
  • 指定 var(配合可选 scope)时,引入的资源内容会被完整读取为 String 存入作用域,适合短小 HTML 片段或配置文本。
  • 指定 varReader 时,资源以 java.io.Reader 字符流形式暴露在 <c:import> 标签体内部,适合流式解析大体积内容(如交由 XML 标签解析),避免一次性将全部文本加载到堆内存中。
jsp
<%-- 1. 直接引入站内公共页眉片段并输出到当前响应流 --%>
<c:import url="/WEB-INF/views/common/header.jsp" charEncoding="UTF-8" />

<%-- 2. 将引入的外部文本内容缓存至变量,供后续按需处理 --%>
<c:import var="noticeHtml" url="https://static.example.com/notice.html" charEncoding="UTF-8" />

<%-- 3. 仅在成功获取非空内容时渲染公告区 --%>
<c:if test="${not empty noticeHtml}">
    <div class="notice">${noticeHtml}</div>
</c:if>

示例: 订单列表渲染 ​

以下片段整合了 Core 标签库的变量缓存、多分支判空、循环渲染、XSS 转义输出与安全 URL 构造,展示无 Scriptlet 视图的标准写法:

jsp
<%-- 1. 引入 JSTL Core 标签库 --%>
<%@ page contentType="text/html;charset=UTF-8" language="java" %>
<%@ taglib prefix="c" uri="http://java.sun.com/jsp/jstl/core" %>

<%-- 2. 判断订单列表是否非空并缓存至 page 作用域 --%>
<c:set var="hasOrders" value="${not empty orderList}" />

<section class="order-panel">
    <%-- 3. 根据集合是否为空切换空态提示与数据表格 --%>
    <c:choose>
        <c:when test="${not hasOrders}">
            <p>当前暂无订单记录</p>
        </c:when>

        <c:otherwise>
            <%-- 4. 遍历订单列表并渲染详情链接与状态标识 --%>
            <table>
                <tbody>
                    <c:forEach var="order" items="${orderList}" varStatus="st">
                        <tr>
                            <td>${st.count}</td>
                            <%-- 5. 使用 c:out 防范订单备注中的 XSS 注入 --%>
                            <td><c:out value="${order.remark}" default="无备注" /></td>
                            <td>
                                <c:if test="${order.paid}">已支付</c:if>
                                <c:if test="${not order.paid}">待支付</c:if>
                            </td>
                            <%-- 6. 使用 c:url 与 c:param 生成带上下文路径的详情地址 --%>
                            <td>
                                <c:url var="detailUrl" value="/order/detail">
                                    <c:param name="orderNo" value="${order.orderNo}" />
                                </c:url>
                                <a href="${detailUrl}">查看详情</a>
                            </td>
                        </tr>
                    </c:forEach>
                </tbody>
            </table>
        </c:otherwise>
    </c:choose>
</section>

API: ConditionalTagSupport【待补充】 ​

API: LoopTag【待补充】 ​

API: LoopTagStatus【待补充】 ​

API: LoopTagSupport【待补充】 ​

Formatting 标签库 ​

Formatting 标签库(约定前缀 fmt)专门处理 JSP 视图层的国际化(I18N)与本地化数据展示,在 JSTL 1.2 中对应 URI [http://java.sun.com/jsp/jstl/fmt](http://java.sun.com/jsp/jstl/fmt)(Jakarta JSTL 3.0 为 jakarta.tags.fmt)。它将区域设置、多语言资源包查找、数值货币格式化与日期时区转换封装为 12 个标准标签,避免在页面中直接操作 Locale、ResourceBundle、DecimalFormat 与 SimpleDateFormat。

国际化环境 ​

Formatting 标签库在执行消息读取、数字格式化或日期转换时,都会先确定当前请求生效的 Locale(区域对象)。JSTL 规范通过配置管理类 Config 统一协调作用域属性、Web 部署描述符(web.xml)初始化参数与 HTTP 请求头,按明确优先级解析生效区域:

  1. 作用域显式配置:通过 <fmt:setLocale> 或 Config 写入的 FMT_LOCALE 配置项,按 page → request → session → application(含 web.xml 上下文参数)顺序查找。

  2. 客户端首选语言:若未显式设置,容器提取 HTTP 请求头 Accept-Language 中的区域列表,并与当前资源包或 JVM 支持的格式区域进行匹配。

  3. 兜底回退区域:当客户端语言无法匹配目标资源时,回退至 FMT_FALLBACK_LOCALE 指定的默认区域,避免出现空白或异常格式。

image-20261119114612466

fmt:setLocale ​

<fmt:setLocale> 用于强制指定当前作用域生效的语言与国家/地区,核心属性如下:

  • value:必填,接收 java.util.Locale 实例或标准区域编码字符串(如 zh_CN、en_US、zh-CN,支持下划线或连字符分隔)。
  • variant:可选,用于指定浏览器或平台相关的区域变体。
  • scope:可选,默认为 page;多页面语言切换场景通常设为 session,使整个会话保持一致的语言环境。

<fmt:setLocale> 在写入区域配置的同时,还会自动调用 ServletResponse.setLocale() 更新响应区域与默认字符集。因此该标签应尽量写在页面顶部、任何产生响应输出或读取资源包的标签之前。

fmt:requestEncoding ​

当客户端以 POST 方式提交多语言表单数据,且请求头 Content-Type 未携带字符集说明时,Servlet 容器默认会按 ISO-8859-1 解码参数导致中文乱码。<fmt:requestEncoding> 内部会调用 ServletRequest.setCharacterEncoding() 指定请求体解码字符集。

若省略 value 属性,标签会尝试读取由 <fmt:setLocale> 在会话中记录的字符集;实际工程中通常显式传入 UTF-8。该标签必须在首次读取任何请求参数(如 ${param.xxx})之前执行,否则字符编码设定不会生效。

jsp
<%-- 1. 在读取表单参数前统一指定请求字符编码 --%>
<fmt:requestEncoding value="UTF-8" />

<%-- 2. 将当前会话的区域设置切换为美式英语 --%>
<fmt:setLocale value="en_US" scope="session" />

工程提示:在现代 Servlet 项目中,请求体编码一般由全局 Filter 统一设置;<fmt:requestEncoding> 主要用于无过滤器的独立 JSP 页面兜底。

资源包消息 ​

JSTL 的国际化文本管理建立在 Java 标准 java.util.ResourceBundle 之上,并通过 LocalizationContext 将加载后的 ResourceBundle 与对应的 Locale 绑定在一起,供消息标签高效复用。

资源文件遵循标准命名约定并放置在类路径(如 src/main/resources/i18n/)下:

  • messages.properties:默认兜底资源文件。
  • messages_zh_CN.properties:简体中文资源文件。
  • messages_en_US.properties:美式英语资源文件。

fmt:setBundle ​

<fmt:setBundle> 用于加载指定基名(basename)的资源包,并将其封装为 LocalizationContext 存入指定作用域(默认 page)。

  • 指定 var 属性时,资源包绑定到指定变量名,后续通过 <fmt:message bundle="${var}"> 显式引用,适合单页面同时使用多个业务模块资源包的场景。
  • 省略 var 属性时,会直接覆盖当前作用域默认的 FMT_LOCALIZATION_CONTEXT 配置,页面内所有未指定 bundle 的 <fmt:message> 均自动使用该资源包。

fmt:bundle ​

<fmt:bundle> 将资源包的作用范围限定在自身的开始与结束标签体内部,离开标签体后即恢复外层默认资源包。它额外支持 prefix 属性,可为标签体内所有 <fmt:message> 的 key 自动拼接统一前缀,显著减少冗长的点分键名重复。

fmt:message ​

<fmt:message> 根据 key 从资源包检索对应的本地化文本,支持嵌套 <fmt:param> 按位置替换 java.text.MessageFormat 风格的占位符({0}、{1} 等)。

  • 若指定的 key 在资源包中不存在,标签不会抛出异常,而是默认输出 ???<key>??? 格式的占位提示,便于开发期快速定位漏翻词条。
  • 支持通过 var 与 scope 将格式化后的消息文本缓存至作用域,而不是立即输出到页面。
jsp
<%-- 1. 加载类路径下的 i18n/messages.properties 并存入 session 作用域 --%>
<fmt:setBundle basename="i18n.messages" var="msgBundle" scope="session" />

<%-- 2. 从指定资源包读取消息键,并按顺序填充占位符参数 --%>
<fmt:message key="order.greeting" bundle="${msgBundle}">
    <fmt:param value="${sessionScope.user.name}" />
    <fmt:param value="${orderCount}" />
</fmt:message>

<%-- 3. 局部加载独立资源包,并为内部所有键自动添加统一前缀 --%>
<fmt:bundle basename="i18n.errors" prefix="auth.">
    <p><fmt:message key="invalidPassword" /></p>
</fmt:bundle>

编码注意:在 JDK 8 环境下,ResourceBundle 默认按 ISO-8859-1 读取 .properties 文件,中文字符需进行 Unicode 转义(或通过 IDE 开启自动转码);JDK 9 及以上版本已默认原生支持 UTF-8 编码读取。

数值格式化 ​

视图层经常需要将原始浮点或 BigDecimal 数值格式化为千分位数字、本地货币或百分比,并在必要时将用户输入的本地化数值字符串解析回 Java Number 对象。

fmt:formatNumber ​

<fmt:formatNumber> 底层委托 java.text.NumberFormat 与 java.text.DecimalFormat 完成格式化输出,支持三类标准格式与自定义模式:

核心属性常见取值与作用
value待格式化的数值或数字字符串,也可通过标签体传入
typenumber(默认普通数字)、currency(货币)、percent(百分比)
pattern自定义 DecimalFormat 模式(如 #,##0.00),指定后会覆盖 type
currencyCode / currencySymbol显式指定 ISO 4217 货币代码(如 CNY、USD)或自定义货币符号
groupingUsed是否启用千分位分组分隔符,默认为 true
maxFractionDigits / minFractionDigits控制小数部分的最大与最小位数(超出时默认采用半偶数舍入 HALF_EVEN)
var / scope将格式化后的结果字符串存入作用域而不直接输出

fmt:parseNumber ​

<fmt:parseNumber> 是 <fmt:formatNumber> 的逆操作,用于按当前区域或指定 pattern 将格式化字符串(如带千分位逗号、货币符号或百分号的字符串)解析为 java.lang.Number 实例。

  • integerOnly 设为 true 时,仅解析整数部分并截断小数部分。
  • parseLocale 允许临时指定与当前页面区域不同的解析区域,避免跨区数据格式冲突。
jsp
<%-- 1. 按当前区域格式化为货币金额,也可显式指定 ISO 货币代码 --%>
<fmt:formatNumber value="${order.amount}" type="currency" currencyCode="CNY" />

<%-- 2. 按百分比格式输出,并精确控制小数位数 --%>
<fmt:formatNumber value="${discountRate}" type="percent" minFractionDigits="1" maxFractionDigits="1" />

<%-- 3. 使用 DecimalFormat 自定义格式模式并关闭千分位分组 --%>
<fmt:formatNumber value="${product.price}" pattern="#0.00" groupingUsed="false" />

<%-- 4. 将本地化格式字符串反向解析为 Number 对象存入 page 作用域 --%>
<fmt:parseNumber var="parsedPrice" value="1,299.50" type="number" />

日期格式化 ​

时间展示高度依赖所在时区与区域习惯。Formatting 标签库通过时区配置标签与日期格式化、解析标签协作,确保同一时间戳在不同用户视角下呈现准确的本地日期时间。

fmt:setTimeZone ​

<fmt:setTimeZone> 用于将指定的 TimeZone 对象或标准时区 ID(如 Asia/Shanghai、UTC、GMT+8)写入 Config 管理的 FMT_TIME_ZONE 配置中,影响目标作用域(默认 page)内所有后续日期格式化与解析操作。若指定了 var 属性,则仅将该 TimeZone 实例存入变量,不改变全局默认时区。

fmt:timeZone ​

<fmt:timeZone> 用于在局部标签体范围内临时覆盖默认时区,适合同一页面中对比展示多地时间(例如同时显示服务器 UTC 时间与用户本地时间)。标签体结束后自动失效,不修改外层作用域配置。

fmt:formatDate ​

<fmt:formatDate> 底层基于 java.text.DateFormat 与 java.text.SimpleDateFormat,将 java.util.Date 实例格式化为目标字符串:

  • type:决定输出粒度,可选 date(默认,仅日期)、time(仅时间)或 both(日期与时间)。
  • dateStyle / timeStyle:使用内置本地化风格,可选 default、short、medium、long、full。
  • pattern:自定义 SimpleDateFormat 格式模板(如 yyyy-MM-dd HH:mm:ss),优先级高于 type、dateStyle 与 timeStyle。
  • timeZone:为当前单次格式化单独指定时区,优先级高于外层 <fmt:timeZone> 与 <fmt:setTimeZone>。

版本兼容限制:<fmt:formatDate> 严格要求 value 必须是 java.util.Date 类型,**不能直接接收 Java 8 的 LocalDate、LocalDateTime 或 Instant**,传入后会抛出类型转换异常。若实体类使用 java.time类型,应在控制器或视图模型中提前格式化为字符串,或先通过<fmt:parseDate> 转换后再渲染。

fmt:parseDate ​

<fmt:parseDate> 按指定 pattern 或区域日期风格,将日期字符串反向解析为 java.util.Date 对象,通常配合 var 存入 page 作用域,供后续 <fmt:formatDate> 按不同本地风格重新格式化展示。

jsp
<%-- 1. 将当前请求默认时区设置为东八区 --%>
<fmt:setTimeZone value="Asia/Shanghai" scope="request" />

<%-- 2. 按指定模式格式化 java.util.Date 实例 --%>
<fmt:formatDate value="${order.createdAt}" pattern="yyyy-MM-dd HH:mm:ss" />

<%-- 3. 局部切换为 UTC 时区渲染日志时间,不影响外部默认时区 --%>
<fmt:timeZone value="UTC">
    <fmt:formatDate value="${order.createdAt}" type="both" dateStyle="medium" timeStyle="short" />
</fmt:timeZone>

<%-- 4. 将字符串解析为 java.util.Date 并存入变量供后续格式化 --%>
<fmt:parseDate var="expireDate" value="2026-12-31 23:59:59" pattern="yyyy-MM-dd HH:mm:ss" />

示例: 多语言商品详情页 ​

以下示例展示如何通过多语言 .properties 资源包配合 Formatting 标签库,实现动态语言切换、带参数文案拼接、货币本地化与日期格式化。首先在类路径 i18n 目录下准备中英文两份资源文件:

properties
# 1. messages_zh_CN.properties(中文资源包)
product.title=商品详情
product.stockTip=当前库存仅剩 {0} 件,更新于 {1}
product.priceLabel=零售价

# 2. messages_en_US.properties(英文资源包)
product.title=Product Detail
product.stockTip=Only {0} left in stock, updated at {1}
product.priceLabel=Price

随后在 JSP 页面中结合 URL 参数动态切换 session 级区域设置,并完成资源读取与本地化格式化:

jsp
<%-- 1. 声明编码并引入 Core 与 Formatting 标签库 --%>
<%@ page contentType="text/html;charset=UTF-8" language="java" %>
<%@ taglib prefix="c" uri="http://java.sun.com/jsp/jstl/core" %>
<%@ taglib prefix="fmt" uri="http://java.sun.com/jsp/jstl/fmt" %>

<%-- 2. 若请求参数携带 lang(如 zh_CN 或 en_US),动态切换会话区域 --%>
<c:if test="${not empty param.lang}">
    <fmt:setLocale value="${param.lang}" scope="session" />
</c:if>

<%-- 3. 绑定当前请求默认资源包与显示时区 --%>
<fmt:setBundle basename="i18n.messages" />
<fmt:setTimeZone value="Asia/Shanghai" />

<%-- 4. 格式化商品上架时间并缓存至变量,作为消息占位符参数 --%>
<fmt:formatDate var="formattedTime" value="${product.updatedAt}" pattern="yyyy-MM-dd HH:mm" />

<section class="product-card">
    <%-- 5. 读取国际化标题与带参数占位符的库存文案 --%>
    <h1><fmt:message key="product.title" /></h1>
    <p>
        <fmt:message key="product.stockTip">
            <fmt:param value="${product.stock}" />
            <fmt:param value="${formattedTime}" />
        </fmt:message>
    </p>

    <%-- 6. 按当前区域格式化商品价格 --%>
    <p>
        <fmt:message key="product.priceLabel" />:
        <fmt:formatNumber value="${product.price}" type="currency" />
    </p>
</section>

API: Config【待补充】 ​

API: LocalizationContext【待补充】 ​

Functions 函数库 ​

Functions 函数库(约定前缀 fn)是 JSTL 提供的标准 EL 函数集合,在 JSTL 1.2 中对应 URI [http://java.sun.com/jsp/jstl/functions](http://java.sun.com/jsp/jstl/functions)(Jakarta JSTL 3.0 为 jakarta.tags.functions)。与 Core、Formatting 等通过 <prefix:tag> 形式书写的自定义标签库不同,Functions 库包含 16 个面向字符串与集合处理的工具函数,全部只能嵌入在 EL 表达式 ${...} 内部调用,不能作为独立 XML 标签使用。

EL 函数映射 ​

Functions 函数库同样通过 <%@ taglib %> 指令引入,但底层在 fn.tld 描述文件中声明的是 <function> 元素而非 <tag> 元素。每个 <function> 将函数名映射到实现类(如 Apache Standard Taglib 中的 org.apache.taglibs.standard.functions.Functions)中的一个 public static Java 方法。

JSP 引擎转译并执行包含 fn 函数的页面时,按以下链路完成解析与调用:

  1. 转译期注册映射:容器扫描 fn.tld,提取 <function> 中的 <name>、<function-class> 与 <function-signature>,生成静态的 FunctionMapper 映射表。

  2. 参数类型强制转换:运行期 EL 引擎求值 ${fn:xxx(...)} 前,会依据方法签名执行标准 EL 类型转换;绝大多数字符串函数会将 null 参数自动转为长度为 0 的空字符串 ""。

  3. 反射调用静态方法:EL 引擎通过 FunctionMapper 解析到对应的 java.lang.reflect.Method 对象并执行调用,将返回值交还给外层表达式继续运算或输出。

image-20261119114634136

工程对比:虽然 Tomcat 7 及以上支持的 EL 2.2+ 已允许直接调用对象的实例方法(如 ${str.toUpperCase()}、${list.size()}),但直接调用 Java 原生方法在对象为 null 或索引越界时容易引发异常;JSTL Functions 函数在 null 容错、索引安全截断以及 XML 转义方面仍具有更高的视图层健壮性。

长度统计 ​

fn:length 是 Functions 函数库中唯一专门面向多种容器类型的函数,用于计算字符串字符数或集合元素总数,常与条件判断和分页统计配合使用。

支持的参数类型包括:

  • 字符串:返回 String.length()。
  • 集合与映射:支持 Collection(返回 size())及 Map(返回键值对条目数 size())。
  • 数组:支持任意对象数组与基本类型数组(返回数组长度)。
  • 单向迭代器:支持 Iterator 与 Enumeration,但底层会遍历迭代直至末尾来累加计数,执行完成后迭代器即被耗尽,无法再次用于 <c:forEach> 遍历。
  • 空值与非法类型:传入 null 时安全返回 0;传入其他不支持的普通 JavaBean 对象则会抛出 JspTagException。
jsp
<%-- 1. 引入 JSTL Core 与 Functions 函数库 --%>
<%@ taglib prefix="c" uri="http://java.sun.com/jsp/jstl/core" %>
<%@ taglib prefix="fn" uri="http://java.sun.com/jsp/jstl/functions" %>

<%-- 2. 统计集合与字符串长度,传入 null 时安全返回 0 --%>
<p>共找到 ${fn:length(productList)} 件商品</p>
<p>标题字数:${fn:length(article.title)}</p>

<%-- 3. 结合 Core 标签按集合元素数量控制展示逻辑 --%>
<c:if test="${fn:length(cart.items) > 0}">
    <span class="badge">${fn:length(cart.items)}</span>
</c:if>

使用边界:若仅需判断字符串或集合是否为空,优先使用 EL 原生运算符 ${empty list};仅在需要获取具体数量、比较阈值或计算截断位置时使用 fn:length。

文本检索 ​

文本检索类函数用于在模板判断中检查子串是否存在、校验前后缀或定位子串索引,统一具备 null 安全特性(源字符串或目标子串为 null 时均视为 "")。

函数返回类型核心行为与边界规则
fn:contains(input, substring)boolean区分大小写判断包含关系;目标子串为 "" 时恒返回 true
fn:containsIgnoreCase(input, substring)boolean忽略大小写判断包含关系,底层统一转换后再比对
fn:startsWith(input, prefix)boolean区分大小写判断是否以指定前缀开头
fn:endsWith(input, suffix)boolean区分大小写判断是否以指定后缀结尾
fn:indexOf(input, substring)int返回子串首次出现的从 0 开始的索引;未匹配时返回 -1
jsp
<%-- 1. 忽略大小写判断角色权限字符串中是否包含 ADMIN --%>
<c:if test="${fn:containsIgnoreCase(user.roles, 'admin')}">
    <a href="/admin">系统管理</a>
</c:if>

<%-- 2. 校验文件名后缀以决定渲染图标类型 --%>
<c:if test="${fn:endsWith(attachment.name, '.pdf')}">
    <span class="icon-pdf">PDF 文档</span>
</c:if>

<%-- 3. 查找子串首次出现的位置,未命中返回 -1 --%>
<c:set var="atPos" value="${fn:indexOf(user.email, '@')}" />

子串截取 ​

子串截取类函数支持按索引区间或按指定分隔符前后提取文本。与 Java 原生 String.substring() 相比,JSTL 截取函数对越界索引进行了全方位的安全收敛,绝不会因为数据长度不足抛出 StringIndexOutOfBoundsException。

函数核心行为与边界规则
fn:substring(input, begin, end)左闭右开截取 [begin, end);begin < 0 自动修正为 0;end < 0 或大于字符串长度时截取至末尾;begin >= end 返回 ""
fn:substringBefore(input, str)返回 str 首次出现之前的全部子串;未找到 str 或 str 为 "" 时返回 ""
fn:substringAfter(input, str)返回 str 首次出现之后的全部子串;未找到 str 返回 "";str 为 "" 时返回原字符串
jsp
<%-- 1. 截取前 20 个字符作为预览;结束索引超出长度时自动截断不抛异常 --%>
<p>${fn:substring(article.summary, 0, 20)}</p>

<%-- 2. 结束索引传 -1 表示从起始位置一直截取到字符串末尾 --%>
<p>脱敏尾号:${fn:substring(user.phone, 7, -1)}</p>

<%-- 3. 提取邮箱用户名与域名部分 --%>
<p>账号名:${fn:substringBefore(user.email, '@')}</p>
<p>服务商:${fn:substringAfter(user.email, '@')}</p>

拆分重组 ​

fn:split 与 fn:join 负责字符串与字符串数组之间的双向转换,常与 <c:forEach> 配合处理标签列表、多值配置或面包屑路径。

  • fn:split(input, delimiters):底层与 <c:forTokens> 一致,基于 java.util.StringTokenizer 按字符集拆分,返回一个 String[]。delimiters 中的每一个字符都被视为独立分隔符,不支持正则表达式,且连续出现的分隔符会被自动折叠跳过,不会产生空串元素。若源字符串为空,返回仅含一个空字符串的单元素数组或空数组(随实现略有差异,遍历前建议判空)。
  • fn:join(array, separator):将 String[] 数组中的元素依次用 separator 连接为单个字符串。传入 null 数组返回 "",separator 为 null 时按空字符串直接拼接。

类型限制:fn:join 的第一个参数在签名上严格声明为 String[],不能直接传入 List<String>,否则 EL 类型转换阶段会抛出异常。若需拼接 List 集合,可在 <c:forEach> 中利用 ${not st.last} 拼接分隔符,或在控制器层提前转为数组。

jsp
<%-- 1. 按逗号与竖线任意字符拆分标签字符串,返回 String[] --%>
<c:set var="tagArray" value="${fn:split('Java,JSP|JSTL', ',|')}" />

<%-- 2. 遍历拆分后的字符串数组 --%>
<c:forEach var="tag" items="${tagArray}">
    <span class="tag">${tag}</span>
</c:forEach>

<%-- 3. 将 String[] 数组按指定连接符重新拼接为展示文本 --%>
<p>技术栈:${fn:join(tagArray, ' / ')}</p>

文本清洗 ​

文本清洗类函数用于处理页面渲染前的空白清理、大小写归一化以及纯文本替换。

函数核心行为与边界规则
fn:trim(input)去除首尾编码值不大于 \u0020 的 ASCII 空白字符(等价于 String.trim()),不移除中文全角空格 \u3000
fn:toLowerCase(input)将字符串中的所有字符转为小写
fn:toUpperCase(input)将字符串中的所有字符转为大写
fn:replace(input, before, after)按纯字面量将所有 before 子串替换为 after(非正则替换);before 为 "" 时原样返回 input
jsp
<%-- 1. 去除用户输入关键词的首尾空白字符 --%>
<c:set var="cleanKeyword" value="${fn:trim(param.keyword)}" />

<%-- 2. 将国家或货币代码统一转换为大写形式 --%>
<span>${fn:toUpperCase(order.currency)}</span>

<%-- 3. 将文本中的协议前缀按字面量全局替换 --%>
<p>${fn:replace(article.plainText, 'http://', 'https://')}</p>

XML 转义 ​

fn:escapeXml(input) 将字符串中的 <、>、&、'、" 五个 XML/HTML 特殊字符分别转义为 &lt;、&gt;、&amp;、&#039;、&#034;,其转义规则与 <c:out> 默认行为完全一致。

两者的核心使用分工如下:

  • 标签体内普通文本输出:优先使用 <c:out value="${...}" default="..." />,兼顾转义与默认值回退。
  • HTML 标签属性值回显:在 <input value="...">、<img alt="..."> 或 title="..." 等属性内部,直接书写 ${fn:escapeXml(val)} 结构更紧凑,既能阻断恶意双引号闭合属性引发的 XSS 注入,又能避免标签嵌套标签导致的 HTML 语法校验告警。
jsp
<%-- 1. 在 HTML 属性值中使用 fn:escapeXml 防止引号闭合引发 XSS --%>
<input type="text" name="keyword" value="${fn:escapeXml(param.keyword)}" />

<%-- 2. 在 title 提示属性中安全输出用户简介与昵称 --%>
<span title="${fn:escapeXml(user.bio)}">${fn:escapeXml(user.nickname)}</span>

<%-- 3. 避免与默认开启转义的 c:out 叠加使用,防止出现双重转义 --%>
<p><c:out value="${user.nickname}" /></p>

防踩坑提示:严禁写成 <c:out value="${fn:escapeXml(str)}" />。因为 fn:escapeXml 会先将 < 转为 &lt;,随后 <c:out> 再次将 & 转为 &amp;,最终页面会直接向用户显示字面文本 &lt;。

示例: 文章列表摘要渲染 ​

以下示例综合运用 fn:trim、fn:escapeXml、fn:length、fn:containsIgnoreCase、fn:substring 与 fn:split,在无任何 Java 脚本的情况下完成搜索回显、标题命中提示、超长正文安全截断与多标签拆分展示:

jsp
<%-- 1. 声明页面编码并引入 Core 与 Functions 库 --%>
<%@ page contentType="text/html;charset=UTF-8" language="java" %>
<%@ taglib prefix="c" uri="http://java.sun.com/jsp/jstl/core" %>
<%@ taglib prefix="fn" uri="http://java.sun.com/jsp/jstl/functions" %>

<%-- 2. 在搜索框属性中回显清洗并转义后的关键词 --%>
<c:set var="kw" value="${fn:trim(param.keyword)}" />
<input type="search" name="keyword" value="${fn:escapeXml(kw)}" />

<section class="article-list">
    <%-- 3. 使用 fn:length 展示文章总数 --%>
    <p>共检索到 ${fn:length(articles)} 篇文章</p>

    <c:forEach var="art" items="${articles}">
        <article>
            <%-- 4. 忽略大小写判断标题是否命中当前搜索词 --%>
            <h3>
                <c:out value="${art.title}" />
                <c:if test="${not empty kw and fn:containsIgnoreCase(art.title, kw)}">
                    <span class="match-flag">标题匹配</span>
                </c:if>
            </h3>

            <%-- 5. 对超长正文执行去空白与定长截断 --%>
            <c:set var="brief" value="${fn:trim(art.content)}" />
            <p>
                <c:out value="${fn:length(brief) > 60 ? fn:substring(brief, 0, 60) : brief}" />
                <c:if test="${fn:length(brief) > 60}">...</c:if>
            </p>

            <%-- 6. 拆分逗号分隔的标签字符串并逐项渲染 --%>
            <div class="tags">
                <c:forEach var="tag" items="${fn:split(art.tags, ',')}">
                    <span class="tag"><c:out value="${fn:trim(tag)}" /></span>
                </c:forEach>
            </div>
        </article>
    </c:forEach>
</section>

XML 标签库 ​

XML 标签库(约定前缀 x)用于以声明式标签处理 XML 文档,在 JSTL 1.2 中对应 URI [http://java.sun.com/jsp/jstl/xml](http://java.sun.com/jsp/jstl/xml)(Jakarta JSTL 3.0 为 jakarta.tags.xml)。它将原本需要编写大量 DOM、SAX 与 JAXP 样板代码的文档解析、XPath 节点筛选、条件迭代以及 XSLT 样式表转换封装为 10 个标准标签。

在现代前后端分离架构中,JSON 已取代 XML 成为主流数据交换格式,XML 标签库在新项目中的使用频率较低,但仍广泛见于传统企业级报表、RSS/Atom 订阅源解析以及基于 XSLT 的文档渲染系统。

image-20261119114657082

Xalan 依赖 ​

与 Core 和 Formatting 标签库不同,Apache Standard Taglib 实现的 XML 标签在运行期依赖 Apache Xalan 提供的 XPath 求值与 XSLT 转换引擎。如果项目仅引入了 taglibs-standard-spec 与 taglibs-standard-impl,执行 XML 标签时会直接抛出 NoClassDefFoundError: org/apache/xpath/XPathException 或 XSLT 工厂初始化异常。

在 Maven 工程中,需要显式补齐 Xalan 核心库及其序列化依赖:

xml
<!-- 1. 引入 Apache Xalan,为 JSTL XML 标签提供 XPath 与 XSLT 引擎 -->
<dependency>
    <groupId>xalan</groupId>
    <artifactId>xalan</artifactId>
    <version>2.7.3</version>
</dependency>

<!-- 2. 引入配套序列化组件,供 XSLT 转换结果输出使用 -->
<dependency>
    <groupId>xalan</groupId>
    <artifactId>serializer</artifactId>
    <version>2.7.3</version>
</dependency>

安全警示:解析外部来源的 XML 时存在 XXE(XML External Entity,外部实体注入)风险。尽管 Apache Standard Taglib 1.2.3 及以上版本默认强化了外部实体访问限制,生产环境仍不应将未经过滤的用户上传 XML 直接交由 JSP 视图层的 <x:parse> 处理。

XPath 作用域绑定 ​

XML 标签库最容易与 Core 标签库混淆之处在于 select 属性的求值规则。所有 XML 标签的 select 属性均由 XPath 1.0 引擎而非 EL 引擎解析,因此在 select 属性中不能书写 ${...},而必须使用 XPath 原生的 $变量名 语法访问 JSP 作用域数据。

JSTL 规范为 XPath 引擎定义了与 EL 隐式对象一一对应的命名空间前缀,用于在 XPath 表达式中精准引用 Web 作用域与请求上下文:

XPath 变量语法对应数据来源
$var依次从 page → request → session → application 查找属性
$pageScope:var仅从 page 作用域读取指定属性
$requestScope:var仅从 request 作用域读取指定属性
$sessionScope:var仅从 session 作用域读取指定属性
$applicationScope:var仅从 application 作用域读取指定属性
$param:name读取单个 HTTP 请求参数值
$header:name读取单个 HTTP 请求头的值
$cookie:name读取指定名称的 Cookie 值
$initParam:name读取 web.xml 中配置的全局上下文初始化参数

需要注意的是,只有 select 属性使用 XPath 语法;诸如 <x:parse> 的 doc 属性以及 <x:transform> 的 doc、xslt 属性仍接收标准 EL 表达式 ${...}。

文档操作 ​

文档操作类标签负责将原始 XML 文本或字符流解析为可查询的节点树,并提取节点值输出到响应流或存入指定作用域。

x:parse ​

<x:parse> 将 XML 文本解析为内存文档对象,供后续 XPath 标签检索,核心属性如下:

  • doc:待解析的 XML 数据源,接收 String 或 java.io.Reader(通常配合 <c:import varReader="..."> 实现流式读取),也可直接将 XML 文本写在 <x:parse> 标签体内部。早期的 xml 属性在 JSTL 1.1 后已废弃,应统一使用 doc。
  • var / scope:将解析结果存入指定作用域(默认 page),容器可采用与具体 XPath 引擎匹配的内部优化结构存储。
  • varDom / scopeDom:强制要求解析结果导出为标准的 org.w3c.dom.Document 对象,便于传递给其他 Java 组件处理。
  • filter:可选,接收实现了 org.xml.sax.XMLFilter 接口的对象,用于在构建文档树之前按需剔除无关节点,降低大文档的内存占用。
  • systemId:指定 XML 文档的基准 URI,用于解析文档内部引用的相对外部实体路径。

x:out ​

<x:out> 计算 select 指定的 XPath 表达式,将结果转换为字符串后写入当前 JspWriter 输出流,定位上等同于 XML 领域的 <c:out>。

  • escapeXml 默认为 true,输出前会自动转义 <、>、&、'、" 五个特殊字符以防范 XSS。
  • 当 XPath 匹配到节点集(Node-set)时,按照 XPath 1.0 规范,仅取集合中第一个节点的字符串值输出。

x:set ​

<x:set> 计算 select 指定的 XPath 表达式,并将结果对象(可以是节点集、单个节点、布尔值、数值或字符串)以 var 为名保存到 scope 指定的作用域(默认为 page)中,便于复用局部子树或简化后续冗长的 XPath 路径。

jsp
<%-- 1. 引入 Core 与 XML 标签库 --%>
<%@ taglib prefix="c" uri="http://java.sun.com/jsp/jstl/core" %>
<%@ taglib prefix="x" uri="http://java.sun.com/jsp/jstl/xml" %>

<%-- 2. 使用 c:import 读取 XML 文本,并通过 x:parse 解析为文档对象 --%>
<c:import var="booksXml" url="/WEB-INF/data/books.xml" charEncoding="UTF-8" />
<x:parse doc="${booksXml}" var="booksDoc" />

<%-- 3. 使用 XPath 提取首个节点文本,默认开启 XML 特殊字符转义 --%>
<p>首本图书:<x:out select="$booksDoc/books/book[1]/title" /></p>

<%-- 4. 将 XPath 筛选出的子树节点缓存到 request 作用域 --%>
<x:set var="firstBook" select="$booksDoc/books/book[1]" scope="request" />

流程控制 ​

XML 标签库提供与 Core 标签库结构对称的条件判断和迭代标签,区别在于条件表达式与迭代目标全部基于 XPath 计算。

x:if ​

<x:if> 计算 select 指定的 XPath 表达式,并按 XPath 布尔转换规则(非空节点集、非零数值、非空字符串均为 true)决定是否渲染标签体。支持通过 var 与 scope 缓存布尔计算结果,供后续标签复用。

x:choose ​

<x:choose> 配合子标签 <x:when select="..."> 与 <x:otherwise> 构成多分支互斥判断结构。其嵌套规则与 <c:choose> 一致:至少包含一个 <x:when>,<x:otherwise> 最多出现一次且必须位于末尾,容器按顺序命中首个为真的 <x:when> 后短路退出。

x:forEach ​

<x:forEach> 用于遍历 select 返回的 XPath 节点集,底层同样继承自 LoopTagSupport,支持 begin、end、step、var 与 varStatus 属性。

在 <x:forEach> 标签体执行期间,当前迭代到的节点会自动成为内部所有相对 XPath 表达式的上下文节点。因此既可以通过 $var/title 访问子节点,也可以直接使用相对路径 title 或 . 引用当前节点。

jsp
<%-- 1. 按 XPath 路径遍历所有 book 节点,当前节点自动成为内部 XPath 上下文 --%>
<x:forEach select="$booksDoc/books/book" var="book" varStatus="st">
    <div class="book-item">
        <span>${st.count}. <x:out select="$book/title" /></span>

        <%-- 2. 使用 x:if 判断属性条件 --%>
        <x:if select="$book/@featured = 'true'">
            <span class="badge">推荐</span>
        </x:if>

        <%-- 3. 使用 x:choose 按价格区间执行多分支判断 --%>
        <x:choose>
            <x:when select="$book/price >= 100">
                <span>高价专业书</span>
            </x:when>
            <x:otherwise>
                <span>常规图书</span>
            </x:otherwise>
        </x:choose>
    </div>
</x:forEach>

XSLT 转换 ​

当 XML 结构较复杂或需要直接套用现成的 XSLT 样式表生成 HTML、SVG 或另一份 XML 文档时,XML 标签库提供了转换标签与参数注入标签。

x:transform ​

<x:transform> 底层调用 JAXP javax.xml.transform.Transformer,将源 XML 文档与 XSLT 样式表结合执行转换,核心属性包括:

  • doc:源 XML 数据,支持 String、Reader、javax.xml.transform.Source、org.w3c.dom.Document 或 <x:parse> 解析产物;也可写在标签体中。
  • xslt:必填,XSLT 样式表,支持 String、Reader 或 javax.xml.transform.Source。
  • docSystemId / xsltSystemId:分别为源文档与样式表指定基准 URI,供 <xsl:import> 或 <xsl:include> 解析相对路径。
  • var / scope:省略时直接将转换结果输出到页面响应流;指定 var 时以 org.w3c.dom.Document 存入作用域。
  • result:可选,接收自定义 javax.xml.transform.Result 对象(如 StreamResult),将转换输出重定向至指定目标流。

x:param ​

<x:param> 必须嵌套在 <x:transform> 内部使用,通过 name 与 value(或标签体)向 XSLT 样式表中声明的顶层 <xsl:param> 传递动态运行期参数,使静态 XSLT 模板具备按请求条件定制输出的能力。

jsp
<%-- 1. 读取源 XML 文档与 XSLT 样式表内容 --%>
<c:import var="booksXml" url="/WEB-INF/data/books.xml" charEncoding="UTF-8" />
<c:import var="booksXsl" url="/WEB-INF/data/books.xsl" charEncoding="UTF-8" />

<%-- 2. 应用 XSLT 样式表转换 XML,并通过 x:param 传入动态参数 --%>
<x:transform doc="${booksXml}" xslt="${booksXsl}">
    <x:param name="currencySymbol" value="¥" />
    <x:param name="maxPrice" value="${param.maxPrice}" />
</x:transform>

示例: 图书目录 XML 渲染 ​

以下示例演示如何将站内 XML 目录文件以字符流方式交给 <x:parse> 解析,并结合 XPath $param: 变量按请求参数动态筛选并渲染列表。首先准备数据源文件 /WEB-INF/data/books.xml:

xml
<!-- 1. 图书目录源文档 books.xml -->
<books>
    <!-- 2. Java 分类图书节点 -->
    <book id="101" category="java">
        <title>Effective Java</title>
        <author>Joshua Bloch</author>
        <price>119.00</price>
    </book>

    <!-- 3. 数据库分类图书节点 -->
    <book id="102" category="db">
        <title>高性能 MySQL</title>
        <author>Silvia Botros</author>
        <price>158.00</price>
    </book>
</books>

随后在 JSP 页面中利用 <c:import varReader="..."> 避免整份文本重复拷贝,并在 XPath 谓词中直接读取请求参数 category 完成条件过滤:

jsp
<%-- 1. 声明页面编码并引入 Core 与 XML 标签库 --%>
<%@ page contentType="text/html;charset=UTF-8" language="java" %>
<%@ taglib prefix="c" uri="http://java.sun.com/jsp/jstl/core" %>
<%@ taglib prefix="x" uri="http://java.sun.com/jsp/jstl/xml" %>

<%-- 2. 使用 varReader 流式读取大体积 XML,交由 x:parse 解析为文档对象 --%>
<c:import url="/WEB-INF/data/books.xml" varReader="xmlReader" charEncoding="UTF-8">
    <x:parse doc="${xmlReader}" var="catalog" />
</c:import>

<%-- 3. 依据请求参数 category 动态构建筛选结果,未传参时展示全部 --%>
<section class="catalog">
    <table>
        <tbody>
            <x:forEach select="$catalog/books/book[not(string($param:category)) or @category = $param:category]" var="item" varStatus="st">
                <%-- 4. 提取节点属性与子元素文本并安全输出 --%>
                <tr>
                    <td>${st.count}</td>
                    <td><x:out select="$item/title" /></td>
                    <td><x:out select="$item/author" /></td>
                    <%-- 5. 对高价图书附加醒目标记 --%>
                    <td>
                        <x:out select="$item/price" />
                        <x:if select="$item/price >= 150">(精装)</x:if>
                    </td>
                </tr>
            </x:forEach>
        </tbody>
    </table>
</section>

SQL 标签库 ​

SQL 标签库(约定前缀 sql)用于直接在 JSP 页面中操作关系型数据库,在 JSTL 1.2 中对应 URI [http://java.sun.com/jsp/jstl/sql](http://java.sun.com/jsp/jstl/sql)(Jakarta JSTL 3.0 为 jakarta.tags.sql)。它将数据源配置、参数化查询、数据更新以及本地事务边界封装为 6 个标准标签,底层基于 JDBC 的 DataSource、Connection 与 PreparedStatement 执行。

架构边界:在视图层直接嵌入 SQL 语句违背 MVC 分层原则,会导致业务规则与数据库表结构耦合在页面中、难以进行单元测试与权限管控。SQL 标签库仅适用于小型原型验证、教学演示或内部临时报表,正式生产项目应将数据库访问严格收敛至 DAO / Repository 层。

image-20261119114716381

数据源配置 ​

所有执行 SQL 的标签都依赖 javax.sql.DataSource 获取数据库连接。JSTL 规范通过 Config 类的 SQL_DATA_SOURCE 配置项统一解析数据源,优先级从高到低依次为:

  1. 当前标签(或外层 <sql:transaction>)显式传入的 dataSource 属性。

  2. 按 page → request → session → application 顺序查找的 SQL_DATA_SOURCE 作用域属性。

  3. web.xml 中配置的同名 <context-param> 全局初始化参数。

同时,规范还提供了 SQL_MAX_ROWS 配置项,用于在全局或作用域级别限制单次查询默认返回的最大行数,避免误操作将整张大表加载到内存中。

sql:setDataSource ​

<sql:setDataSource> 用于向指定作用域注册数据源,支持两种配置方式:

  • 引用现有数据源(推荐):通过 dataSource 属性绑定容器 JNDI 路径(相对 java:comp/env/,如 jdbc/MallDB)、直接传入已放入作用域的 javax.sql.DataSource 实例(如 Druid 或 HikariCP 连接池),或传入逗号分隔的 JDBC 四元组字符串。
  • 直连 JDBC 参数:分别配置 driver、url、user 与 password 属性。

指定 var 与 scope(默认 page)时,数据源以变量形式存储并供后续标签通过 dataSource="${var}" 引用;省略 var 时则直接覆盖对应作用域默认的 SQL_DATA_SOURCE 配置。

jsp
<%-- 1. 优先绑定已配置连接池的 JNDI 或作用域 DataSource 对象 --%>
<%@ taglib prefix="sql" uri="http://java.sun.com/jsp/jstl/sql" %>
<sql:setDataSource var="pooledDs" dataSource="jdbc/MallDB" scope="application" />

<%-- 2. 原型验证场景通过 JDBC 参数直接声明数据源(无连接池) --%>
<sql:setDataSource
    var="protoDs"
    driver="com.mysql.cj.jdbc.Driver"
    url="jdbc:mysql://localhost:3306/mall?useSSL=false&serverTimezone=Asia/Shanghai"
    user="root"
    password="secret"
    scope="session" />

性能注意:采用 driver、url、user、password 方式创建的底层实现类为无池化的简单包装器,每次执行查询或更新都会重新建立并关闭物理 TCP 连接,在高并发场景下存在严重性能瓶颈。

语句执行 ​

查询标签 <sql:query> 与更新标签 <sql:update> 均实现标准接口 SQLExecutionTag,共享参数收集、预编译执行与连接回收流程,区别仅在于 SQL 语句类型与返回值封装形式。

sql:query ​

<sql:query> 用于执行 SELECT 等返回结果集的查询语句,将结果封装为与数据库连接解耦的 javax.servlet.jsp.jstl.sql.Result 对象并存入 var 指定的变量(var 为必填项,scope 默认为 page),执行完毕后立即关闭底层 ResultSet 与 Statement,避免连接泄漏。

常用属性如下:

  • sql:待执行的 SQL 语句,也可直接写在标签体内部。
  • dataSource:显式指定数据源,若位于 <sql:transaction> 内则严禁单独指定。
  • startRow:跳过的起始行索引(从 0 开始),默认为 0。
  • maxRows:最多读入 Result 的记录行数,默认 -1 表示不限制(或沿用 SQL_MAX_ROWS 配置)。

在页面中通常通过 EL 直接访问 Result 的常用属性:rows(按列名映射的 SortedMap[],键名不区分大小写)、rowsByIndex(按列下标访问的 Object[][])、columnNames(列名数组)、rowCount(本次读入行数)与 limitedByMaxRows(布尔值,标识结果是否被 maxRows 截断)。

分页警示:startRow 与 maxRows 是在 JDBC 客户端游标层跳过或截断结果集,并不会自动改写为数据库原生的 LIMIT / OFFSET 语句。数据量较大时应直接在 SQL 中编写数据库方言分页条件。

sql:update ​

<sql:update> 用于执行 INSERT、UPDATE、DELETE 等写操作或无结果集的 DDL 语句。支持可选的 var 与 scope 属性,用于接收数据库返回的受影响行数(Integer 类型)。

jsp
<%-- 1. 执行查询并将 Result 结果集存入 page 作用域 --%>
<sql:query var="bookResult" dataSource="${pooledDs}" startRow="0" maxRows="20">
    SELECT id, title, price
        FROM books
        WHERE status = 'ON_SALE'
        ORDER BY id DESC
</sql:query>

<%-- 2. 遍历 Result.rows 输出记录行 --%>
<c:forEach var="row" items="${bookResult.rows}">
    <p><c:out value="${row.title}" /> - ${row.price}</p>
</c:forEach>

<%-- 3. 执行更新语句并通过 var 接收受影响行数 --%>
<sql:update var="affected" dataSource="${pooledDs}">
    UPDATE books
        SET status = 'ARCHIVED'
        WHERE stock = 0
</sql:update>

参数绑定 ​

在 <sql:query> 或 <sql:update> 标签体中直接拼接 ${param.xxx} 会导致严重的 SQL 注入漏洞。SQL 标签库要求在语句中使用标准 JDBC 占位符 ?,再通过嵌套参数标签按出现顺序依次绑定参数,底层统一使用 PreparedStatement 预编译执行。

sql:param ​

<sql:param> 必须嵌套在实现了 SQLExecutionTag 的标签内部使用,通过 value 属性(或标签体文本)将任意常见 Java 类型值绑定到对应的 ? 占位符。当 value 为 null 时,底层自动调用 PreparedStatement.setNull() 写入数据库空值。

sql:dateParam ​

JDBC 规范区分日期(java.sql.Date)、时间(java.sql.Time)与时间戳(java.sql.Timestamp),而 JSP 作用域中常见的时间对象多为 java.util.Date。<sql:dateParam> 专门负责将 java.util.Date 实例按 type 属性转换为精确的 SQL 时间类型后绑定:

  • timestamp(默认):转换为 java.sql.Timestamp,保留完整日期与时分秒。
  • date:转换为 java.sql.Date,仅保留年月日。
  • time:转换为 java.sql.Time,仅保留时分秒。
jsp
<%-- 1. 按占位符顺序依次绑定普通参数与时间戳参数,防范 SQL 注入 --%>
<sql:query var="orders" dataSource="${pooledDs}">
    SELECT order_no, total_amount, created_at
        FROM orders
        WHERE member_id = ?
            AND created_at >= ?
        ORDER BY created_at DESC
    <%-- 2. 使用 sql:param 与 sql:dateParam 映射 PreparedStatement 参数 --%>
    <sql:param value="${sessionScope.memberId}" />
    <sql:dateParam value="${startDate}" type="timestamp" />
</sql:query>

事务控制 ​

默认情况下,每条独立的 <sql:query> 与 <sql:update> 都会单独申请连接并在自动提交模式下执行。当多条 SQL 语句需要满足原子性要求时,必须通过事务标签将它们纳入同一个数据库连接与事务上下文。

sql:transaction ​

<sql:transaction> 将标签体内的所有嵌套 <sql:query> 与 <sql:update> 包裹在同一事务中,执行遵循以下生命周期规则:

  1. 开启事务:进入标签时从数据源获取单个 Connection,调用 setAutoCommit(false),并按可选的 isolation 属性设置事务隔离级别(支持 read_committed、read_uncommitted、repeatable_read、serializable)。

  2. 共享连接:嵌套的 SQL 子标签通过父标签引用直接复用该连接,因此子标签严禁再显式声明 dataSource 属性,否则容器会直接抛出 JspTagException。

  3. 提交或回滚:标签体正常结束时自动调用 commit();若执行期间抛出任何未捕获的 Throwable,容器拦截异常后立即调用 rollback() 并将原异常继续向外抛出,最后在 finally 阶段恢复连接状态并释放连接。

jsp
<%-- 1. 开启读已提交隔离级别事务,数据源统一声明在事务标签上 --%>
<sql:transaction dataSource="${pooledDs}" isolation="read_committed">
    <%-- 2. 扣减转出账户余额 --%>
    <sql:update>
        UPDATE accounts
            SET balance = balance - ?
            WHERE account_id = ?
        <sql:param value="${amount}" />
        <sql:param value="${fromId}" />
    </sql:update>

    <%-- 3. 增加转入账户余额,若此步抛出异常则整个事务自动回滚 --%>
    <sql:update>
        UPDATE accounts
            SET balance = balance + ?
            WHERE account_id = ?
        <sql:param value="${amount}" />
        <sql:param value="${toId}" />
    </sql:update>
</sql:transaction>

示例: 账户转账 ​

以下示例结合 <sql:transaction>、<sql:update>、<sql:query>、<c:catch> 与 <fmt:formatNumber>,演示原子转账、异常回滚降级提示以及余额列表渲染的完整流程:

jsp
<%-- 1. 声明页面编码并引入 Core、Formatting 与 SQL 标签库 --%>
<%@ page contentType="text/html;charset=UTF-8" language="java" %>
<%@ taglib prefix="c" uri="http://java.sun.com/jsp/jstl/core" %>
<%@ taglib prefix="fmt" uri="http://java.sun.com/jsp/jstl/fmt" %>
<%@ taglib prefix="sql" uri="http://java.sun.com/jsp/jstl/sql" %>

<%-- 2. 绑定应用级数据源(假定已由容器 JNDI 管理连接池) --%>
<sql:setDataSource var="bankDs" dataSource="jdbc/BankDB" scope="application" />

<%-- 3. 使用 c:catch 捕获事务异常,保证页面正常输出提示 --%>
<c:catch var="txError">
    <sql:transaction dataSource="${bankDs}" isolation="read_committed">
        <sql:update>
            UPDATE accounts
                SET balance = balance - ?
                WHERE account_id = ?
            <sql:param value="${param.amount}" />
            <sql:param value="${param.fromId}" />
        </sql:update>

        <sql:update>
            UPDATE accounts
                SET balance = balance + ?
                WHERE account_id = ?
            <sql:param value="${param.amount}" />
            <sql:param value="${param.toId}" />
        </sql:update>
    </sql:transaction>
</c:catch>

<%-- 4. 依据异常状态展示执行结果 --%>
<c:choose>
    <c:when test="${not empty txError}">
        <p>转账失败,事务已回滚:<c:out value="${txError.message}" /></p>
    </c:when>
    <c:otherwise>
        <p>转账成功</p>
    </c:otherwise>
</c:choose>

<%-- 5. 查询账户最新余额并格式化展示 --%>
<sql:query var="accountRes" dataSource="${bankDs}" maxRows="10">
    SELECT account_id, holder_name, balance
        FROM accounts
        ORDER BY account_id ASC
</sql:query>

<table>
    <tbody>
        <c:forEach var="acc" items="${accountRes.rows}">
            <tr>
                <td><c:out value="${acc.holder_name}" /></td>
                <td><fmt:formatNumber value="${acc.balance}" type="currency" /></td>
            </tr>
        </c:forEach>
    </tbody>
</table>

API: Config【待补充】 ​

API: Result【待补充】 ​

API: SQLExecutionTag【待补充】 ​

JSTL 标签编译执行 ​

JSTL 标签并不是由浏览器解析的特殊标记,而是严格运行在 JSP 容器(如 Tomcat 的 Jasper 引擎)内部的 Java 组件。从页面中的 <c:forEach> 到最终输出到客户端的纯 HTML,容器在启动扫描、JSP 转译、字节码编译与请求执行四个阶段完成了从 XML 声明到 Java 方法调用的完整转换。

TLD 扫描与解析 ​

JSP 容器识别 JSTL 标签的前提是建立“标签库 URI → 标签描述文件(TLD)”的全局映射。以 Tomcat 为例,Web 应用启动时 JasperInitializer 会触发 TldScanner 自动扫描 WEB-INF/ 目录以及 WEB-INF/lib/ 下所有 JAR 包中的 META-INF/*.tld 文件(例如 taglibs-standard-impl 内置的 c.tld、fmt.tld、fn.tld 等)。

当容器解析 JSP 页面顶部的 <%@ taglib prefix="c" uri="[http://java.sun.com/jsp/jstl/core](http://java.sun.com/jsp/jstl/core)" %> 指令时,不会发起任何网络请求,而是直接按 uri 命中已缓存的 TLD 元数据,提取以下关键契约:

  • 标签映射(<tag>):声明标签名、对应的处理器全限定类名、标签体内容类型(JSP、empty 或 tagdependent)以及每个属性是否必填、是否允许接收运行期 EL 表达式(<rtexprvalue>)。
  • 函数映射(<function>):仅供 Functions 库使用,声明 EL 函数名到 public static 工具方法的签名映射。
  • 转译期校验器(<validator>):声明实现 TagLibraryValidator 的校验类,在页面编译前检查标签嵌套结构的合法性。
xml
<!-- 1. 声明 Core 标签库中的 if 标签元数据 -->
<tag>
    <name>if</name>
    <!-- 2. 绑定具体标签处理器实现类 -->
    <tag-class>org.apache.taglibs.standard.tag.rt.core.IfTag</tag-class>
    <body-content>JSP</body-content>

    <attribute>
        <!-- 3. 声明 test 属性必填且允许运行期 EL 表达式求值 -->
        <name>test</name>
        <required>true</required>
        <rtexprvalue>true</rtexprvalue>
        <!-- 4. 指定属性目标类型为布尔值 -->
        <type>boolean</type>
    </attribute>
</tag>

JSP 转译代码结构 ​

首次访问或预编译 JSP 页面时,Jasper 引擎会将页面转译为继承自 HttpJspBase 的标准 Servlet 源码(*_jsp.java),再交由 Java 编译器生成 .class 文件。

页面中每出现一次 JSTL 标签调用,Jasper 都会生成一个独立的私有辅助方法(如 _jspx_meth_c_005fforEach_005f0),并按以下结构织入对象获取、属性注入、回调流转与异常清理代码:

java
// 1. 从 TagHandlerPool 获取可复用的 ForEachTag 实例
ForEachTag tag = (ForEachTag) pool.get(ForEachTag.class);
boolean reused = false;

// 2. 注入页面上下文、父标签及通过 EL 求值后的标签属性
try {
  tag.setPageContext(pageContext);
  tag.setParent(null);
  tag.setVar("item");
  tag.setItems(evaluateItems(pageContext));

  // 3. 触发开始标签回调,决定是否进入循环体
  int startFlag = tag.doStartTag();
  if (startFlag != Tag.SKIP_BODY) {
    do {
      out.write("<li>");
      // 4. 渲染循环体内容并检查是否继续下一轮迭代
      renderBody(pageContext, out);
      out.write("</li>");
    } while (tag.doAfterBody() == BodyTag.EVAL_BODY_AGAIN);
  }

  if (tag.doEndTag() == Tag.SKIP_PAGE) {
    return true;
  }
  pool.reuse(tag);
  reused = true;
} catch (Throwable ex) {
  // 5. 实现 TryCatchFinally 的标签可在此拦截并处理异常
  tag.doCatch(ex);
} finally {
  // 6. 无论是否异常,均清理循环变量并在未复用时销毁标签
  tag.doFinally();
  if (!reused) {
    tag.release();
  }
}

从生成代码可以看出,JSTL 本质上并没有改变 JSP 最终作为 Servlet 执行的模型,只是把开发者手工编写的 if、for、try/catch/finally 控制流下沉到了标准化的转译模板与标签处理器基类中。

经典标签生命周期 ​

尽管 JSP 2.0 引入了轻量级的 SimpleTag 接口,但 JSTL 1.2(Apache Standard Taglib)及 Jakarta JSTL 的核心处理器大多沿用了经典标签(Classic Tag)体系,核心接口位于 javax.servlet.jsp.tagext(Jakarta EE 中为 jakarta.servlet.jsp.tagext),主要包括 Tag、IterationTag、BodyTag 与 TryCatchFinally。

单次标签调用严格遵循以下生命周期流转:

  1. 上下文与属性绑定:容器依次调用 setPageContext、setParent 绑定运行环境与嵌套父标签(例如 <c:param> 通过父标签引用向 <c:url> 注册参数),随后调用各个属性对应的 Setter 方法注入求值后的属性。

  2. 起始判定(doStartTag):标签执行前置准备并返回控制常量。返回 SKIP_BODY 时直接跳过标签体(如 <c:if> 条件为 false 或 <c:forEach> 集合为空);返回 EVAL_BODY_INCLUDE 时直接向当前输出流渲染标签体;实现 BodyTag 的标签还可返回 EVAL_BODY_BUFFERED,由容器分配 BodyContent 缓冲区捕获标签体文本(如 <c:set> 通过标签体赋值)。

  3. 迭代控制(doAfterBody):实现 IterationTag 的标签(如继承自 LoopTagSupport 的 <c:forEach>、<c:forTokens>)在每次标签体执行结束后触发此回调。返回 EVAL_BODY_AGAIN 时循环执行下一轮;返回 SKIP_BODY 时退出循环。

  4. 结束判定(doEndTag):执行标签收尾逻辑。绝大多数标签返回 EVAL_PAGE 继续渲染页面剩余内容;<c:redirect> 在触发 302 重定向后返回 SKIP_PAGE,通知容器立即终止当前 JSP 的后续输出。

  5. 异常拦截与资源回收(TryCatchFinally):当标签体或生命周期方法抛出异常时,容器回调 doCatch(Throwable);无论是否发生异常,最终必定执行 doFinally()。

image-20261119114759421

TryCatchFinally 是 JSTL 实现健壮性的核心支撑:

  • LoopTagSupport:在 doFinally() 中无条件清理或恢复 page 作用域中的 var 与 varStatus 变量,防止循环体中途抛出异常导致作用域残留脏数据。
  • CatchTag:在 doCatch() 中吞掉异常并将其存入 page 作用域的 var 属性,实现页面局部降级。
  • TransactionTag:在 doCatch() 中触发数据库事务回滚,并在 doFinally() 中恢复连接自动提交状态并归还连接池。

TagHandlerPool ​

高并发页面中每个循环或列表渲染都可能触发成百上千次标签调用。为避免频繁创建与垃圾回收大量经典标签处理器对象,Tomcat Jasper 引擎默认启用了基于 TagHandlerPool 的对象池复用机制。

池化隔离维度 ​

Jasper 在编译阶段会为当前 JSP 中每种不同的“标签实现类 + 传入属性名集合”组合分配一个独立的 TagHandlerPool 成员变量(例如仅传 value 的 <c:out> 与同时传 value 和 default 的 <c:out> 各自使用不同的对象池)。这种按属性签名分池的策略保证了同一池中复用的实例每次都会被新调用重新覆盖完全相同的属性集合,避免上一次请求设置的可选属性残留到下一次调用中。

reuse 与 release 边界 ​

TagHandlerPool 内部维护定长数组(默认最大容量 MAX_POOL_SIZE 为 5),标签实例的归还与销毁遵循明确边界:

  1. 标签体与 doEndTag() 正常完成且未发生未捕获异常时,容器调用 pool.reuse(tag) 将实例放回数组;若当前池已满,容器立即调用 tag.release() 丢弃该实例。

  2. 标签执行期间一旦抛出未捕获异常,该实例不再放回对象池,容器在 finally 块中直接调用 tag.release() 销毁。

  3. 留在池中的活跃实例在后续请求中被反复 get 与 reuse,直到整个 JSP Servlet 被容器卸载执行 _jspDestroy() 时,才统一触发 pool.release() 调用所有池内标签的 release() 方法。

image-20261119114859104

关键误区:release() 并不会在每次标签执行结束后被调用。因此无论是理解 JSTL 源码还是编写自定义经典标签,所有单次调用产生的临时状态清理都必须放在 doFinally() 中完成,严禁依赖 release() 重置请求级状态。

编译期校验与性能调优 ​

理解 JSTL 的编译期校验机制与运行期渲染开销,有助于在开发期提前暴露结构错误并在生产环境保持稳定的吞吐性能。

TagLibraryValidator ​

JSTL 规范为各标签库内置了 TagLibraryValidator 实现(如 JstlCoreTLV、JstlFmtTLV、JstlSqlTLV 与 JstlXmlTLV)。在 JSP 转译为 Java 源码之前,容器会将整个页面转换为标准 XML 视图(PageData)并交给对应校验器执行静态结构检查。

诸如 <c:when> 未嵌套在 <c:choose> 内、<c:otherwise> 写在 <c:when> 之前、<c:set> 同时指定 var 与 target、或者 scope 传入非法作用域名称等错误,均会在编译阶段直接报错中断,而不会潜伏到线上运行期才暴露。

渲染性能调优 ​

在维护包含复杂 JSTL 页面的高并发 Web 应用时,可重点关注以下三项工程配置:

  1. 开启空白字符裁剪:多层嵌套的 <c:if>、<c:choose> 与 <c:forEach> 会在最终输出的 HTML 源码中留下大量空行与缩进空格,既增加响应体积又影响网络传输。在页面指令或 web.xml 的 <jsp-property-group> 中开启 trimDirectiveWhitespaces="true",可在转译期自动剥离标签指令间的纯空白模板文本。

  2. 避免循环内重复求值:在迭代次数较多的 <c:forEach> 内部,应将跨轮次不变的深层对象属性访问或 fn 函数计算提取到循环外,通过 <c:set> 缓存在 page 作用域中。

  3. 合理配置生产期 Jasper 参数:确保 Tomcat conf/web.xml 中 JspServlet 的 development 为 false(关闭每次请求对 JSP 文件修改时间戳的轮询检查),并保持 enablePooling 为 true 以发挥 TagHandlerPool 的对象复用优势。

jsp
<%-- 1. 启用指令与标签空白裁剪,压缩嵌套 JSTL 产生的冗余空行 --%>
<%@ page contentType="text/html;charset=UTF-8" trimDirectiveWhitespaces="true" %>
<%@ taglib prefix="c" uri="http://java.sun.com/jsp/jstl/core" %>

<%-- 2. 在循环外部缓存重复使用的复杂表达式结果 --%>
<c:set var="discount" value="${sessionScope.member.level.discountRate}" />
<c:forEach var="item" items="${cart.items}">
    <p><c:out value="${item.name}" />:${item.price * discount}</p>
</c:forEach>
xml
<!-- 1. Tomcat conf/web.xml 中 Jasper 引擎核心运行参数 -->
<servlet>
    <servlet-name>jsp</servlet-name>
    <servlet-class>org.apache.jasper.servlet.JspServlet</servlet-class>
    <!-- 2. 启用标签处理器对象池复用(默认 true) -->
    <init-param>
        <param-name>enablePooling</param-name>
        <param-value>true</param-value>
    </init-param>

    <!-- 3. 生产环境关闭开发模式,避免每次请求检查 JSP 文件修改时间戳 -->
    <init-param>
        <param-name>development</param-name>
        <param-value>false</param-value>
    </init-param>
</servlet>

API: ConditionalTagSupport【待补充】 ​

API: LoopTagSupport【待补充】 ​