python-integrations-resilience

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Python Integrations and Resilience

Python集成与弹性设计

Overview

概述

External integrations stay reliable when provider-specific details hide behind explicit client boundaries, and every outbound operation carries a defined reliability policy that is tested against both success and failure paths.

Treat these recommendations as preferred defaults. When project constraints demand deviation, call out tradeoffs and compensating controls (tests, observability, rollback).

外部集成要保持可靠性，需将服务商特定细节隐藏在明确的客户端边界之后，并且每个出站操作都带有针对成功和失败路径测试过的既定可靠性策略。

将这些建议视为首选默认方案。当项目约束要求偏离时，需说明权衡方案和补偿控制措施（测试、可观测性、回滚）。

When to Use

适用场景

Designing or reviewing client boundaries around external APIs or provider SDKs.
Adding or auditing timeout, retry, or idempotency policy on outbound calls.
Writing contract or resilience tests for provider integrations.
Diagnosing contract drift between a client wrapper and the upstream provider.
Refactoring domain logic that has coupled itself to a specific provider SDK.

围绕外部API或服务商SDK设计或审查客户端边界时。
为出站调用添加或审核超时、重试或幂等性策略时。
为服务商集成编写契约或弹性测试时。
诊断客户端包装器与上游服务商之间的契约漂移时。
重构与特定服务商SDK耦合的领域逻辑时。

When NOT to Use

不适用场景

Pure in-process library calls with no network or I/O boundary.
Internal module interfaces that carry no external contract risk.
Performance tuning of already-isolated integrations (see
```
python-concurrency-performance
```
).

无网络或I/O边界的纯进程内库调用。
无外部契约风险的内部模块接口。
对已隔离集成进行性能调优（请参见
```
python-concurrency-performance
```
）。

Quick Reference

快速参考

Hide provider-specific details behind explicit client boundaries.
Keep domain logic isolated from provider SDK specifics.
Require explicit timeout/retry/idempotency policy for every outbound operation.
Test both contract mapping and failure behavior directly.

将服务商特定细节隐藏在明确的客户端边界之后。
保持领域逻辑与服务商SDK细节隔离。
要求每个出站操作都有明确的超时/重试/幂等性策略。
直接测试契约映射和失败行为。

Common Mistakes

常见错误

Letting provider types cross the boundary — returning raw SDK response objects into domain code couples the entire codebase to one provider.
Implicit or missing timeouts — relying on library defaults (or no timeout at all) turns a slow upstream into a cascading failure.
Retrying non-idempotent calls — retrying a POST without an idempotency key risks duplicate side effects.
Testing only the happy path — skipping timeout, rate-limit, and malformed-response scenarios leaves the most likely production failures uncovered.
Hardcoding retry policy — embedding backoff constants deep in client code prevents tuning without a redeploy.

允许服务商类型跨越边界——将原始SDK响应对象返回至领域代码会使整个代码库与单一服务商耦合。
隐式或缺少超时设置——依赖库默认值（或完全没有超时设置）会将上游服务缓慢的问题转化为级联故障。
重试非幂等调用——在没有幂等键的情况下重试POST请求可能导致重复副作用。
仅测试正常路径——跳过超时、速率限制和格式错误响应场景会使最可能发生的生产故障未被覆盖。
硬编码重试策略——在客户端代码深处嵌入退避常量会导致无法在不重新部署的情况下进行调优。

Scope Note

范围说明

Treat these recommendations as preferred defaults for common cases, not universal rules.
If a default conflicts with project constraints or worsens the outcome, suggest a better-fit alternative and explain why it is better for this case.
When deviating, call out tradeoffs and compensating controls (tests, observability, migration, rollback).

将这些建议视为常见场景的首选默认方案，而非通用规则。
如果默认方案与项目约束冲突或导致结果更差，请提出更合适的替代方案并解释为何该方案更适合此场景。
当偏离默认方案时，需说明权衡方案和补偿控制措施（测试、可观测性、迁移、回滚）。

Invocation Notice

调用说明

Inform the user when this skill is being invoked by name:
```
python-design-modularity
```
.

当通过名称
```
python-design-modularity
```
调用此技能时，需告知用户。

References

参考资料

```
references/client-patterns.md
```

references/request-reliability-policy.md

references/resilience-and-contract-testing.md

```
references/client-patterns.md
```

references/request-reliability-policy.md

references/resilience-and-contract-testing.md