开箱即用的 GoWind Admin｜风行，企业级前后端一体中后台框架：列表查询规则指南

在企业级中后台系统中，列表查询是贯穿“数据管理、业务审核、统计分析”的核心高频场景——从用户列表的多条件筛选，到订单数据的时间区间查询，再到报表的排序分页，其易用性与灵活性直接决定研发效率与业务操作体验。风行·GoWind Admin 作为开箱即用的 Go 语言后台管理系统，以“降低开发成本、提升研发效率”为核心设计理念，针对性打造了一套“配置化、高兼容、可扩展”的列表查询规则，让开发者无需关注底层 SQL 实现，仅通过简单配置即可完成复杂查询需求。

一、核心设计理念：声明式语法与 Go 生态适配

GoWind Admin 列表查询规则的设计，深度借鉴了 Python 生态中 Django ORM、SQLAlchemy 等优秀框架的“声明式语法”核心思想——通过贴近自然语言的配置方式屏蔽底层数据访问细节，让开发者聚焦业务逻辑而非 SQL 拼接。但不同于简单照搬，我们基于 Go 语言“强类型、高性能”的特性做了全链路适配，最终实现“简洁直观”与“原生兼容”的平衡：

• 屏蔽底层差异：统一封装多数据库（MySQL、PostgreSQL、Oracle 等）的查询语法差异，配置式查询规则可跨数据库复用，避免开发者适配不同数据库的重复工作。
• 强化类型安全：基于 Go 强类型特性设计查询参数校验机制，避免动态 SQL 拼接带来的类型错误与注入风险。
• 低心智负担：采用“字段名+操作符”的简洁配置格式，无需编写繁琐 SQL，新手也能快速上手。
• 灵活扩展兼容：支持原生 SQL 扩展、自定义查询函数，既满足开箱即用的简单需求，也能适配复杂业务场景。

简言之，GoWind Admin 列表查询规则的核心目标是：让后台列表开发从“重复编码”转变为“配置化组装”，兼顾效率与灵活性。

二、通用列表查询请求：统一参数规范

GoWind Admin 定义了标准化的列表查询请求参数，所有列表接口均遵循此规范，确保前后端交互的一致性。参数支持多条件组合过滤、动态排序、分页控制、字段筛选等核心能力，具体说明如下：

参数传递说明：所有 JSON 格式的参数（query、or、orderBy）需进行 URL 编码后传递，避免特殊字符导致解析失败。例如：query=%7B%22userName%22%3A%22admin%22%7D

三、排序规则：简洁直观的排序配置

排序规则基于 SQL 的 ORDER BY 语法设计，通过简单的“字段名前缀标识”实现升序/降序控制，支持多字段组合排序，完全适配业务中复杂的排序需求。

3.1 核心规则

• 升序：直接传入字段名（无前缀），如 "createTime" 对应 SQL：ORDER BY createTime ASC。
• 降序：字段名前加“-”前缀，如 "-createTime" 对应 SQL：ORDER BY createTime DESC。
• 多字段排序：按数组顺序依次排序（优先级递减），如 ["-createTime", "userId"] 对应 SQL：ORDER BY createTime DESC, userId ASC。

3.2 典型场景示例

四、过滤规则：灵活强大的条件筛选

过滤规则是列表查询的核心，对应 SQL 中的 WHERE 条件。GoWind Admin 支持“基础等值筛选”与“高级条件筛选”，高级筛选通过“字段名__操作符”的双下划线分隔语法实现，覆盖模糊搜索、区间查询、正则匹配等全场景需求。

4.1 基础语法规则

• 基础等值筛选：直接使用 {"字段名": "值"}，如 {"status": 1} 对应 SQL：WHERE status = 1。
• 高级条件筛选：使用 {"字段名__操作符": "值"}，如 {"createTime__gte": "2024-01-01"} 对应 SQL：WHERE createTime >= '2024-01-01'。
• JSON 字段筛选：支持嵌套 JSON 字段的筛选，语法为 {"字段名.嵌套JSON字段名__操作符": "值"}，如 {"extInfo.phone__contains": "138"} 对应 SQL：WHERE extInfo->>'$.phone' LIKE '%138%'（PostgreSQL 示例）。

4.2 完整操作符列表（按功能分类）

4.2.1 基础逻辑与等值操作

4.2.2 数值/时间区间操作

4.2.3 字符串模糊匹配操作

4.2.4 正则匹配操作

4.2.5 日期时间提取操作

支持从日期时间字段中提取年、月、日、小时等维度进行筛选，适配按时间维度统计的业务场景：

4.3 过滤规则避坑指南

1. 日期区间查询注意事项：日期字符串（如“2024-01-01”）会被隐式转换为“2024-01-01 00:00:00”，若需查询当天全量数据，建议使用 createTime__range: ["2024-01-01", "2024-01-01 23:59:59"]，避免遗漏当天后半段数据。
2. 模糊匹配性能优化：contains、endswith 等操作无法命中普通索引，数据量大时建议使用全文检索（如 Elasticsearch）替代，或为字段建立专用模糊索引。
3. 跨数据库兼容性：icontains、istartswith 等不区分大小写的操作，在 MySQL 中需开启 lower_case_table_names 配置，否则可能出现大小写区分的情况。
4. 正则匹配慎用：正则匹配（regex、iregex）性能较差，且跨数据库语法差异大，非必要不使用；若需使用，建议简化正则表达式。

五、典型业务场景实操示例

结合前文规则，以下是3个高频业务场景的完整查询配置示例，覆盖多条件筛选、排序分页、字段筛选等核心能力，可直接参考落地：

5.1 场景1：多条件筛选用户列表（分页+排序）

业务需求：查询“部门ID=1”且“入职时间在2024年1月1日之后”且“用户名包含‘张’”的用户，按入职时间倒序排序，每页20条，查询第2页，仅返回ID、用户名、入职时间字段。

// 请求参数（已URL编码前）
{
   
  "page": 2,
  "pageSize": 20,
  "query": [
    {
   "deptId": 1},
    {
   "entryTime__gte": "2024-01-01"},
    {
   "userName__icontains": "张"}
  ],
  "orderBy": ["-entryTime"],
  "fieldMask": "id,userName,entryTime"
}

对应 SQL 核心片段：

SELECT id, userName, entryTime 
FROM user 
WHERE deptId = 1 
  AND entryTime >= '2024-01-01' 
  AND userName ILIKE '%张%' 
ORDER BY entryTime DESC 
LIMIT 20 OFFSET 20;

5.2 场景2：订单列表OR条件筛选（不分页）

业务需求：查询“订单状态=待支付”或“订单金额>10000”的全量订单，按订单金额降序排序。

// 请求参数（已URL编码前）
{
   
  "noPaging": true,
  "or": [
    {
   "status": 1}, // 1=待支付
    {
   "amount__gt": 10000}
  ],
  "orderBy": ["-amount"]
}

5.3 场景3：按日期维度筛选报表数据

业务需求：查询“2024年2季度”且“每周一创建”的销售报表数据。

// 请求参数（已URL编码前）
{
   
  "query": [
    {
   "createTime__year": "2024"},
    {
   "createTime__quarter": "2"},
    {
   "createTime__week_day": "1"} // 1=周一（不同数据库可能有差异，需适配）
  ]
}

六、扩展说明：自定义查询逻辑

GoWind Admin 列表查询规则支持自定义扩展，以适配复杂业务场景（如多表关联查询、自定义函数计算等）：

• 原生 SQL 扩展：通过 customSql 参数传入自定义 SQL 片段（需后端开启白名单配置），如：customSql="AND (userName LIKE '%张%' OR realName LIKE '%张%')"。
• 自定义查询函数：后端可注册自定义查询处理器，支持复杂逻辑计算（如按地理位置筛选、按权限数据过滤等），前端通过约定的操作符调用。
• 多表关联查询：通过后端配置关联表映射关系，前端可直接按“关联表字段名操作符”的格式筛选关联数据（如 `{"dept.namecontains": "技术部"}` 查询所属技术部的用户）。

七、项目源码与参考资料

7.1 项目源码

• Gitee（国内访问速度快）：https://gitee.com/tx7do/go-wind-admin
• GitHub：https://github.com/tx7do/go-wind-admin

7.2 参考资料

• Django ORM 过滤规则：https://docs.djangoproject.com/en/4.2/ref/models/querysets/#field-lookups
• Tortoise ORM 过滤规则：https://tortoise.github.io/query.html#filtering
• GoWind Admin 后端查询扩展文档：http://localhost:7788/docs/openapi.yaml（本地部署后访问）