如何实现API文档的列表搜索过滤、千份文档同页分页及全量检索

核心实现原则 #

所有逻辑拆分数据源层、交互层处理，禁止直接修改原始拉取的全量文档数据，所有过滤、分页操作都基于原始数据生成派生结果，这是过滤功能失效的最常见诱因。

一、搜索词列表过滤功能（针对你当前遇到的过滤失效问题） #

根据你的API能力二选一实现即可：

• 优先选服务端过滤方案（性能最优）
  接口请求时直接携带搜索关键词参数，由后端完成全量文档匹配后返回结果，前端拿到结果直接渲染，不需要做二次遍历。常规请求格式参考：

  GET /api/document/list?keyword=搜索词&pageNum=1&pageSize=20
  

• 前端本地过滤方案（API不支持服务端检索时用）
  1. 页面初始化时，把接口返回的1000条原始文档存入独立变量rawDocList，全程只读不修改
  2. 给搜索输入框加300ms防抖，避免输入过程中频繁触发计算导致卡顿
  3. 统一做匹配规则处理：关键词统一转小写、去除首尾空格，匹配范围覆盖你需要检索的字段（标题、正文摘要、标签等）
     参考实现代码：

  // 防抖工具函数
  const debounce = (func, delay = 300) => {
    let timer = null
    return (...args) => {
      clearTimeout(timer)
      timer = setTimeout(() => func.apply(this, args), delay)
    }
  }
  
  // 原始全量数据，初始化接口请求完成后赋值，后续只读
  let rawDocList = []
  // 当前过滤后的结果集，分页基于这个变量处理
  let currentFilteredList = []
  let currentPage = 1
  const pageSize = 20
  
  // 过滤逻辑
  const handleFilter = (keyword) => {
    const trimKey = keyword.trim().toLowerCase()
    if (!trimKey) {
      currentFilteredList = [...rawDocList]
      return
    }
    currentFilteredList = rawDocList.filter(doc => {
      // 按需增减需要匹配的字段
      return doc.title.toLowerCase().includes(trimKey) 
        || doc.summary.toLowerCase().includes(trimKey)
        || doc.tags.some(tag => tag.toLowerCase().includes(trimKey))
    })
    // 过滤完成后重置到第一页
    currentPage = 1
  }
  
  // 绑定搜索框事件
  document.querySelector('#search-input').addEventListener('input', debounce((e) => {
    handleFilter(e.target.value)
    renderCurrentPageList()
  }))
  

  过滤失效高频排查点：
  • 把过滤结果直接赋值给了rawDocList，导致原始全量数据被覆盖，后续检索只能在已过滤的子集里匹配
  • 没有做关键词大小写、首尾空格统一处理，导致存在匹配漏项
  • 过滤后没有重置页码，结果被分页截断，误以为过滤没生效

二、1000份文档的分页功能实现 #

不要一次性把1000条文档全部渲染到DOM，会导致页面卡顿甚至崩溃，基于过滤后的结果集做切片分页即可：

// 渲染当前页列表+分页器
const renderCurrentPageList = () => {
  const total = currentFilteredList.length
  const totalPage = Math.ceil(total / pageSize)
  // 边界处理：当前页码大于总页数时自动回到最后一页
  if (currentPage > totalPage) currentPage = totalPage
  // 切片获取当前页数据
  const startIdx = (currentPage - 1) * pageSize
  const currentPageData = currentFilteredList.slice(startIdx, startIdx + pageSize)
  // 替换列表DOM内容
  document.querySelector('#doc-list').innerHTML = buildListHtml(currentPageData)
  // 渲染分页控件
  document.querySelector('#pagination').innerHTML = buildPaginationHtml(totalPage, currentPage)
}

// 分页切换事件
const handlePageChange = (targetPage) => {
  const totalPage = Math.ceil(currentFilteredList.length / pageSize)
  if (targetPage < 1 || targetPage > totalPage) return
  currentPage = targetPage
  renderCurrentPageList()
}

三、全量文档检索覆盖实现 #

• 若文档总量长期维持在1000条左右：页面初始化时拉取全量文档的检索必要字段（文档ID、标题、摘要、标签，不需要拉取完整大体积正文）存入rawDocList作为本地检索底库即可
• 若文档总量后续会持续增长超过1000条：放弃前端本地检索方案，直接由后端实现全量文档的全文检索能力，前端只传搜索词、页码参数，拿对应页的结果渲染即可，避免前端加载数据量过大导致页面性能问题。

调试技巧：过滤功能异常时，先在控制台打印rawDocList.length和currentFilteredList.length，如果rawDocList长度和接口返回的总文档数不一致，说明原始数据被修改，直接定位问题。

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