自定义条件分页查询

自定义条件分页查询接口参数包括分页和条件两部分，具体使用规则如下：

1. 分页参数（必填项）

参数名	必填	说明	示例
page	否	页码，从0开始计数	0（第一页）
limit	是	每页数据量（1-1000）	10
sort	否	排序规则： • 字段(表列名)前加-表示降序 • 多字段用逗号分隔 • 默认是降序	-id

提示

当未指定sort参数且表中存在id列时，系统默认按id降序排序。

2. 条件参数（选填项）

采用columns数组结构，支持多条件组合查询：

参数名	必填	说明	默认值
name	是	数据库列名	-
exp	否	运算符：=, !=, >, >=, <, <=, in, like, notin, isnull, isnotnull	=
value	是	查询值： • in/notin时用逗号分隔多个值 • isnull/isnotnull时可留空	-
logic	否	逻辑连接符： • and/or • 追加:(或:)实现逻辑分组	and

提示

最后一个条件的 logic 无意义，可以不填，但是如果是结束分组，则必须填写。

注意

对于 mongodb，如果 value 类型为 object id 时，对应的 name 名称后缀必须添加:oid标记，例如 user_id:oid，对于 gorm 不需要添加 :oid 标记，这是 mongodb 和 gorm 两者唯一区别。

安全提示

• GORM 实现：对分页查询参数执行严格的输入验证，有效防范 SQL 注入风险，确保系统安全稳定
• MongoDB 实现：除基础参数校验外，还支持对字段值的自定义验证规则，提供更灵活的安全保障

性能注意

Gorm： 采用基于偏移量(offset)的分页查询机制时，当数据表行数较大且查询较深页码时，查询性能将显著下降，请谨慎评估使用场景。

分组语法说明

在使用分组条件时，必须明确指定成对的括号 ( 和 )，并遵循以下规则：

• 在and / or 基础上通过拼接(和)表示分组开始或结束，例如:(后缀表示开始分组，:)后缀表示结束分组。
• 括号必须正确嵌套，成对出现。

示例：

{
    "columns": [
        {"name": "foo1", "value": "bar1", "logic": "and"},
        {"name": "foo2", "value": "bar2", "logic": "or:("},  // 可以理解为 {"group":"(", "name": "foo2", "value": "bar2", "logic": "or"}
        {"name": "foo3", "value": "bar3", "logic": "and:)"}  // 可以理解为 {"name": "foo3", "value": "bar3", "logic": "and", "group": ")"}
    ]
}

• 等价 SQL：

  WHERE foo1 = 'bar1' AND  ( foo2 = 'bar2' OR foo3 = 'bar3' )

• 等价 mongodb 查询：

  {
      "foo1": "bar1",
      "$or": [
          {"foo2": "bar2"},
          {"foo3": "bar3"}
      ]
  }

典型示例

示例 1

查询前10条新用户数据，API 接口请求参数如下：

{
    "page": 0,
    "limit": 10,
    "sort": "-created_at"
}

• 等价 SQL：

  ORDER BY id DESC
  LIMIT 10 OFFSET 0

• 等价 MongoDB 查询：

  {
      "sort": { "created_at": -1 },
      "skip": 0,
      "limit": 10
  }

示例 2

查询大于20岁的男性的用户, API 接口请求参数如下：

{
    "page": 0,
    "limit": 10,
    "columns": [
        {
            "name": "age",
            "exp": ">",
            "value": 20
        },
        {
            "name": "gender",
            "value": "male"
        }
    ]
}

• 等价 SQL：

  WHERE age > 20 AND gender = 'male'
  ORDER BY id DESC
  LIMIT 10 OFFSET 0

• 等价 MongoDB 查询：

  {
      "filter": {
          "age": { "$gt": 20 },
          "gender": "male"
      },
      "sort": { "_id": -1 },
      "skip": 0,
      "limit": 10
  }

示例 3

查询研发部门工资大于等于10000的员工，或者部门为市场部并且级别为3、4、5的员工，API 接口请求参数如下：

{
    "page": 0,
    "limit": 20,
    "sort": "-created_at",
    "columns": [
          {"name": "dept", "value": "rd", "logic": "and:("},
          {"name": "salary", "exp": ">=", "value": "10000", "logic": "or:)"},
          {"name": "dept", "value": "mkt", "logic": "and:("},
          {"name": "level", "exp": "in", "value": "3,4,5", "logic": "and:)"}
    ]
}

• 等价 SQL：

  WHERE (dept = 'rd' AND salary >= 10000) OR (dept = 'mkt' AND level IN (3,4,5))
  ORDER BY created_at DESC
  LIMIT 20 OFFSET 0

• 等价 MongoDB 查询：

  {
      "filter": {
          "$or": [
              { "dept": "rd", "salary": { "$gte": 10000 } },
              { "dept": "mkt", "level": { "$in": [3,4,5] } }
          ]
      },
      "sort": { "created_at": -1 },
      "skip": 0,
      "limit": 20
  }