跳到主要内容

插件开发的最佳实践

我们整理了一系列构建和发布高质量 Grafana 插件的实践，我们认为这些实践非常有益。在构建您自己的插件时，请参考它们以获得最佳结果。

此列表中是否缺少内容？请告知我们。

通用​

  • 验证您的数据源或应用插件是否可以配置 - 有关更多信息，请参阅配置 (Provisioning)。
  • 在您的数据源或应用插件中包含默认仪表盘 - 有关更多信息，请参阅捆绑仪表盘。
  • 确保 Grafana 的最低版本正确 - 确保您的 plugin.json 中的 grafanaDependency 指向您的插件完全支持的最早 Grafana 版本。
  • 不要暴露敏感信息 - 出于安全原因，请避免暴露敏感信息，例如秘密。确保正确使用日志级别，避免过度日志记录，并且永远不要记录凭据或其他敏感信息。
  • 不允许用户输入任意代码 - 出于安全原因，不要让您的插件用户输入潜在的恶意代码，以防止任意代码执行。
  • 避免在插件中使用 console.log - 控制台消息通常用于调试目的，因此不适合交付给客户端。
  • 添加 Linting 和自动补全 - 通过在 VS Code 中添加类似这个代码片段来减少插件中的错误，从而为您的插件启用 Linting。
  • 包含一份写得好的 README 文件 - 让用户更深入地了解如何配置和使用您的插件，但不要让它成为必须阅读的内容。如果可能，您希望用户无需查阅文档就能直观地理解您的插件。
  • 允许循序渐进的学习 - 使用开关或分类隐藏高级选项，让用户在准备好时学习高级功能。
  • 招募 Beta 测试人员 - 在提交插件之前，招募目标用户试用您的插件。获取反馈以帮助在发布前改进您的插件。

面板插件​

  • 不要存储或使用凭据 - 面板插件没有安全存储凭据的方法。如果您的插件需要使用凭据，请考虑使用数据源或应用插件，然后使用面板插件来显示数据源返回的信息。

  • 考虑创建自定义选项 - 如果默认面板选项不适合您希望提供给用户的功能，请使用自定义选项。

  • 记录 dataframe 模式 - 考虑在 README 文件中记录插件的模式（预期字段、字段类型、字段名称命名约定等）。

数据源插件​

  • 如果您的插件需要存储凭据，请使用 secureJsonData 而不是 jsonData - 前者在静态时加密，而后者不加密。有关更多信息，请参阅安全 JSON 数据。
  • 实现查询构建器 - 这对于不熟悉数据源查询语言的用户非常有用。例如，请参阅用于 Microsoft SQL Server 的查询构建器，它有助于编写该服务的 SQL 查询。
  • 为您的插件添加健康检查 - 健康检查用于验证数据源是否正常工作。其实现方式取决于插件是否有后端。请参阅我们的前端健康检查示例和后端健康检查示例。对于 backend 的情况，只要它扩展了 `@grafana/runtime` 中的 DataSourceWithBackend 类，就不需要修改其前端代码。
  • 添加仪表盘变量支持 - 仪表盘（或模板）变量允许用户创建动态仪表盘。在插件中添加变量支持有两个方面。第一是允许将您的数据源查询和返回值用作变量。第二是在其他查询中替换现有变量。有关更多信息，请参阅我们的文档。选择“所有值”时请特别注意，因为它可能需要特定的逻辑来连接变量值。
  • 添加注释支持 - 注释允许用户向其仪表盘添加上下文信息，并且可以使用查询来定义它们。有关更多信息，请参阅启用注释。
  • 实践良好的前端设计 - 构建前端组件时，请务必使用 Grafana 组件 作为基础，并遵循 Saga 设计系统。
  • 添加查询编辑器帮助 - 查询编辑器可能很复杂，为用户提供帮助非常有用。有关更多信息，请参阅添加查询编辑器帮助。
  • 跳过隐藏或空查询 - 这可以避免执行不必要或错误的查询。实现 DataSourceWithBackend 的数据源只需实现 filterQuery 方法。请参阅此示例。
  • 指定默认查询 - 默认查询可以帮助用户了解如何为插件编写查询。

仅前端插件​

  • 仅在前端运行的数据源通常使用 Grafana 代理 来访问外部服务 - 这是在您的插件中添加查询支持的一种简单方法，并且不需要 Golang 知识。然而，在某些用例中，编写后端插件是必需的。有关这些用例的更多信息，请参阅后端插件。

后端插件​

  • 添加警报支持 - 后端插件固有地支持 Grafana 警报，但此支持需要启用。只需在您的 plugin.json 文件中添加 "alerting": true 即可。
  • 使用 CallResourceHandler 接口处理自定义 HTTP 请求。有关更多信息，请参阅资源处理器。例如，这在提供查询构建器时很有用，如本示例所示。
  • 为您的数据源添加日志、指标和追踪。 这使得插件开发者和 Grafana 操作人员更容易诊断和解决问题。在我们的文档中查找更多信息。
  • 保持连接缓存 - 这是一项重要的优化。要了解更多信息，请参阅我们的文档和示例。
  • 添加宏支持 - 宏类似于变量，但它们通常在后端评估，并可以根据环境数据（例如当前时间范围）返回值。例如，这对于在动态期间评估警报很有用。它们通常使用语法 $__macroName 定义（例如，$__timeFilter）。请参阅本示例，了解如何实现支持。一些预定义宏在插件 SDK 的 macros 包中可用。
  • 对于 SQL 数据源，请参考 SDK 中的 sqlutil 包 - 它包含多个帮助程序，用于处理 SQL 数据源，例如 dataframe 转换、默认宏等。此外，考虑使用sqlds 包，它极大地简化了 SQL 数据源的实现。
  • 不要使用本地文件系统 - 不同的插件共享相同的环境。出于安全原因，插件不应依赖本地文件。
  • 不要使用环境变量 - 环境变量也是一个安全风险，应避免使用。对于特定数据源的配置，请使用 plugin.json 文件中的 jsonData 或 secureJsonData 字段。如果插件需要跨数据源共享的配置，则使用plugin 配置。
  • 插件不应在后端执行任意代码 - 同样，这是一个安全风险，应避免。如果您的插件需要执行代码，请提供允许命令的列表，并在执行之前验证输入。
  • 通常，发生的任何错误都应以 error 级别记录。
  • 不要使用 info 级别：请改用 debug 级别。
  • 启用并发查询执行 - 这允许您并行运行多个查询。要了解更多信息，请参阅我们的文档。

应用插件​

  • 为您的应用指定根页面 - 如果您的应用定义了多个页面，请确保选择一个默认页面作为插件的登录页面。
  • 拆分您的应用代码 - 如果您的应用包含多个页面，请务必使用代码拆分技术来提高前端加载性能。默认情况下，如果任何前端资源大于 250KB，Webpack 将在构建期间在终端中显示警告。有关更多信息，请参阅以下链接：
  • 要生成动态应用，请考虑使用 Grafana Scenes。
  • 考虑贡献一个 UI 扩展 - UI 扩展可以帮助用户在上下文中发现您的应用并继续给定的工作流程。此外，如果您的应用提供了可在其他应用中使用的上下文，则创建扩展点以允许这些应用这样做，而无需对您的应用进行进一步更改。

发布插件​

管理插件兼容性​

在 Grafana 插件生态系统中，插件与特定 Grafana 版本的兼容性由插件的 plugin.json 文件中 grafanaDependency 属性定义的语义版本范围决定。插件作者必须仔细选择一个版本范围，以平衡广泛的兼容性与可管理的维护工作量需求。

插件开发中的独特挑战​

Grafana 插件是一种相当特殊的软件，因为编译期间使用的许多 npm 依赖项在运行时会被不同的版本替换。有关更多详细信息，请参阅Grafana 插件中的前端 NPM 依赖项。如果插件依赖于活动 Grafana 环境中不可用的 API，这种运行时替换可能会导致崩溃。因此，管理兼容性是插件开发中一个关键且复杂的方面。

管理插件兼容性的最佳实践​

为了确保插件的健壮性和可靠性，请遵循以下最佳实践：

  • 采用最新的插件 API： 使用最新的插件 API 版本可以帮助开发者利用 Grafana 的新功能，并确保与平台不断发展的能力保持一致。这也有助于鼓励对插件及其依赖项进行定期维护和更新。
  • 维护单一开发分支： 力争为插件支持的整个 Grafana 版本范围（在 grafanaDependency 中指定）维护单一分支。这种方法可以减轻维护负担，并与 Grafana 插件目录中使用的实践保持一致。
  • 通过运行时检查管理向后兼容性： 为了利用新的 Grafana 功能同时保持与旧版本的兼容性，请实现条件逻辑，在运行时验证功能的可用性。有关指导，请参阅通过运行时检查管理向后兼容性。
  • 使用 Grafana 版本矩阵执行端到端测试： Grafana 的依赖共享机制可能导致许多插件相关的问题仅在运行时出现。通过对插件的 plugin.json 文件中定义的 Grafana 版本矩阵进行端到端冒烟测试，可以有效地识别这些问题。定期针对旧的支持版本和 Grafana 的主要开发分支测试插件，可以确保向后和向前兼容性。这种方法使插件维护者能够验证当前和即将发布的 Grafana 版本的功能，从而保持可靠性并为未来的更新做好准备。