Avo动态过滤器：自定义查询与默认过滤系统的互斥设计

在Avo框架的动态过滤器功能中，一个重要的设计决策引起了开发者社区的讨论：当开发者使用自定义query块时，默认的过滤系统是否应该继续生效。本文将深入探讨这一设计问题的背景、解决方案及其技术实现。

问题背景

在Avo的动态过滤器实现中，当开发者使用query块自定义查询逻辑时，框架默认会在自定义查询之前先应用基础的过滤系统。这一设计初衷是为了支持某些特定场景下的组合使用需求，比如同时使用自定义查询和常规文本过滤器。

然而，这种设计在实际使用中引发了一些困惑。开发者通常期望当覆盖query方法时，能够获得完全的控制权，而不希望有任何隐式的预处理逻辑在背后运行。这种预期与Ruby语言中方法覆盖的常规理解一致——当你覆盖一个方法时，你期望完全接管其行为。

技术分析

默认过滤系统和自定义查询同时存在的设计主要面临以下问题：

1. 行为不透明性：开发者难以直观理解查询的完整执行流程
2. 性能影响：不必要的预处理可能增加查询复杂度
3. 调试困难：当查询结果不符合预期时，排查过程复杂化

解决方案

经过社区讨论和技术评估，Avo团队决定采用以下改进方案：

1. 互斥原则：当使用query块时，默认过滤系统将不再自动应用
2. 显式控制：开发者可以在自定义查询中按需调用默认过滤逻辑

这种设计既满足了开发者对完全控制的需求，又保留了组合使用的灵活性。以下是典型的使用示例：

dynamic_filter :custom_population,
  query_attributes: :population,
  query: -> {
    # 完全自定义的查询逻辑
    query.where("population > ?", 1000000)
  }

如果需要结合默认过滤逻辑，可以这样实现：

dynamic_filter :custom_population,
  query_attributes: :population,
  query: -> {
    # 先应用默认过滤
    apply_default_filters
    
    # 再添加自定义条件
    query.where("population > ?", 1000000)
  }

实现细节

在技术实现上，这一改进主要涉及以下变更：

1. 修改动态过滤器的查询构建流程，检测query块的存在
2. 当query块存在时，跳过默认过滤系统的自动应用
3. 提供apply_default_filters方法作为显式调用接口

这种实现方式保持了向后兼容性，同时提供了更清晰的API边界。开发者可以明确知道他们的查询何时会受到影响，以及如何控制这些影响。

最佳实践

基于这一改进，建议开发者在以下场景中使用不同的策略：

1. 完全控制场景：直接使用query块编写完整查询逻辑
2. 扩展默认功能场景：在query块中先调用apply_default_filters，再添加额外条件
3. 简单过滤场景：继续使用默认过滤系统，无需自定义query

这种分层设计使得Avo的动态过滤器功能既能满足简单需求，又能处理复杂场景，同时保持了API的简洁性和可预测性。

总结

Avo动态过滤器的这一改进体现了框架设计中的一个重要原则：显式优于隐式。通过让开发者明确选择何时应用默认逻辑，而不是在背后自动执行，框架提供了更清晰的行为和更好的可维护性。这种设计决策虽然看似微小，但对于构建可预测、易维护的应用程序界面至关重要。