python-infrastructure

Python 基础设施

Python 服务的系统可靠性问题，按实际代码中常常一起使用的功能归类：排入队列的任务（background-jobs）需要在同一调用路径上进行重试（resilience）和监控（observability）。

范围路由

如果你需要……	阅读
设计任务队列、安排周期性任务，或运行异步工作进程（Celery、RQ、asyncio 任务池）	References/background-jobs.md
决定重试什么、采用何种退避策略，以及何时停止（tenacity 模式、幂等性、熔断器）	References/resilience.md
使用结构化日志、指标和追踪为服务添加监控（structlog、OpenTelemetry、四大黄金信号）	References/observability.md

决策树

Operation can fail transiently (network/IO/3rd-party API)?
  -> resilience.md (retry policy)
Operation runs out-of-request (email, image processing, batch)?
  -> background-jobs.md (queue + worker)
Need to know what's happening in production?
  -> observability.md (logs/metrics/traces)
All three at once for one feature?
  -> all three references, in that order.

跨技能边界

• writing-python — 如何编写函数。本技能 — 如何让函数在生产环境中稳定运行。
• python-error-handling — 应抛出什么异常。本技能 — 异常跨越网络边界时该怎么处理。
• python-resource-management — 如何清理资源（上下文管理器）。本技能 — 资源获取失败时如何持续重试。

注意事项

• 没有退避的重试会放大拒绝服务（DoS）问题。 下游服务故障后，N 个客户端立即重试，会造成流量突增，使下游服务持续宕机。从一开始就默认使用指数退避和抖动。
• 重试非幂等操作会重复产生副作用。 POST 请求失败后重试，可能导致扣款两次。重试失败操作时，务必同时使用幂等键，或将该操作标记为不可重试。
• 异步工作进程中的同步代码会阻塞事件循环。 在 asyncio 工作进程中调用一个“快速”的 requests 请求也会降低吞吐量。请使用异步客户端（httpx、aiohttp），或在执行器中运行同步代码。
• 结构化日志和指标面向不同的受众。 日志回答“这一个请求发生了什么”；指标回答“所有请求总体情况如何”。不要试图从一种数据推导另一种——两者都要进行监控。
• 追踪上下文需要显式跨队列边界传递。 将任务推送到 Celery 会丢失当前追踪，除非将追踪上下文序列化到任务头中，并在工作进程中恢复。不要想当然地认为它“会自动生效”；请先阅读 OpenTelemetry-Celery 传播器文档。