README

此包为您的Symfony应用程序中的请求和响应添加请求ID。

原因：这是一个简单而有效的方式，可以在日志中添加一些额外信息并展示给用户。例如，如果请求失败或抛出异常，您将能够向用户显示请求ID，他们可以将此ID传递给您以定位他们的问题。

安装

请求ID包可以在项目的任何生命周期阶段安装。

要求

PHP 8.0
Symfony 6.0

安装包

请使用 composer 安装包

composer require semaio/request-id-bundle

启用包

然后，通过在项目的 bundles.php 文件中添加以下行来启用包：

// config/bundles.php

return [
    // ...
    Semaio\RequestId\SemaioRequestIdBundle::class => ['all' => true],
    // ...
];

配置包

现在，包已安装并启用，您需要添加一些配置

# config/packages/semaio_request_id.yml

semaio_request_id:
    # Service that implements `Semaio\RequestId\Generator\GeneratorInterface`.
    # Defaults to `Semaio\RequestId\Generator\RamseyUuid4Generator`.
    generator_service: ~

    # Service that implements `Semaio\RequestId\Policy\PolicyInterface`.
    # Defaults to `Semaio\RequestId\Policy\DefaultPolicy`.
    policy_service: ~

    # Service that implements `Semaio\RequestId\Provider\ProviderInterface`.
    # Defaults to `Semaio\RequestId\Provider\SimpleRequestIdProvider`.
    provider_service: ~

    # The header which will contain the request ID on the response.
    response_header: "X-Request-Id"

    # The header which will contain the request ID that will be checked on incoming requests.
    request_header: "X-Request-Id"

    # Whether to add the request ID to monolog messages (see below), defaults to true.
    enable_monolog: true

    # Whether to add the twig extension (see below), defaults to true.
    enable_twig: true

    # Configuration for additional generators.
    generators:
        # Additional configuration for `Md5Generator`
        md5:
            # Specify which generator should be used to generate a request id that is then hashed by PHP's md5 function.
            # Defaults to `RamseyUuid4Generator`
            generator_service: ~

        # Additional configuration for `PhpUniqidGenerator`. 
        # See https://php.ac.cn/manual/en/function.uniqid.php for more information about PHP's uniqid function parameters.
        phpuniqid:
            prefix: ''
            more_entropy: false

工作原理

当请求到达您的Symfony应用程序时，如果您的配置策略允许，包会检查 X-Request-Id 标头。如果存在，则将给定的值用于整个请求生命周期。这允许您从更高层（如Web服务器本身或负载均衡器）使用请求ID。

如果没有找到请求ID或配置策略拒绝使用任何给定的 X-Request-Id 标头，则包将基于配置的生成器创建新的请求ID。默认情况下，生成UUID版本4的请求ID（例如：31c70a8e-8a1e-47af-9c31-3285e9bc2eb3）。

在向客户端发送响应之前，使用生成的请求ID值在响应上也设置了 X-Request-Id 标头。

组件

生成器

生成器创建一个随机字符串，在您的Symfony应用程序请求生命周期中用作请求ID。

所有生成器都必须实现 Semaio\RequestId\Generator\GeneratorInterface 接口。默认情况下，有三个可能的生成器

RamseyUuid4Generator
- 此生成器通过利用 ramsey/uuid 库创建UUID v4请求ID。
- 这是默认生成器！
PhpUniqidGenerator
- 此生成器使用PHP的本地 uniqid 函数创建请求ID。
Md5Generator
- 此生成器通过注入生成器（默认：RamseyUuid4Generator）创建请求ID，然后使用PHP的本地 md5 函数对请求ID进行哈希处理。

策略

策略检查传入请求的两个原因

是否应向当前请求添加请求ID？
如果当前请求已包含请求ID，则是否应信任此值或包应创建新的请求ID？

所有策略都必须实现 Semaio\RequestId\Policy\PolicyInterface 接口。默认情况下，有两个可能的策略

DefaultPolicy
- 允许向请求添加请求ID并接受任何给定的传入请求ID。
- 这是默认策略！
RejectRequestIdHeaderPolicy
- 允许向请求添加请求ID但拒绝任何给定的传入请求ID。

提供者

提供商持有生成的请求ID，并将其提供给您代码中的任何可能需要请求ID的部分。默认情况下，只有一个提供商

SimpleRequestIdProvider
- 这是一个简单的getter-setter PHP对象。
- 这是默认提供商！

扩展

Monolog集成

此包提供了一个monolog 处理器，它将请求ID添加到记录的extra数组中。可以通过在包配置中将enable_monolog设置为false来关闭此功能。

要在日志中使用请求ID，请在格式化器中包含%extra.request_id%。以下是此包测试中的配置示例。

# https://symfony.ac.cn/doc/current/logging.html#changing-the-formatter

services:
    request_id_formatter:
        class: Monolog\Formatter\LineFormatter
        arguments:
            - "[%%level_name%% - %%extra.request_id%%] %%message%%"

monolog:
    handlers:
        file:
            type: stream
            level: debug
            formatter: request_id_formatter

Twig集成

此包在您的Twig环境中提供了一个全局的request_id函数。可以在包配置中将enable_twig设置为false来关闭此功能。

这是一个模板示例。

<!DOCTYPE html>
<html>
<head>
    <title>Hello World!</title>
</head>
<body>
    <h1>{{ request_id() }}</h1>
</body>
</html>

许可

MIT

semaio / request-id-bundle

维护者

详细信息

README

安装

要求

安装包

启用包

配置包

工作原理

组件

生成器

策略

提供者

扩展

Monolog集成

Twig集成

许可