Prop 项目技术文档

本文档将详细介绍如何安装、使用以及API调用Prop项目，帮助用户更好地理解并运用该限流工具。

1. 安装指南

在项目中使用Prop之前，需要先将其添加到项目依赖中。对于Ruby项目，可以在Gemfile中添加以下代码：

gem 'prop'

然后执行以下命令安装Prop：

bundle install

2. 项目使用说明

Prop是一个用于限制请求或操作的Ruby库。它支持两种限制策略：基本策略和漏桶策略。

2.1 基本策略

基本策略使用时间间隔定义一个时间窗口。这意味着在最坏情况下，允许在指定时间间隔内进行两倍于指定的请求数。

2.2 漏桶策略

漏桶策略类似于基本策略，但还支持一个指定的突发阈值。

在使用Prop之前，需要设置一个缓存来存储值：

Prop.cache = Rails.cache # 需要具有读/写/递增方法

当使用间隔策略时，Prop将设置一个键的过期时间为间隔时间。因为漏桶策略不设置TTL，所以最好使用memcached或类似缓存，而不是redis。

2.3 设置回调

可以定义一个可选的回调，当达到速率限制时调用。在Rails应用中，可以使用此处理器添加通知支持：

Prop.before_throttle do |handle, key, threshold, interval|
  ActiveSupport::Notifications.instrument('throttle.prop', handle: handle, key: key, threshold: threshold, interval: interval)
end

2.4 定义阈值

例如，限制每小时接收的来自特定用户的邮件数：

Prop.configure(:mails_per_hour, threshold: 100, interval: 1.hour, description: "邮件速率限制超过")

2.5 使用限制

Prop.throttle!(:mails_per_hour) # 如果达到阈值/间隔，则抛出 Prop::RateLimited
Prop.throttled?(:mails_per_hour) # 如果达到阈值/间隔，则返回 true
Prop.reset(:mails_per_hour) # 将限制计数重置为0
Prop.count(:mails_per_hour) # 返回限制值，通常是计数

2.6 作用域限制

可以将限制作用域限定为特定的发送者：

Prop.throttle!(:mails_per_hour, mail.from)
Prop.throttled?(:mails_per_hour, mail.from)
Prop.reset(:mails_per_hour, mail.from)

3. 项目API使用文档

以下是Prop的一些关键API方法：

• Prop.configure(handle, threshold: <阈值>, interval: <间隔>, description: <描述>)：配置限制。
• Prop.throttle!(handle, [key])：如果达到阈值/间隔，则抛出Prop::RateLimited。
• Prop.throttled?(handle, [key])：如果达到阈值/间隔，则返回true。
• Prop.reset(handle, [key])：将限制计数重置为0。
• Prop.count(handle, [key])：返回限制值。

4. 项目安装方式

如前所述，将Prop添加到项目的Gemfile中，然后运行bundle install命令即可安装Prop。

请遵循上述指南和API文档，以便在项目中有效地使用Prop。