跳至主要內容

自定义条件分页查询

Vison2025/5/14大约 5 分钟commonpageconditiongorm

概述

分页查询是数据检索中常见的功能，在大多数情况下，我们需要通过页码、每页数量、排序等参数来控制查询结果的分页显示。而条件查询则是数据检索中另一个重要的功能，它允许用户通过指定列名、操作符、查询值、逻辑连接符等参数来筛选出符合条件的数据。

下面将详细介绍自定义条件分页查询 API 的参数规则，包括分页参数（页码、每页数量、排序）和条件参数（列名、操作符、查询值、逻辑连接符如 AND/OR）的规则，包括如何通过 columns 数组实现多条件组合与逻辑分组（例如 AND, OR），以实现灵活强大的数据检索功能。

自定义条件分页查询接口参数如下：

{
    "page": 0,
    "limit": 10,
    "sort": "-id",

    "columns": [
          {"name": "language", "exp":"=", "value": "go", "logic": "and"}
    ]
}

参数包括分页和条件两部分，其中分页部分是必填项，条件部分是选填项，具体使用规则如下：

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 无意义，可以不填，但是如果是结束分组，则必须填写。

安全提示

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

性能注意

GORM：采用基于偏移量(offset)的分页查询机制时，当数据表行数较大且查询较深页码时，查询性能将显著下降，请谨慎评估使用场景。使用 ListByLastID 方法的分页查询不会随着表行数增加而变慢的问题。


分组语法说明

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

  • 在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 created_at 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
}

保留字符串类型

在条件查询中，value 值默认会被转换为对应的类型，例如 value = "100" 默认会被转换为数字 100，如果需要保留字符串类型，不想被转换为数字，则可以将 value 值用双引号包裹起来表示字符串类型（value = "\"100\""），示例：

{
    "page": 0,
    "limit": 10,
    "columns": [
        {
            "name": "id",
            "exp": "=",
            "value": "\"100\""
        },
    ]
}

Copyright © 2025 Vison