第16章 Route Handler 参考
第16章 Route handler 参考
功能内置代理Route handler 参考Route handler 参考本页是 Memcached 内置代理标准路由库所提供的 route handler（路由处理器）的参考文档。
关于如何在代理配置文件中调用这些 route handler，请参阅配置内置代理。示例请参阅示例配置文件。
Route handlers route_direct 将请求路由到单个 pool，并返回结果。 route_direct{ child = "POOL_NAME" } 将 POOL_NAME 替换为配置文件 pools{} 块中定义的 pool 名称。
route_null 立即返回与请求类型匹配的空响应。Get 请求返回 MISS，Set 请求返回 NOT_STORED，数值、touch 和 delete 命令返回 NOT_FOUND。 route_null{}
route_allsync 将请求并行路由到一组 pool。代理会等待所有响应完成。如果从任何一个 pool 收到错误，则返回收到的第一个错误；否则返回收到的最后一个结果。 route_allsync{ children = POOL_LIST_OR_SET_NAME } 将 POOL_LIST_OR_SET_NAME 替换为以下之一：
配置文件 pools{} 块中定义的 pool 名称列表，用花括号括起、以逗号分隔——例如 { "cust_pool_1", "cust_pool_2" }。 配置文件 pools{} 块中定义的 set 名称——例如 "set_cust_pools"。
route_allfastest 将请求并行路由到一组 pool。代理返回它从任何 pool 收到的第一个响应。 route_allfastest{ children = POOL_LIST_OR_SET_NAME, miss = MISS_BOOLEAN, wait = WAIT_FLOAT, } 将 POOL_LIST_OR_SET_NAME 替换为以下之一：
配置文件 pools{} 块中定义的 pool 名称列表，用花括号括起、以逗号分隔——例如 { "cust_pool_1", "cust_pool_2" }。 配置文件 pools{} 块中定义的 set 名称——例如 "set_cust_pools"。
MISS_BOOLEAN：如果为 true，则等待第一个命中响应或所有子 pool 返回。 WAIT_FLOAT：最多等待该秒数后，返回目前为止获得的最佳结果（允许小数）。
route_split 将请求路由到恰好两个 pool。代理只等待 child_a 所指定 pool 的响应，并返回其结果。 route_split{ child_a = "POOL_NAME_A" child_b = "POOL_NAME_B" } 替换以下内容：
POOL_NAME_A：代理配置文件 pools{} 块中定义的 pool 名称。 POOL_NAME_B：配置文件 pools{} 块中定义的另一个 pool 的名称。
route_ttl 在 set、add、cas 或 ms 请求中设置 TTL。有关这些请求的更多信息，请参阅 Basic Text Protocol。 route_ttl{ ttl = TTL, child = "POOL_NAME" } 替换以下内容：
TTL：表示新 TTL 值的整数。 POOL_NAME：配置文件 pools{} 块中定义的 pool 名称。
route_failover 将请求串行路由到一组 pool。可以通过传入额外参数来调整此 handler 的行为。 route_failover{ children = POOL_LIST_OR_SET_NAME, failover_count = FAILOVER_COUNT, shuffle = SHUFFLE_BOOLEAN, miss = MISS_BOOLEAN, wait = WAIT_FLOAT, local_zone = ZONE_NAME, } 替换以下内容：
POOL_LIST_OR_SET_NAME：以下之一：
配置文件 pools{} 块中定义的 pool 名称列表，用花括号括起、以逗号分隔——例如 { "cust_pool_1", "cust_pool_2" }。 配置文件 pools{} 块中定义的 set 名称——例如 "set_cust_pools"。
参阅使用 local zones 优先选择路由——如果提供的是带 zone 的 pool set 并且配置了 local_zone，会优先尝试 local zone。 LOCAL_ZONE：覆盖 local zone。 FAILOVER_COUNT：返回错误前尝试列表中其他 pool 的次数。 SHUFFLE_BOOLEAN：如果为 true，代理在路由请求前会随机打乱 pool 列表；否则按给定顺序使用列表。 MISS_BOOLEAN：如果为 true，未命中和错误都算作失败；否则只有错误算作失败。 WAIT_FLOAT：最多等待该秒数后，切换到下一个 pool（允许小数）。
route_ratelim 注意：此 route handler 为实验性功能，参数或行为可能会变化。 此 handler 使用令牌桶算法对发送到子 pool 的请求进行限流。失败时返回“null”响应（参见 route_null）。 route_ratelim{ child = "POOL_NAME", limit = LIMIT, fillrate = FILLRATE, tickrate = MILLISECONDS, global = GLOBAL_BOOLEAN, fail_until_limit = FAIL_UNTIL_BOOLEAN, } 将 POOL_NAME 替换为配置文件 pools{} 块中定义的 pool 名称。
LIMIT：桶的最大容量，以请求数计。 FILLRATE：每经过 fillrate 指定的时间后，向桶中补充的数量。 TICKRATE：每次补充之间的时间间隔，以毫秒为单位。 GLOBAL_BOOLEAN：默认情况下，代理为每个 worker thread 创建一个桶。将此选项设为 true 时，限流对整个进程全局生效，但速度会变慢，因为桶的数据结构由单个 mutex 保护。 FAIL_UNTIL_BOOLEAN：设为 true 时，限流器会反转逻辑：在超出限流阈值之前一直判定为失败。这可用于在服务器繁忙时自动启用代理本地的数据缓存。
route_random 将请求路由到子 pool 列表中随机选中的一个。 route_random{ children = POOL_LIST_OR_SET_NAME, } 将 POOL_LIST_OR_SET_NAME 替换为以下之一：
配置文件 pools{} 块中定义的 pool 名称列表，用花括号括起、以逗号分隔——例如 { "cust_pool_1", "cust_pool_2" }。 配置文件 pools{} 块中定义的 set 名称——例如 "set_cust_pools"。
route_zfailover 注意：此函数已废弃，其功能由 route_failover 和 route_allfastest 提供。 将请求路由到指定名称的 pool set。可以通过传入额外参数来调整此 handler 的行为。
使用此 handler 需要在配置文件中定义 zones。更多信息请参阅使用 local zones 优先选择路由。 route_zfailover{ children = "SET_NAME", stats = true, miss = true } 替换以下内容：
SET_NAME：配置文件 pools{} 块中定义的 pool set 名称。 STATS_BOOLEAN：如果为 true，Memcached 会在 stats proxy 命令的响应中包含 failover 次数统计。 MISS_BOOLEAN：如果为 true，错误和缓存数据缺失都算作失败；否则只有错误算作失败。
将 route handler 限定到特定命令 默认情况下，代理为请求选择路由时不考虑其中的 Memcached 命令。可以通过在 cmdmap{} 调用中包裹 route handler，将路由限定为只处理特定的 Memcached 命令： cmdmap { COMMAND = ROUTE_HANDLER } 替换以下内容：
COMMAND：Memcached 命令——例如 set。命令列表请参阅 Basic Text Protocol。 ROUTE_HANDLER：完整的 route handler 定义——例如 route_direct{ [...] }。
在配置文件中任何 route handler 调用合法的位置都可以使用 cmdmap{}。下面的 map{} 块定义了一条路由，代理只对键前缀为 main 且命令为 set 的请求使用它： map = { main = cmdmap{ set = route_direct{ child = "main_pool", }, }, }, 常见问题 Proxy 设置参考
