REST API中大于/小于过滤的URL设计及组合过滤实现方案

一、比较条件过滤的常见合规设计方式 #

针对大于、小于这类比较过滤，有两种被广泛采用的合规方案，完全符合URL查询字符串规范：

1. 字段名+操作符后缀

用约定的后缀区分操作类型，通常用双下划线分隔字段和操作符（避免和字段名本身的下划线冲突），常见操作符后缀：

• __gt：大于（greater than）
• __lt：小于（less than）
• __gte：大于等于
• __lte：小于等于
• __eq：等于（可选，默认不加后缀即为等于逻辑）

示例：

• 筛选连接数大于2的部件：/widgets?connections__gt=2
• 筛选连接数小于等于5的部件：/widgets?connections__lte=5
• 筛选屏幕数恰好为1的部件：/widgets?screen__eq=1（或直接写/widgets?screen=1）

这种方式语义清晰，主流开发框架（比如Django REST Framework）原生支持，也容易被开发者快速理解。

2. 独立参数命名

针对每个比较维度单独命名参数，比如用Min/Max后缀明确范围：

• 筛选连接数大于2：/widgets?connectionsMin=2
• 筛选连接数小于5：/widgets?connectionsMax=5
• 筛选屏幕数为1：/widgets?screen=1

这种方式更直白，适合面向技术背景较弱的调用者的场景，但参数数量会随过滤维度增加而变多。

二、组合过滤的实现方案 #

组合过滤的核心是明确逻辑关系（默认多参数为AND，按需支持OR），以下是两种常用方式：

1. 默认多参数为AND逻辑

最常见的设计是：当同时传递多个过滤参数时，默认执行逻辑与操作。

示例（连接数大于2且屏幕数恰好为1）：
/widgets?connections__gt=2&screen=1

这种方式简单直接，覆盖绝大多数常见场景，开发者无需额外学习成本。

2. 显式指定逻辑关系（支持OR/复杂组合）

如果需要支持OR或者更复杂的逻辑组合，可以通过以下方式实现：

• 逻辑前缀标识：给参数加前缀区分逻辑组，比如用or_前缀标识该参数属于OR分支：
  示例（连接数大于2 或 屏幕数为1）：
  /widgets?or_connections__gt=2&or_screen=1
  注：这种方式适合简单的OR场景，复杂嵌套逻辑会变得繁琐。

• 过滤表达式参数：用单个参数传递结构化的过滤表达式，比如用URL编码的JSON字符串，或自定义简单语法：
  示例（用JSON表达“(连接数>2 且 屏幕数=1) 或 价格<100”）：
  /widgets?filter=%7B%22or%22%3A%5B%7B%22and%22%3A%5B%7B%22connections%22%3A%7B%22gt%22%3A2%7D%7D%2C%7B%22screen%22%3A1%7D%5D%7D%2C%7B%22price%22%3A%7B%22lt%22%3A100%7D%7D%5D%7D
  或者用更简洁的自定义语法：
  /widgets?filter=(connections>2&screen=1)|price<100
  这种方式支持任意复杂逻辑，但需要前后端约定语法规则，后端也要实现对应的表达式解析逻辑。

注意事项 #

• 保持命名风格统一：要么全用后缀式，要么全用独立参数名，不要混用。
• 提供清晰的API文档：明确说明支持的操作符、逻辑规则，让调用者一目了然。

内容的提问来源于stack exchange，提问作者Anna