开发

相关源文件

• .github/pull_request_template.md
• .github/scripts/check_language_properties.py
• .github/workflows/build.yml
• .github/workflows/check_properties.yml
• .github/workflows/dependency-review.yml
• .github/workflows/licenses-update.yml
• .github/workflows/pre_commit.yml
• .github/workflows/sync_files.yml
• CONTRIBUTING.md
• DATABASE.md
• DeveloperGuide.md
• HowToAddNewLanguage.md
• HowToUseOCR.md
• src/main/java/stirling/software/SPDF/config/EndpointConfiguration.java
• src/main/java/stirling/software/SPDF/controller/web/SecurityWebController.java

本页面为希望为Stirling-PDF做出贡献或扩展其功能的开发人员提供了全面的信息。它涵盖了构建过程、开发工作流、CI/CD管道以及添加新功能的指南。有关部署选项的信息，请参阅部署。

从源代码构建

本节介绍如何使用Gradle从源代码构建Stirling-PDF并设置开发环境。

先决条件

• Git
• Java JDK 17或更高版本
• Docker（用于全面测试）
• Java IDE（推荐Eclipse、IntelliJ或VSCode）

克隆和构建过程

1. 克隆仓库

2. 使用Gradle构建项目

3. 要启用安全功能进行构建，请设置环境变量

开发环境设置

为了高效的开发环境

1. 在您的IDE中安装Lombok，以处理代码库中使用的注释
2. 添加环境变量DOCKER_ENABLE_SECURITY=true以进行安全功能测试
3. 配置您的IDE使用Java 17或更高版本

来源：DeveloperGuide.md33-56 .github/workflows/build.yml34-48

开发工作流

项目结构

来源：DeveloperGuide.md60-103

端点配置系统

该EndpointConfiguration类管理应用程序中启用或禁用的功能。端点根据功能分为不同的组。

来源：src/main/java/stirling/software/SPDF/config/EndpointConfiguration.java20-304

CI/CD 流水线

本节介绍Stirling-PDF使用的持续集成和持续部署（CI/CD）管道。

CI/CD工作流图

关键工作流程

1. 构建工作流（build.yml）：使用不同的JDK版本（17、21）和安全配置构建和测试项目。

2. 许可证更新工作流（licenses-update.yml）：自动检查和更新第三方许可证信息，如果检测到更改则创建一个PR。

3. 文件同步工作流（sync_files.yml）：同步翻译文件并使用翻译进度更新README。

4. 预提交工作流（pre_commit.yml）：运行预提交钩子以确保代码质量，并创建包含任何结果更改的PR。

5. 属性检查工作流（check_properties.yml）：验证PR中的语言属性文件以确保一致性。

来源：.github/workflows/build.yml1-60 .github/workflows/licenses-update.yml1-93 .github/workflows/sync_files.yml1-146 .github/workflows/pre_commit.yml1-81 .github/workflows/check_properties.yml1-251

第三方库和依赖项

Stirling-PDF依赖于多个第三方库和工具来提供其功能

类别	依赖项
核心框架	Spring Boot, Spring Security
PDF 处理	Apache PDFBox, PDF.js
文件转换	LibreOffice, Weasyprint
OCR	Tesseract OCR
UI	Bootstrap, jQuery, PDF-Lib.js
构建工具	Gradle, Docker
质量工具	QPDF

许可证合规性

项目使用自定义Gradle任务自动检查许可证兼容性

所有依赖项的许可证信息都保存在src/main/resources/static/3rdPartyLicenses.json中，并由CI/CD管道自动更新。

来源：.github/workflows/licenses-update.yml43-54

基于 Docker 的开发

Stirling-PDF为开发和测试提供了几种Docker配置

• 常规：包含大多数功能的标准镜像
• 超精简版：最小镜像，不包含外部工具的依赖项
• 完整版：包含所有预装依赖项的完整镜像

构建 Docker 镜像

来源：DeveloperGuide.md167-200

添加新功能

本节提供了有关如何为Stirling-PDF添加新功能的指南。

添加新的API端点

示例控制器

来源：DeveloperGuide.md385-410

添加新的UI页面

示例Web控制器

示例Thymeleaf模板结构

来源：DeveloperGuide.md462-506 src/main/java/stirling/software/SPDF/controller/web/SecurityWebController.java1-90

国际化

添加新功能时，请更新语言属性文件以支持国际化

1. 将新字符串添加到src/main/resources/messages_en_GB.properties（参考文件）
2. 在您的Thymeleaf模板中使用#{key}语法，通过翻译键进行引用

CI/CD管道包含用于检查语言文件一致性和跟踪翻译进度的流程。

来源：HowToAddNewLanguage.md32-68 .github/scripts/check_language_properties.py174-178

测试

Stirling-PDF结合了手动测试和自动化测试。

测试工作流程

来源：DeveloperGuide.md204-259 .github/workflows/build.yml90-146

运行测试

用于本地测试

用于全面测试，包括Docker构建

该test.sh脚本执行以下操作

1. 构建所有Docker镜像（常规、超精简版、完整版）
2. 运行每个镜像，确保它能正确启动
3. 针对主版本执行Cucumber测试

来源：DeveloperGuide.md204-223

贡献指南

要为Stirling-PDF做出贡献

1. Fork 存储库
2. 为您的功能或错误修复创建一个分支
3. 按照编码标准进行更改
4. 彻底测试您的更改
5. 使用提供的PR模板提交拉取请求

拉取请求模板包含一个清单，以确保在提交前满足所有要求，包括

• 阅读贡献指南
• 对代码进行自我审查
• 更新相关文档
• 在本地测试更改

来源： CONTRIBUTING.md1-45 .github/pull_request_template.md1-35