一、接口概述
在实际业务开发中，我们经常遇到将 HTML 内容转换为 PDF 文件的需求，比如生成合同、报告、证书等文档。本文介绍一个基于 Spring Boot 实现的 HTML 转 PDF 接口，支持动态渲HTML 并生成 PDF 文件供用户下载。
二、接口定义
@RequestMapping(value = "/rest/api/convertHtmlToPdf", method = RequestMethod.GET) public void convertHtmlToPdfTwo(HttpServletResponse httpResponse) { // ... }
三、核心实现代码
@RequestMapping(value = "/rest/api/convertHtmlToPdf", method = RequestMethod.GET) public void convertHtmlToPdf(HttpServletResponse httpResponse) { try { // 1. 渲染 HTML 模板 String htmlContent = service.buildConvertHtml(); // 2. 校验 HTML 内容 if (htmlContent == null || htmlContent.trim().isEmpty()) { httpResponse.setStatus(HttpServletResponse.SC_NOT_FOUND); httpResponse.setContentType("application/json;charset=UTF-8"); httpResponse.getWriter().write("{\"code\":404,\"msg\":\"未找到HTML内容\"}"); return; } // 3. 生成 PDF HtmlConvertToPdfUtils.generatePdf(htmlContent, httpResponse); } catch (Exception e) { try { httpResponse.setStatus(HttpServletResponse.SC_INTERNAL_SERVER_ERROR); httpResponse.setContentType("application/json;charset=UTF-8"); httpResponse.getWriter().write("{\"code\":500,\"msg\":\"PDF生成失败: " + e.getMessage() + "\"}"); } catch (Exception ignored) { httpResponse.setStatus(HttpServletResponse.SC_INTERNAL_SERVER_ERROR); } } }四、响应说明
4.1 成功响应
┌──────────────┬──────────────────┐
│ 项目 │ 说明 │
├──────────────┼──────────────────┤
│ HTTP 状态码 │ 200 OK │
├──────────────┼──────────────────┤
│ Content-Type │ application/pdf │
├──────────────┼──────────────────┤
│ 响应体 │ PDF 文件二进制流 │
└──────────────┴──────────────────┘
浏览器会根据设置自动下载或在浏览器中直接预览 PDF 文件。
五、关键技术点
5.1 直接输出流到 Response
该接口没有返回值（void），而是直接操作 HttpServletResponse 输出 PDF 流：
HtmlConvertToPdfUtils.generatePdf(htmlContent, httpResponse);
这种方式的优点：
- 减少内存占用：不需要在内存中先构建完整的 PDF 字节数组
- 响应更快：边生成边输出，用户体验更好
- 适合大文件：避免了 OutOfMemoryError 风险，支持自定义文件名
response.setHeader("Content-Disposition", "attachment; filename=" + URLEncoder.encode(fileName, "UTF-8") + ".pdf");六、总结
1. 动态渲染：根据业务数据和模板动态生成 HTML
2. 流式输出：直接输出到 Response，内存友好
3. 完善的异常处理：多层保护，确保用户收到明确的错误信息
4. RESTful 风格：GET 请求，参数清晰，便于浏览器直接访问
这种实现方式在企业级应用中非常实用，特别适合合同、报告、证书等文档的在线生成与下载场景。
相关技术栈：Spring Boot、iText / Flying Saucer、Thymeleaf / FreeMarker
