{"id":15137056,"url":"https://github.com/reinanhs/sqlcommenter-hyperf","last_synced_at":"2025-10-23T11:32:14.862Z","repository":{"id":242981375,"uuid":"808832212","full_name":"ReinanHS/sqlcommenter-hyperf","owner":"ReinanHS","description":"SQLCommenter implementation for Hyperf.","archived":false,"fork":false,"pushed_at":"2024-07-19T21:12:24.000Z","size":447,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-01-30T18:47:43.086Z","etag":null,"topics":["hyperf","opentelemetry","php","sqlcommenter"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ReinanHS.png","metadata":{"files":{"readme":"README-CN.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-05-31T23:31:34.000Z","updated_at":"2024-07-18T00:42:21.000Z","dependencies_parsed_at":"2024-06-06T02:56:27.400Z","dependency_job_id":"01dc10c5-49cf-481f-a640-027f6449c56c","html_url":"https://github.com/ReinanHS/sqlcommenter-hyperf","commit_stats":null,"previous_names":["reinanhs/sqlcommenter-hyperf"],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ReinanHS%2Fsqlcommenter-hyperf","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ReinanHS%2Fsqlcommenter-hyperf/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ReinanHS%2Fsqlcommenter-hyperf/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ReinanHS%2Fsqlcommenter-hyperf/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ReinanHS","download_url":"https://codeload.github.com/ReinanHS/sqlcommenter-hyperf/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":237821761,"owners_count":19371823,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["hyperf","opentelemetry","php","sqlcommenter"],"created_at":"2024-09-26T06:43:11.980Z","updated_at":"2025-10-23T11:32:09.508Z","avatar_url":"https://github.com/ReinanHS.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"中文 | [Português](./README-PT.md) | [English](./README.md)\n\n\u003cp align=\"center\"\u003e\u003ca href=\"https://google.github.io/sqlcommenter/\" target=\"_blank\" rel=\"noopener noreferrer\"\u003e\u003cimg src=\"https://i.imgur.com/pkcyYLU.png\" alt=\"Sqlcommenter Logo\"\u003e\u003c/a\u003e\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/reinanhs/sqlcommenter-hyperf/releases\"\u003e\u003cimg src=\"https://poser.pugx.org/reinanhs/sqlcommenter-hyperf/v/stable\" alt=\"稳定版本\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.php.net\"\u003e\u003cimg src=\"https://img.shields.io/badge/php-%3E=8.1-brightgreen.svg?maxAge=2592000\" alt=\"Php 版本\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://packagist.org/packages/reinanhs/sqlcommenter-hyperf\"\u003e\u003cimg src=\"https://poser.pugx.org/reinanhs/sqlcommenter-hyperf/downloads\" alt=\"总下载量\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/reinanhs/sqlcommenter-hyperf/blob/main/LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/github/license/reinanhs/sqlcommenter-hyperf.svg?maxAge=2592000\" alt=\"Sqlcommenter 许可证\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n## 介绍\n\nSqlcommenter Hyperf 是一个库，旨在为 [Hyperf](https://github.com/hyperf/hyperf) 框架执行的 SQL 查询自动添加注释。这些注释使用 [sqlcommenter](https://google.github.io/sqlcommenter/) 格式，该格式被各种数据库工具和服务理解，为您的应用程序数据库交互提供更好的见解和可追溯性。\n\n## 安装\n\n您可以通过 Composer 安装该库：\n\n```shell\ncomposer require reinanhs/sqlcommenter-hyperf\n```\n\n添加组件配置：\n\n```shell\nphp bin/hyperf.php vendor:publish reinanhs/sqlcommenter-hyperf\n```\n\n## 示例\n\n以下是一个简单查询的示例：\n\n```sql\nselect *\nfrom users\n```\n\n使用该库后，查询将如下所示：\n\n```sql\nselect *\nfrom users /*framework='Hyperf',\napplication='hyperf-skeleton',\ncontroller='UserController',\naction='index',\nroute='%%2Fapi%%2Ftest',\ndb_driver='mysql',\ntraceparent='00-1cd60708968a61e942b5dacc2d4a5473-7534abe7ed36ce35-01'*/\n```\n\n通过检查上面的 SQL 语句及其注释 `/*...*/`，我们可以将 SQL 查询中的字段与我们的 web 应用程序中的源代码相关联并识别出来：\n\n\u003e 表1：每种注释类型的描述信息\n\n| 原始字段                                                                 | 解释                                                                                     |\n|--------------------------------------------------------------------------|------------------------------------------------------------------------------------------|\n| **framework**='Hyperf'                                                   | “Hyperf” 代表生成查询的框架。                                                            |\n| **application**='hyperf-skeleton'                                        | 运行代码的项目名称。                                                                     |\n| **controller**='UserController'                                          | 控制器的名称，在 `app/Controller` 中。                                                   |\n| **action**='index'                                                       | 控制器调用的方法名称。                                                                   |\n| **route**='%%2Fapi%%2Ftest'                                              | 调用查询时使用的路由。                                                                   |\n| **db_driver**='mysql'                                                    | Hyperf 数据库引擎的名称。                                                                |\n| **traceparent**='00-1cd60708968a61e942b5dacc2d4a5473-7534abe7ed36ce35-01'| OpenTelemetry trace 的 [W3C TraceContext Traceparent](https://www.w3.org/TR/trace-context/#traceparent-field) 字段。|\n\n各种工具和服务可以解释这些注释，帮助将用户代码与 ORM 生成的 SQL 语句相关联，并可以在数据库服务器日志中进行检查。这为您的应用程序状态提供了更好的可观察性，直到数据库服务器。\n\n以下是这些信息在 [Google Cloud SQL](https://cloud.google.com/sql/docs/postgres/using-query-insights) 中的显示示例：\n\n![在 GCP 上的 SQLcommenter 示例](.github/assets/cloud-sql-query-insights-view-1.png)\n\n上图展示了 sqlcommenter 信息在 Google Cloud 中的映射。在这种情况下，sqlcommenter 被用来在 Query Insights 中添加标签，从而更容易识别导致性能问题的应用程序代码部分。\n\n点击这些标签之一，您可以查看有关查询的详细信息。请参见以下示例：\n\n![在 GCP 上的 SQLcommenter 示例](.github/assets/cloud-sql-query-insights-view-2.png)\n\n除了 **Cloud SQL** 之外，还有许多其他工具也支持 _sqlcommenter_。一个示例是 [Planetscale Query Insights](https://planetscale.com/docs/concepts/query-insights)。\n\n## Trace\n\n通过使用 sqlcommenter-hyperf 库，您可以将 Cloud SQL Query 的追踪信息与您的 Hyperf 项目相关联。通过关联这些信息，您将获得比 Hyperf 默认提供的更详细的可追溯性。\n\n下面是两张图片的对比，显示了 Hyperf 中的标准 SQL 追踪信息和 Cloud SQL Query 的追踪信息：\n\n下图展示了 Hyperf 中的标准 SQL 追踪：\n\n![Hyperf 中的标准 SQL 追踪](.github/assets/standard-sql-trace-in-hyperf.png)\n\n下图展示了与 Hyperf 请求关联的 Cloud SQL 追踪：\n\n![Hyperf 中的 Cloud SQL 追踪](.github/assets/cloud-sql-trace-in-hyperf.png)\n\n使用 sqlcommenter-hyperf 库的一个建议是禁用 Hyperf 的默认 SQL 追踪，因为通过 GCP 的 Cloud SQL Query 追踪，您将获得更详细的信息。\n\n## 配置\n\n当您将库安装到您的项目中时，它将通过默认配置自动启用。因此，要使用此库，您只需将其安装到项目中。\n\n但是，如果您想禁用某些注释，可以通过配置来实现。此外，您还可以通过配置完全禁用特定环境中的此库的执行。\n\n通过以下配置，您可以启用或禁用该库生成的注释。默认情况下，所有注释都是启用的。您可以在 `config/autoload/sqlcommenter.php` 文件中找到此配置：\n\n```php\n'enable' =\u003e env('SQLCOMMENTER_ENABLE', true),\n'include' =\u003e [\n    'framework' =\u003e env('SQLCOMMENTER_ENABLE_FRAMEWORK', true),\n    'controller' =\u003e env('SQLCOMMENTER_ENABLE_CONTROLLER', true),\n    'action' =\u003e env('SQLCOMMENTER_ENABLE_ACTION', true),\n    'route' =\u003e env('SQLCOMMENTER_ENABLE_ROUTE', true),\n    'application' =\u003e env('SQLCOMMENTER_ENABLE_APPLICATION', true),\n    'db_driver' =\u003e env('SQLCOMMENTER_ENABLE_DB_DRIVER', true),\n],\n```\n\n以下是每个配置的详细说明：\n\n| 配置                    | 类型      | 默认值    | 说明                                                                |\n|-----------------------|---------|--------|-------------------------------------------------------------------|\n| `enable`              | Boolean | `true` | 控制 SQLCommenter 是否启用。设置为 `true` 以启用 SQLCommenter 并将注释添加到 SQL 查询中。 |\n| `include.framework`   | Boolean | `true` | 在 SQL 注释中包括使用的框架名称。                                               |\n| `include.controller`  | Boolean | `true` | 在 SQL 注释中包括生成查询的控制器名称。                                            |\n| `include.action`      | Boolean | `true` | 在 SQL 注释中包括控制器中生成查询的操作或方法名称。                                      |\n| `include.route`       | Boolean | `true` | 在 SQL 注释中包括生成查询的请求相关联的路由。                                         |\n| `include.application` | Boolean | `true` | 在 SQL 注释中包括应用程序的名称。                                               |\n| `include.db_driver`   | Boolean | `true` | 在 SQL 注释中包括用于执行查询的数据库驱动程序名称。                                      |\n\n## 功能\n\n- 自动向 SQL 查询添加兼容 sqlcommenter 的注释。\n- 提供更好的可追溯性和数据库交互的见解。\n- 与 Hyperf 框架轻松集成。\n- 支持多种数据库驱动程序。\n\n## 性能\n\n使用 Sqlcommenter Hyperf 库可能会引入一些性能影响，因为它会向 SQL 查询添加注释。然而，在可追溯性、调试的便利性和与监控工具的集成方面的好处通常超过了这些影响。\n\n为了展示 Sqlcommenter Hyperf 库的有效性，我们将进行两个不同的测试。测量将在 Google Cloud Run 的受控环境中进行，配置如下：\n\n- CPU 始终分配\n- 最小实例数：1\n- 最大实例数：1\n- 每个实例的内存：1GB\n- 每个实例的 vCPU 数量：1vCPU\n- 每个实例的最大并发请求数：1000\n\n以下是用于实验的项目：\n\n- [sample-sqlcommenter-hyperf-poc](https://github.com/ReinanHS/sample-sqlcommenter-hyperf-poc)\n\n### 代码块的平均执行时间测试：\n\n在此测试中\n\n，我们将测量添加 SQL 注释的 SqlCommenterAspect 代码块的平均执行时间。在收集了 10,000 条执行时间记录后，我们计算出平均执行时间约为 **0.103 毫秒 (ms)**。\n\n该值表明将 SQL 注释插入查询是一项极快的操作，几乎不会对查询的总执行时间产生影响。\n\n- [有关代码块平均执行时间测试的完整文档](https://github.com/ReinanHS/sqlcommenter-hyperf/wiki/Performance#performance-analysis-of-the-code-block-in-the-library)\n\n### 请求延迟性能测试\n\n在此测试中，我们将使用 K6 进行多次请求，并比较启用和禁用库时的性能。请参阅下面的实验结果：\n\n![启用与禁用配置的性能](.github/assets/performance-configuration-chart.png)\n\n通过分析上图，我们可以看到，最初两种配置的响应时间非常相似。然而，随着 CPU 消耗的增加并接近 1 vCPU 的限制，禁用配置（False）的性能略有提升。通过检查 CPU 利用率图表，我们观察到在大约 400 VUs 时，两种配置的 CPU 使用率均约为 98%。\n\n当库不在 CPU 使用上进行激烈竞争时，它可以保持非常好的性能，接近禁用配置。这表明，在高需求条件下，禁用配置可以稍微更好地处理负载，从而导致每秒处理的请求数略有增加。\n\n如果您想查看有关测试的详细信息，建议点击以下链接：\n\n- [有关请求延迟性能测试的完整文档](https://github.com/ReinanHS/sqlcommenter-hyperf/wiki/Performance#request-latency-performance-test)\n\n## 更新日志\n\n请参阅 [CHANGELOG](CHANGELOG.md) 了解最近的更改。\n\n## 贡献\n\n您想成为这个项目的一部分吗？请阅读 [如何贡献](CONTRIBUTING.md)。\n\n## 安全漏洞\n\n请查看 [我们的安全政策](https://github.com/reinanhs/sqlcommenter-hyperf/security/policy) 了解如何报告安全漏洞。\n\n### 许可证\n\n此项目已获得许可。有关详细信息，请参阅 [LICENSE](LICENSE) 文件。","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Freinanhs%2Fsqlcommenter-hyperf","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Freinanhs%2Fsqlcommenter-hyperf","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Freinanhs%2Fsqlcommenter-hyperf/lists"}