Stooland Docs

Appearance

query-filter 使用指南（团队约定） ​

本指南统一说明在业务列表接口中使用 query-filter 进行筛选、排序与分页的推荐范式，确保各模块行为一致、代码可读。

快速开始 ​

js
import queryFilter, { KeyType, ListOrder, SortBy, DEFAULT_PAGE_FIRST, DEFAULT_PAGE_SIZE } from '@/api/base/query-filter'

queryFilter.init()
// 可选：分页
queryFilter.page = DEFAULT_PAGE_FIRST
queryFilter.pageSize = DEFAULT_PAGE_SIZE
// 设定筛选条件（支持多个）
queryFilter.setQuery([
  { keyBy: 'status', keyValue: 1, keyType: KeyType.EQ },
  { keyBy: 'id',     keyValue: '100,101,102', keyType: KeyType.IN }
])
// 设定排序
queryFilter.sortBy = 'id' // 或 SortBy.CREATE_TIME / UPDATE_TIME / LIST_ORDER
queryFilter.listOrder = ListOrder.DESC

// 传给任意 *Index 列表接口
const res = await someIndexApi(queryFilter.getFilters())

常见筛选模式 ​

  • 等值匹配（eq）

    • 用途：精确匹配某个字段值
    • 用法：{ keyBy: 'platform', keyValue: 'douyin', keyType: KeyType.EQ }

  • 模糊匹配（like）

    • 用途：关键字搜索（名称、标题、标签等）
    • 用法：{ keyBy: 'keyword', keyValue: '风景', keyType: KeyType.LIKE }
    • 说明：后端通常按 SQL LIKE 语义处理；无需显式加 %（如接口有特殊约定，可按接口文档补充）。

  • 集合匹配（in / not_in）

    • 用途：匹配一组 ID 或状态集合
    • 用法：{ keyBy: 'id', keyValue: '1,2,3', keyType: KeyType.IN }
    • 推荐：若前端拿到数组，可先 array.join(',') 再赋值给 keyValue。

  • 区间匹配（between / not_between）

    • 用途：时间范围、数值范围
    • 用法：{ keyBy: 'create_time', keyValue: '1727606400,1728211200', keyType: KeyType.BETWEEN }
    • 说明：区间值使用英文逗号分隔；时间字段传时间戳或后端约定的格式。

  • 比较匹配（gt / egt / lt / elt / neq）

    • 用途：>、≥、<、≤、!=
    • 用法：{ keyBy: 'score', keyValue: 90, keyType: KeyType.GT }

排序范式 ​

  • 统一写法

    • queryFilter.sortBy = 'id' 或使用 SortBy 预定义常量（CREATE_TIME/UPDATE_TIME/LIST_ORDER）
    • queryFilter.listOrder = ListOrder.DESC 或 ASC

  • 团队约定

    • 若无特别业务要求，列表默认使用 id desc，以保证“最新优先”的一致体验。

分页范式 ​

  • 推荐：列表页开启分页，导出/小列表场景可不分页
  • 示例
    js
    queryFilter.page = DEFAULT_PAGE_FIRST // 1
queryFilter.pageSize = DEFAULT_PAGE_SIZE // 50（可按模块定制）

组合条件（多条件 AND） ​

  • setQuery 支持一次设置多个条件，内部会使用 ~ 将 kb/kv/kt 串联，后端按约定解析为 AND 组合：
    js
    queryFilter.setQuery([
  { keyBy: 'platform', keyValue: 'douyin', keyType: KeyType.EQ },
  { keyBy: 'storyboard_id', keyValue: 123, keyType: KeyType.EQ },
  { keyBy: 'status', keyValue: 'ready,done', keyType: KeyType.IN }
])

关联对象筛选（可选） ​

  • 若接口支持“关联条件”，可使用以下字段：
    • hasKey：关联对象名（如 topic）
    • hasKeyBy：关联对象字段（如 name）
    • hasKeyValue：关联字段值（同样支持逗号分隔）
    • hasKeyType：匹配类型（同 KeyType）
  • 示例（仅在接口有该能力时使用）：
    js
    queryFilter.hasKey = 'topic'
queryFilter.hasKeyBy = 'name'
queryFilter.hasKeyValue = '风景'
queryFilter.hasKeyType = KeyType.LIKE

常见场景示例 ​

  • 拉取最新发布记录（最新优先）

    js
    queryFilter.init()
queryFilter.setQuery([
  { keyBy: 'storyboard_id', keyValue: storyboardId, keyType: KeyType.EQ },
  { keyBy: 'platform', keyValue: platform, keyType: KeyType.EQ }
])
queryFilter.sortBy = 'id'
queryFilter.listOrder = ListOrder.DESC
const res = await materialStoryboardPublishIndex(queryFilter.getFilters())

  • 关键字 + 时间范围 + 分页

    js
    queryFilter.init()
queryFilter.page = 1
queryFilter.pageSize = 20
queryFilter.setQuery([
  { keyBy: 'keyword', keyValue: keyword, keyType: KeyType.LIKE },
  { keyBy: 'create_time', keyValue: `${startTs},${endTs}`, keyType: KeyType.BETWEEN }
])
queryFilter.sortBy = SortBy.CREATE_TIME
queryFilter.listOrder = ListOrder.DESC
const res = await someIndexApi(queryFilter.getFilters())

  • 批量按 ID 查询（IN）

    js
    queryFilter.init()
const ids = [101, 203, 309]
queryFilter.setQuery([
  { keyBy: 'id', keyValue: ids.join(','), keyType: KeyType.IN }
])
const res = await someIndexApi(queryFilter.getFilters())

注意事项 ​

  • 每次使用前务必调用 queryFilter.init()，避免不同调用间共享状态。
  • IN/区间（BETWEEN）等复合值使用英文逗号连接，前后端需在接口层保持统一约定。
  • LIKE 的匹配策略由后端决定；一般无需在前端手动添加 %。
  • 排序未设定时，可能由后端默认排序决定；建议显式设定以获得稳定结果。
  • 分页不设定时，后端可能返回全部数据；列表页建议显式开启分页。

推荐引用路径 ​

js
import queryFilter, { KeyType, ListOrder, SortBy } from '@/api/base/query-filter'

若模块未配置 @ 别名或必须使用相对路径，请以项目中现有写法为准。