架构

相关源文件

• build.gradle
• src/main/java/stirling/software/SPDF/controller/api/RearrangePagesPDFController.java
• src/main/java/stirling/software/SPDF/controller/api/SplitPDFController.java
• src/main/java/stirling/software/SPDF/controller/api/converters/ConvertImgPDFController.java
• src/main/java/stirling/software/SPDF/controller/web/GeneralWebController.java
• src/main/java/stirling/software/SPDF/controller/web/OtherWebController.java
• src/main/java/stirling/software/SPDF/utils/PdfUtils.java
• src/main/resources/messages_en_GB.properties
• src/main/resources/messages_en_US.properties
• src/main/resources/templates/fragments/navbar.html
• src/main/resources/templates/home.html

本文档全面概述了 Stirling PDF 的架构，阐述了系统的关键组件、它们之间的关系以及驱动应用程序的整体设计模式。有关核心组件的具体实现细节，请参阅核心组件。

系统分层

Stirling PDF 遵循分层架构模式，将功能组织成具有明确职责的不同层。这种设计促进了关注点分离、可维护性和可测试性，同时为广泛的功能集提供了灵活的基础。

来源

• build.gradle1-59
• src/main/java/stirling/software/SPDF/utils/PdfUtils.java1-50
• src/main/java/stirling/software/SPDF/controller/web/GeneralWebController.java1-50
• src/main/java/stirling/software/SPDF/controller/api/converters/ConvertImgPDFController.java1-50

请求处理流程

下图说明了请求如何通过 Stirling PDF 系统流动，从用户交互到 PDF 处理和响应生成。

来源

• src/main/java/stirling/software/SPDF/controller/web/GeneralWebController.java50-100
• src/main/java/stirling/software/SPDF/controller/api/converters/ConvertImgPDFController.java50-100
• src/main/java/stirling/software/SPDF/utils/PdfUtils.java100-150

关键组件

控制器

Stirling PDF 基于 Spring MVC 架构构建，包含两种类型的控制器

1. Web 控制器 - 处理 HTTP 请求并返回 HTML 视图

   • GeneralWebController - 管理 PDF 合并、拆分和组织等通用 PDF 操作
   • OtherWebController - 处理压缩、OCR 和元数据更改等专业操作

2. API 控制器 - 提供返回 JSON 或二进制数据的 RESTful 端点

   • ConvertImgPDFController - PDF 与图像之间的转换
   • RearrangePagesPDFController - 管理页面删除和重排等页面操作
   • SplitPDFController - 处理 PDF 拆分操作

来源

• src/main/java/stirling/software/SPDF/controller/web/GeneralWebController.java1-346
• src/main/java/stirling/software/SPDF/controller/web/OtherWebController.java1-189
• src/main/java/stirling/software/SPDF/controller/api/converters/ConvertImgPDFController.java1-284
• src/main/java/stirling/software/SPDF/controller/api/RearrangePagesPDFController.java1-300
• src/main/java/stirling/software/SPDF/controller/api/SplitPDFController.java1-168

PDF 处理实用工具

Stirling PDF 的核心功能在工具类中实现，提供 PDF 操作功能

PdfUtils 类是应用程序 PDF 操作的核心，提供以下方法的支持：

• PDF 与图像之间的转换
• 检测 PDF 中的文本和图像
• 操作 PDF 页面和内容
• 处理 PDF 元数据

来源

• src/main/java/stirling/software/SPDF/utils/PdfUtils.java1-445

网页界面

Web 界面采用 Thymeleaf 模板、Bootstrap 进行样式设计，并使用 JavaScript 实现客户端功能

Web 界面包括

• 带有工具类别和设置的导航栏
• 主页，包含搜索和功能磁贴
• 用于各种 PDF 操作的功能专用页面
• 多语言国际化支持

来源

• src/main/resources/templates/fragments/navbar.html1-283
• src/main/resources/templates/home.html1-227
• src/main/resources/messages_en_GB.properties1-100
• src/main/resources/messages_en_US.properties1-100

PDF 处理架构

Stirling PDF 的 PDF 处理能力按操作类型进行组织，每组操作都作为独立的控制器和实用方法实现

每种操作类型都利用 PdfUtils 类中的专用实用方法，并可能通过 ProcessExecutor 调用不支持 PDFBox 的外部工具。

来源

• src/main/java/stirling/software/SPDF/controller/api/RearrangePagesPDFController.java1-300
• src/main/java/stirling/software/SPDF/controller/api/SplitPDFController.java1-168
• src/main/java/stirling/software/SPDF/controller/api/converters/ConvertImgPDFController.java1-284
• src/main/java/stirling/software/SPDF/utils/PdfUtils.java1-445

构建和部署架构

Stirling PDF 支持多种部署方法，包括 Docker 容器、JAR 文件和特定于平台的安装程序

构建系统 (Gradle) 配置为生成不同的部署工件

• JAR 包 - 标准 Java 应用程序
• 特定于平台的安装程序 - Windows EXE, macOS DMG, Linux DEB
• Docker 镜像 - 具有不同功能集的多个变体

来源

• build.gradle1-100
• build.gradle100-200
• build.gradle200-300

安全架构

Stirling PDF 包含一个可选的安全系统，可在部署期间启用或禁用

安全系统是模块化的，可以完全从构建中排除，以支持不需要身份验证的环境。这由构建配置中的 DOCKER_ENABLE_SECURITY 环境变量控制。

来源

• build.gradle50-100

国际化系统

Stirling PDF 通过消息解析系统提供广泛的国际化支持

国际化系统使用属性文件进行消息定义，并与 Thymeleaf 模板集成，使用消息键。该系统目前支持超过 39 种语言。

来源

• src/main/resources/messages_en_GB.properties1-100
• src/main/resources/messages_en_US.properties1-100
• src/main/resources/templates/fragments/navbar.html1-50

关键技术实现细节

PDF 处理工作流程

Stirling PDF 中的 PDF 处理通常遵循以下步骤

1. 控制器接收包含文件输入和操作参数的请求
2. 使用 CustomPDFDocumentFactory 加载文件
3. PdfUtils 中的相应实用方法处理文档
4. 对于复杂操作，可能通过 ProcessExecutor 调用外部工具
5. 将处理后的文档返回给客户端

这种模式使得在各种 PDF 操作中都能保持一致的处理，同时允许进行特定于操作的自定义。

外部工具集成

Stirling PDF 利用了多种外部工具来执行 PDFBox 之外的功能

工具	目的	集成方法
LibreOffice	Office 格式转换	进程执行
Tesseract OCR	图像文本识别	进程执行
QPDF	高级 PDF 操作	进程执行
Weasyprint	HTML/Markdown 转 PDF	进程执行

ProcessExecutor 类提供了一种标准化的方式来调用这些工具并捕获其输出，从而实现与应用程序其余部分的无缝集成。

特定于平台的特性

Stirling PDF 包含用于不同部署环境的专用组件

• 桌面 UI 集成 (由 STIRLING_PDF_DESKTOP_UI 环境变量控制)
• 安全特性 (由 DOCKER_ENABLE_SECURITY 环境变量控制)
• WebP 图像支持 (需要带 OpenCV 的 Python)

这些特性可以在构建时启用或禁用，以针对每个环境创建适当的部署工件。