幂等性头部ASGI中间件

使端点幂等的中间件。

中间件的目的确保修改端点的执行恰好一次，无论请求的数量。我们通过缓存响应，并在重复请求时向用户返回已保存的响应来实现这一点。只有当存在幂等性键HTTP头部时才缓存响应，因此客户端必须选择加入此行为。此外，只有配置的HTTP方法（默认为POST和PATCH）返回JSON有效负载时才缓存和重放。

这主要模仿了stripe的实现。

该中间件与Starlette和FastAPI应用程序都兼容。

安装

pip install asgi-idempotency-header

设置

将中间件添加到您的应用程序中，如下所示

from fastapi import FastAPI

from idempotency_header_middleware import IdempotencyHeaderMiddleware
from idempotency_header_middleware.backends import RedisBackend


backend = RedisBackend(redis=redis)

app = FastAPI()
app.add_middleware(IdempotencyHeaderMiddleware(backend=backend))

或如下所示

from fastapi import FastAPI
from fastapi.middleware import Middleware

from idempotency_header_middleware import IdempotencyHeaderMiddleware
from idempotency_header_middleware.backends import RedisBackend


backend = RedisBackend(redis=redis)

app = FastAPI(
    middleware=[
        Middleware(
            IdempotencyHeaderMiddleware,
            backend=backend,
        )
    ]
)

如果您使用的是Starlette，只需将FastAPI替换为Starlette，它应该会以相同的方式工作。

配置

中间件接受几个参数。一个完整的示例如下所示

from aioredis import from_url

from idempotency_header_middleware import IdempotencyHeaderMiddleware
from idempotency_header_middleware.backends import RedisBackend


redis = from_url(redis_url)
backend = RedisBackend(redis=redis)

IdempotencyHeaderMiddleware(
    backend,
    idempotency_header_key='Idempotency-Key',
    replay_header_key='Idempotent-Replayed',
    enforce_uuid4_formatting=False,
    expiry=60 * 60 * 24,
    applicable_methods=['POST', 'PATCH']
)

以下部分描述了每个参数

后端

from idempotency_header_middleware.backends import RedisBackend, MemoryBackend

backend: Union[RedisBackend, MemoryBackend]

后端是唯一必需的参数，因为它定义了如何和在哪里存储响应。

该软件包包含aioredis后端实现，以及用于测试的内存后端。

欢迎为更多后端做出贡献，配置自定义后端相当简单 - 只需查看现有的实现。

幂等性头键

idempotency_header_key: str = 'Idempotency-Key'

幂等性头键是要检查的头部值。当存在时，如果HTTP方法在适用方法中，则将使用中间件。

默认值是"Idempotency-Key"，但它可以是任何字符串。

重放头键

replay_header_key: str = 'Idempotent-Replayed'

重放头被添加到重放响应中。它提供了一种方法，让客户端能够告诉操作是否是第一次执行。

强制UUID格式

enforce_uuid4_formatting: bool = False

方便的选项，用于更严格的头部值验证。

客户端实际上可以在其头部设置任何值，但键值越短，与其他用户发生值冲突的风险就越高。如果两个用户不小心发送了相同的头部值，而这些值本应代表两个不同的请求，则中间件将它们解释为相同的。

通过启用此选项，您可以强制用户使用UUID作为头部值，从而基本上消除这种风险。

当验证失败时，中间件会返回一个422响应，告知用户头部值格式不正确。

过期

expiry: int = 60 * 60 * 24

缓存响应的时间长度，以秒为单位。默认设置为24小时。

适用方法

applicable_methods=['POST', 'PATCH']

要考虑的HTTP方法以进行幂等性。如果请求方法是此列表中的方法之一，并且发送了幂等性头，则将使用中间件。默认情况下，只有POST和PATCH方法被缓存和重放。

行为快速总结

简要总结，中间件就是这样工作的

• 第一个请求被处理，随后的请求被重放，直到响应过期。expiry可以设置为None以跳过过期，但您很可能希望一段时间后过期响应。
• 如果有两个请求同时到达 - 即，如果第二个请求在第一个请求完成之前击中中间件，则中间件将返回一个409，告知用户正在处理请求，并且无法处理第二个请求。
• 中间件仅处理HTTP请求。
• 默认情况下，中间件仅处理具有POST和PATCH方法的请求。其他HTTP方法会跳过此中间件。
• 仅缓存有效的JSON响应，其中content-type == application/json。