filter

# 分页过滤条件解析器

介绍

分页过滤条件解析器是一款用于处理分页请求中过滤参数的工具，核心能力是将前端传递的过滤条件转换为后端可识别的查询逻辑，从而实现数据的精准筛选与分页展示。

该解析器支持两种主流过滤格式，覆盖不同开发场景需求：

• JSON格式：语法简洁、支持复杂逻辑嵌套，适配前端表单过滤场景；
• Google AIP表达式：遵循Google API设计规范，适配标准化API接口场景。

JSON格式

过滤条件以JSON对象/数组形式传递，通过“字段名+操作符”的组合实现多样化查询，无显式操作符时默认执行“等于”逻辑。

基础语法示例

以下为常用基础过滤写法，清晰对应查询语义与等价操作：

逻辑组合规则

支持$and/$or关键字实现逻辑组合，数组内可嵌套基础条件或其他逻辑节点，满足复杂查询场景。

场景1：纯AND组合

需求：部门 ID=1 且 入职时间≥2024-01-01 且 用户名含 “张”

{
  "query": [
    {
      "deptId": 1
    },
    {
      "entryTime__gte": "2024-01-01"
    },
    {
      "userName__icontains": "张"
    }
  ]
}

或者使用$and显式写法：

{
  "query": {
    "$and": [
      {
        "deptId": 1
      },
      {
        "entryTime__gte": "2024-01-01"
      },
      {
        "userName__icontains": "张"
      }
    ]
  }
}

说明：顶层数组默认等价于$and逻辑，简化常规多条件“且”查询写法。

场景2：纯OR组合

需求：部门 ID=1 或 部门 ID=2 或 用户名含 “张”

{
  "query": {
    "$or": [
      {
        "deptId": 1
      },
      {
        "deptId": 2
      },
      {
        "userName__icontains": "张"
      }
    ]
  }
}

场景3：AND嵌套OR

需求：部门 ID=1 且（入职时间≥2024-01-01 或 用户名含 “张”）

{
  "query": {
    "$and": [
      {
        "deptId": 1
      },
      {
        "$or": [
          {
            "entryTime__gte": "2024-01-01"
          },
          {
            "userName__icontains": "张"
          }
        ]
      }
    ]
  }
}

场景4：OR嵌套AND

需求：（部门 ID=1 且 入职时间≥2024-01-01） 或 （部门 ID=2 且 用户名含 “张”）

{
  "query": {
    "$or": [
      {
        "$and": [
          {
            "deptId": 1
          },
          {
            "entryTime__gte": "2024-01-01"
          }
        ]
      },
      {
        "$and": [
          {
            "deptId": 2
          },
          {
            "userName__icontains": "张"
          }
        ]
      }
    ]
  }
}

场景5：多层嵌套

需求：部门 ID=1 且（（入职时间≥2024-01-01 且 入职时间≤2024-12-31）或 用户名含 “张”）且 状态 = active

{
  "query": {
    "$and": [
      {
        "deptId": 1
      },
      {
        "$or": [
          {
            "$and": [
              {
                "entryTime__gte": "2024-01-01"
              },
              {
                "entryTime__lte": "2024-12-31"
              }
            ]
          },
          {
            "userName__icontains": "张"
          }
        ]
      },
      {
        "status": "active"
      }
    ]
  }
}

查找类型（操作符）规范

操作符设计参考Python主流ORM（Tortoise ORM、Django Field lookups ），采用双下划线__分割字段名与操作符，支持JSON嵌套字段查询，语法规则如下：

{字段名}__{查找类型} : {值}
{字段名}.{JSON字段名}__{查找类型} : {值}

通用查找类型

日期时间提取类查找类型

支持从日期时间字段中提取指定维度值进行查询，适配时间维度筛选场景：

AND

Google AIP表达式

遵循AIP-160 Filtering规范，以字符串形式传递过滤条件，适配标准化API接口设计需求。

逻辑运算符

支持二元逻辑运算符，用于组合多个条件：

注意：与多数编程语言不同，OR运算符优先级高于AND。例如a AND b OR c等价于a AND (b OR c)，建议使用显式括号明确逻辑优先级，避免歧义。

否定运算符

比较运算符

注意：与大多数编程语言不同，字段名称必须出现在比较运算符的左侧；右侧只接受字面值和逻辑运算符。

由于过滤器被当作查询字符串接受，因此会进行类型转换，将字符串转换为相应的强类型值：

• 枚举类型，需要枚举类型的字符串表示形式（区分大小写）。
• 布尔值，需要满足true、false字面值要求。
• 数字类型，接受标准的整数或浮点数表示形式。对于浮点数，支持指数（例如2.997e9）。
• 持续时间 Duration ，需要以数字形式表示，后跟一个s后缀（表示秒）。例如：20s，1.2s。
• 时间戳 Timestamp ，需要采用RFC-3339格式的字符串（例如 2012-04-21T11:30:00-04:00）。支持 UTC 偏移量。

遍历算子

通过.（点运算符）实现消息、映射或结构的嵌套遍历：

存在运算符

通过:（冒号运算符）表示“存在匹配”，适用于集合（重复字段、映射）及消息类型，行为随数据类型略有差异：

重复字段查询

用于判断重复结构中是否包含匹配元素：

参考资料

• AIP-160 Filtering （Google官方API过滤规范）
• Tortoise ORM Filtering（ORM过滤语法参考）
• Django Field lookups（ORM字段查找规则参考）