如何在 Java Servlet 中动态渲染 HTML 模板文件_技术教程

本文介绍如何使用原生 java servlet 读取 `.tpl` 模板文件，解析占位符（如 `{pet.name}`），注入真实数据后返回渲染后的 html 响应，无需第三方模板引擎。

要实现基于 .tpl 文件的轻量级模板渲染，核心思路是：Servlet 接收请求 → 定位并读取模板文件 → 提取参数（如 id）→ 查询业务对象（如 Pet）→ 替换模板中的占位符 → 输出 HTML 响应。整个过程不依赖 Thymeleaf、Freemarker 等框架，适合学习 Servlet 基础机制或构建极简服务。

✅ 正确实现步骤（含关键修复与最佳实践）

首先，注意原始示例代码中存在两处关键问题：

request.getParameterByName("id") 方法不存在（应为 getParameter("id")）；
占位符替换逻辑缺失（需手动实现或使用 String.replace() 安全替换）；
缺少 MIME 类型设置和异常处理，易导致浏览器解析失败或 500 错误。

以下是生产就绪的 doGet() 实现示例：

@WebServlet("/index.tpl")
public class TemplateServlet extends HttpServlet {
    private static final String BASE_PATH = "/WEB-INF/templates"; // 推荐将模板放在 WEB-INF 下，禁止直接 HTTP 访问

    @Override
    protected void doGet(HttpServletRequest request, HttpServletResponse response)
            throws ServletException, IOException {

        // 1. 解析请求路径（如 /index.tpl → 模板名）
        String pathInfo = request.getPathInfo(); // 注意：若映射为 /index.tpl，则 getPathInfo() 可能为 null
        String templateName = "index.tpl";
        if (pathInfo != null && !pathInfo.trim().isEmpty()) {
            templateName = pathInfo.substring(1); // 去除开头 '/'，如 "/index.tpl" → "index.tpl"
        }

        // 2. 构建安全文件路径（防止路径遍历攻击）
        String filePath = getServletContext().getRealPath(BASE_PATH + "/" + templateName);
        if (filePath == null || !filePath.startsWith(getServletContext().getRealPath(BASE_PATH))) {
            response.sendError(HttpServletResponse.SC_NOT_FOUND, "Template not accessible");
            return;
        }

        // 3. 读取模板内容
        String templateContent;
        try {
            templateContent = Files.readString(Paths.get(filePath), StandardCharsets.UTF_8);
        } catch (IOException e) {
            throw new ServletException("Failed to read template: " + templateName, e);
        }

        // 4. 获取参数并加载数据
        String idParam = request.getParameter("id");
        if (idParam == null || idParam.trim().isEmpty()) {
            response.sendError(HttpServletResponse.SC_BAD_REQUEST, "Missing 'id' parameter");
            return;
        }
        Long petId;
        try {
            petId = Long.parseLong(idParam.trim());
        } catch (NumberFormatException e) {
            response.sendError(HttpServletResponse.SC_BAD_REQUEST, "'id' must be a number");
            return;
        }

        Pet pet = loadPetById(petId); // 你的数据访问逻辑（例如 JDBC / JPA）
        if (pet == null) {
            response.sendError(HttpServletResponse.SC_NOT_FOUND, "Pet not found with id: " + petId);
            return;
        }

        // 5. 安全替换占位符（推荐使用正则避免误替换，如 {pet.name} ≠ {pet.named}）
        String rendered = templateContent
                .replace("{pet.name}", escapeHtml(pet.getName()))
                .replace("{pet.age}", String.valueOf(pet.getAge()))
                // 可扩展其他字段...
                ;

        // 6. 设置响应头并输出
        response.setContentType("text/html;charset=UTF-8");
        response.setStatus(HttpServletResponse.SC_OK);
        response.getWriter().write(rendered);
        response.getWriter().flush();
    }

    // 示例数据加载方法（请按实际实现）
    private Pet loadPetById(Long id) {
        // 示例：返回模拟宠物对象
        return new Pet("Buddy", 3L);
    }

    // 简单 HTML 转义（防御 XSS，生产环境建议用 OWASP Java Encoder）
    private String escapeHtml(String input) {
        if (input == null) return "";
        return input.replace("&", "&")
                    .replace("<", "zuojiankuohaophpcn")
                    .replace(">", "youjiankuohaophpcn")
                    .replace("\"", """)
                    .replace("'", "'");
    }
}

⚠️ 重要注意事项

安全性优先：
- 模板文件必须存放于 WEB-INF/templates/ 等受保护目录，避免用户通过 URL 直接下载源码；
- 务必对动态插入的变量进行 HTML 转义（如上例 escapeHtml()），否则将导致 XSS 漏洞；
- 对 id 等路径/参数做严格校验（类型、范围、非空），防止注入或空指针。
编码一致性：使用 StandardCharsets.UTF_8 显式指定读写编码，避免中文乱码。
可维护性增强建议：
- 将占位符替换逻辑封装为通用工具类（支持嵌套语法如 {user.profile.name}）；
- 使用 Map 统一传入模型，配合反射或表达式引擎（如 JEXL）提升灵活性；
- 后续可平滑迁移到标准模板引擎（如 Thymeleaf 的 @Controller + Model 方式），保持架构演进空间。