PyBreaker 使用与技术文档

1. 安装指南

安装 PyBreaker 最简单的方式是使用 pip 工具从 PyPI 下载最新稳定版本：

pip install pybreaker

如果您是 Git 用户，并希望安装最新的开发版本，可以按照以下步骤操作：

git clone git://github.com/danielfm/pybreaker.git
cd pybreaker
# 在 Windows 下请省略 ./
./pw test
pip install -e .

2. 项目使用说明

PyBreaker 是一种 Python 实现的电路断路器模式，该模式在 Michael T. Nygard 的书籍 Release It! 中有所描述。电路断路器允许一个子系统在失败时不会破坏整个系统。这是通过在危险操作（通常是集成点）周围包装一个可以在系统不健康时绕过调用的组件来实现的。

使用方法

首先，为每个要保护的集成点创建一个 CircuitBreaker 实例：

import pybreaker

# 用于数据库集成点
db_breaker = pybreaker.CircuitBreaker(fail_max=5, reset_timeout=60)

CircuitBreaker 实例应该在应用程序范围内全局存在，例如，跨请求存在。

如果希望使用 Redis 作为后端存储，可以在初始化 CircuitBreaker 时指定一个 CircuitRedisStorage：

import pybreaker
import redis

redis = redis.StrictRedis()
db_breaker = pybreaker.CircuitBreaker(
    fail_max=5,
    reset_timeout=60,
    state_storage=pybreaker.CircuitRedisStorage(pybreaker.STATE_CLOSED, redis))

请注意，初始化 Redis 连接时不要将 decode_responses 设置为 True，这会强制 redis 返回 ASCII 对象，并在 Python3+ 中因为 AttributeError: 'str' object has no attribute 'decode' 而失败。

事件监听

如果只是想要在特定事件发生时执行操作，无需子类化 CircuitBreaker，而是子类化 CircuitBreakerListener：

class DBListener(pybreaker.CircuitBreakerListener):
    "执行数据库操作的监听器"

    def before_call(self, cb, func, *args, **kwargs):
        "在电路断路器 `cb` 调用 `func` 之前被调用"
        pass

    def state_change(self, cb, old_state, new_state):
        "当电路断路器 `cb` 状态改变时被调用"
        pass

    def failure(self, cb, exc):
        "当函数调用引发系统错误时被调用"
        pass

    def success(self, cb):
        "当函数调用成功时被调用"
        pass

电路断路器的工作原理

假设想要在更新数据库中的 customer 表的行时使用电路断路器：

@db_breaker
def update_customer(cust):
    # 执行操作...
    pass

# 将触发电路断路器
updated_customer = update_customer(my_customer)

如果不使用装饰器语法：

def update_customer(cust):
    # 执行操作...
    pass

# 将触发电路断路器
updated_customer = db_breaker.call(update_customer, my_customer)

或者，作为上下文管理器与 with 语句一起使用：

# 将触发电路断路器
with db_breaker.calling():
    # 执行操作...
    pass

根据默认参数，电路断路器 db_breaker 在 update_customer 中连续失败 5 次后将自动打开电路。

当电路打开时，所有对 update_customer 的调用都会立即失败（抛出 CircuitBreakerError），而无需尝试执行实际操作。如果希望在电路跳闸时抛出原始错误，可以将 throw_new_error_on_trip 选项设置为 False：

pybreaker.CircuitBreaker(..., throw_new_error_on_trip=False)

60 秒后，电路断路器将允许下一个对 update_customer 的调用通过。如果该调用成功，则电路关闭；如果失败，则电路再次打开，直到另一个超时过期。

3. 项目API使用文档

PyBreaker 提供了用于监控和更改其当前状态的属性和函数：

# 获取当前连续失败次数
print(db_breaker.fail_counter)

# 获取/设置最大连续失败次数
print(db_breaker.fail_max)
db_breaker.fail_max = 10

# 获取/设置当前重置超时时间（秒）
print(db_breaker.reset_timeout)
db_breaker.reset_timeout = 60

# 获取当前状态，即 'open', 'half-open', 'closed'
print(db_breaker.current_state)

# 关闭电路
db_breaker.close()

# 半开电路
db_breaker.half_open()

# 打开电路
db_breaker.open()

这些属性和函数应该被以某种方式暴露给运维人员，因为它们可以帮助他们检测系统中的问题。

4. 项目安装方式

请参考上述“安装指南”部分，获取 PyBreaker 的安装方法。