在 Devin 中试用 DeepWiki 处理私有仓库
DeepWiki

Stirling-Tools/Stirling-PDF

菜单

添加新功能

相关源文件

本文档为希望向 Stirling-PDF 添加新功能的开发人员提供了全面的指南。它涵盖了系统架构、实现新功能的过程以及为项目贡献的最佳实践。

理解架构

在向 Stirling-PDF 添加新功能之前，了解应用程序的整体架构非常重要

来源

其架构包括：

  1. 用户界面层：用于 Web 界面的 Thymeleaf 模板、JavaScript 和 CSS
  2. 控制器层：用于处理 HTTP 请求的 Web 控制器和用于 REST 端点的 API 控制器
  3. 服务层：用于 PDF 操作的业务逻辑和工具类
  4. 外部集成：与外部工具集成以进行高级 PDF 操作

功能实现工作流

向 Stirling-PDF 添加新功能的过程通常遵循以下步骤

来源

让我们详细探讨每个步骤。

1. 注册您的功能

Stirling-PDF 中的每个功能都必须在 EndpointConfiguration 类中注册。这至关重要，因为它允许应用程序通过配置启用或禁用功能。

功能按以下组别组织，例如：

  • "PageOps" - 用于页面操作功能（旋转、拆分、合并等）
  • "Convert" - 用于转换功能（PDF 转图像、图像转 PDF 等）
  • "Security" - 用于安全相关功能（密码保护、密文删除等）
  • "Other" - 用于其他杂项功能

为您的功能选择合适的组，如果它不属于现有类别，则将其添加到“Other”中。

来源

2. 创建模型、控制器和服务

2.1 模型类

模型类定义了您的功能所使用的数据结构。例如，一个请求模型

2.2 API 控制器

API 控制器处理 HTTP 请求并返回响应。它应该使用 @RestController 进行注解，并包含详细的 API 文档

来源

2.3 Web 控制器

Web 控制器使用 Thymeleaf 模板渲染用户界面

来源

2.4 实现核心功能

您的功能的核心功能应在工具类或服务中实现。对于 PDF 操作，您通常会向 PdfUtils 类添加方法

来源

3. 创建用户界面

3.1 Thymeleaf 模板

为您的功能的用户界面创建一个 Thymeleaf 模板

3.2 JavaScript（如果需要）

如果您的功能需要客户端交互，请在 static/js/ 目录中的单独文件中添加 JavaScript 代码，并在您的模板中引用它。

4. 添加翻译

将您的功能的翻译键添加到消息属性文件中

来源

5. 测试您的功能

在提交您的功能之前，请对其进行彻底测试

  1. 使用有效输入进行测试，以确保其按预期工作
  2. 使用无效输入进行测试，以确保正确的错误处理
  3. 测试边缘情况（大文件、不寻常的文件名等）
  4. 在启用安全功能的情况下进行测试（如果适用）

示例：实现图像转 PDF 转换器

让我们通过一个完整的示例来演示如何实现一个将图像转换为 PDF 的功能

步骤 1：注册功能

将功能添加到 EndpointConfiguration 类

步骤 2：创建控制器类

创建 API 控制器

创建 Web 控制器

步骤 3：实现工具方法

在 PdfUtils.java 中添加一个方法

步骤 4：创建 Thymeleaf 模板

创建 src/main/resources/templates/convert/img-to-pdf.html

步骤 5：添加翻译

将翻译添加到 messages_en_GB.properties

功能集成过程图

这是一个更详细的图表，展示了添加新功能时不同组件如何交互

来源

最佳实践

向 Stirling-PDF 添加新功能时，请遵循以下最佳实践

  1. 遵循现有模式：研究现有代码以理解项目的模式和约定

  2. 错误处理：实现适当的错误处理并向用户提供有意义的错误消息

  3. 国际化：始终使用消息属性进行文本显示，以支持多种语言

  4. 文档：添加全面的 Javadoc 注释并更新 API 文档

  5. 安全性：验证所有用户输入并确保文件操作安全

  6. 测试：使用各种输入和边缘情况彻底测试您的功能

  7. 代码组织：保持代码组织有序并遵循现有的包结构

  8. 功能注册：始终在 EndpointConfiguration 类中注册您的功能

  9. 一致的命名：使用与现有代码库一致的命名约定

  10. 贡献流程：提交更改时遵循项目的贡献指南

应避免的常见陷阱

  1. 忘记注册端点：新功能必须在 EndpointConfiguration 类中注册

  2. 硬编码文本：始终使用翻译键而不是硬编码字符串

  3. 忽略安全性：验证所有用户输入以防止安全漏洞

  4. 缺少错误处理：始终处理异常并提供有意义的错误消息

  5. 紧密耦合的代码：将业务逻辑与控制器分离，以提高可维护性

  6. 测试不足：使用各种输入和边缘情况彻底测试您的功能

  7. 翻译不完整：为所有用户可见文本添加翻译键

  8. 忽略现有模式：遵循项目中已建立的编码模式

结论

向 Stirling-PDF 添加新功能涉及理解应用程序架构、实现后端和前端组件、添加翻译以及进行彻底测试。遵循本文档中的指南，您可以贡献高质量的功能，使其与现有代码库无缝集成。

请记住，Stirling-PDF 项目遵循模块化架构，并明确分离关注点。这使得添加新功能更容易，而不会影响现有功能。通过仔细规划您的实现并遵循已建立的模式，您可以为项目贡献有价值的新功能。

来源