README

英文 | 葡萄牙语 | 中文

简介

Sqlcommenter Hyperf是一个库，用于自动向由Hyperf框架执行的SQL查询添加注释。这些注释使用sqlcommenter格式，该格式被各种数据库工具和服务所理解，为您的应用程序的数据库交互提供更深入的洞察和可追溯性。

安装

您可以通过Composer安装此库

composer require reinanhs/sqlcommenter-hyperf

添加组件配置

php bin/hyperf.php vendor:publish reinanhs/sqlcommenter-hyperf

示例

查看一个简单查询的执行示例

select *
from users

使用此包，将添加类似这样的注释

select *
from users /*framework='Hyperf',
application='hyperf-skeleton',
controller='UserController',
action='index',
route='%%2Fapi%%2Ftest',
db_driver='mysql',
traceparent='00-1cd60708968a61e942b5dacc2d4a5473-7534abe7ed36ce35-01'*/

通过检查上述SQL语句及其在/*...*/中的注释，我们可以关联并识别SQL查询中的字段与Hyperf中的源代码

表1：每种类型注释的描述信息

各种工具和服务可以解释这些注释，帮助关联用户代码与ORM生成的SQL语句，并可在数据库服务器日志中查看。这为您提供了更好的可观察性，直至数据库服务器。

以下是如何在Google Cloud SQL中显示这些信息的示例

上图说明了sqlcommenter信息在Google Cloud中的映射。在这种情况下，sqlcommenter被用于在查询洞察中添加标签，使其更容易识别导致性能问题的应用程序代码的哪个部分。

点击其中一个标签，您将能够查看有关查询的详细信息。以下是一个示例

除了Cloud SQL之外，还有其他几个工具也支持sqlcommenter。一个例子是Planetscale Query Insights。

跟踪

通过使用sqlcommenter-hyperf库，您可以关联Cloud SQL查询跟踪信息与您的Hyperf项目。通过同步您的信息，您将获得比Hyperf默认提供的更详细的跟踪级别。

以下是两个图像的比较，展示了Hyperf中标准SQL的跟踪信息和来自Cloud SQL Query的跟踪信息

以下图像展示了Hyperf中标准SQL的跟踪信息

以下图像展示了与Hyperf中的请求关联的Cloud SQL跟踪信息

使用sqlcommenter-hyperf库的一个提示是禁用Hyperf中的默认SQL跟踪，因为您将通过GCP中的Cloud SQL Query跟踪获得更详细的信息。

配置

当您在项目中安装此库时，它将通过默认设置自动启用。因此，要使用此库，您只需在项目中安装它即可。

然而，如果您想禁用一些注释，您可以通过设置来实现。还值得一提的是，您也可以通过设置在特定环境中完全禁用此库的执行。

以下设置可以启用或禁用此库生成的注释。默认情况下，所有注释都启用。您可以在config/autoload/sqlcommenter.php文件中找到此配置

'enable' => env('SQLCOMMENTER_ENABLE', true),
'include' => [
    'framework' => env('SQLCOMMENTER_ENABLE_FRAMEWORK', true),
    'controller' => env('SQLCOMMENTER_ENABLE_CONTROLLER', true),
    'action' => env('SQLCOMMENTER_ENABLE_ACTION', true),
    'route' => env('SQLCOMMENTER_ENABLE_ROUTE', true),
    'application' => env('SQLCOMMENTER_ENABLE_APPLICATION', true),
    'db_driver' => env('SQLCOMMENTER_ENABLE_DB_DRIVER', true),
],

下面是每个设置的详细说明

特性

• 自动将sqlcommenter兼容的注释添加到SQL查询中。
• 提供更好的数据库交互的可追溯性和洞察力。
• 易于与Hyperf框架集成。
• 支持多种数据库驱动程序。

性能

使用Sqlcommenter Hyperf库可能会因为向SQL查询中添加注释而引入轻微的性能影响。然而，在可追溯性、易于调试和与监控工具集成方面的好处通常超过了这种影响。

为了展示Sqlcommenter Hyperf库的有效性，我们将进行两次不同的测试。测量将在以下配置的受控Google Cloud Run环境中进行

• CPU始终分配
• 最小实例数：1
• 最大实例数：1
• 每个实例的内存：1GB
• 每个实例的vCPU数量：1vCPU
• 每个实例的最大并发请求数：1000

以下是我们用作实验的项目

• sample-sqlcommenter-hyperf-poc

代码块平均执行时间测试

在这个测试中，我们将测量添加SQL注释的SqlCommenterAspect代码块的平均执行时间。收集了此操作的10,000条执行时间记录后，我们计算了平均执行时间，大约为0.103毫秒（ms）。

这个值表明将SQL注释插入查询是一个极其快速的操作，对总查询执行时间的影响微乎其微。

• 有关代码块平均执行时间测试的完整文档

请求延迟性能测试

在这个测试中，我们将使用K6发起多次请求，并比较启用和禁用库的性能。下面是实验结果

在分析上述图像时，我们可以看到，最初，两种配置的响应时间非常相似。然而，当CPU消耗增加并接近1 vCPU的限制时，禁用配置（False）开始表现略好。通过检查CPU利用率图表，我们发现大约在400 VUs时，两种配置的CPU使用率都约为98%。

当库没有激烈竞争CPU使用时，它能够保持非常好的性能，接近禁用配置的性能。这表明在高需求条件下，禁用配置可以更好地处理负载，导致每秒处理的请求数量略有增加。

如果您想查看测试的详细信息，建议点击以下链接

• 有关请求延迟性能测试的完整文档

变更日志

请参阅CHANGELOG以获取有关最近更改的更多信息。

贡献

您想成为这个项目的一部分吗？请阅读如何贡献。

安全漏洞

请查阅我们的安全策略以了解如何报告安全漏洞。

许可证

本项目受许可协议约束。有关详细信息，请参阅许可文件。