implementing-search-filter

搜索与筛选实现

使用全面的前端组件和后端查询优化，实现搜索和筛选界面。

用途

此技能提供可用于生产环境的模式，帮助在全栈中实现搜索和筛选功能。涵盖前端的 React/TypeScript 组件（搜索输入框、筛选界面、自动补全），以及后端的 Python 模式（SQLAlchemy 查询、Elasticsearch 集成、API 设计）。此技能着重介绍性能优化、无障碍访问和用户体验。

适用场景

• 构建带有类别和价格筛选的商品搜索
• 实现自动补全/输入提示搜索
• 创建带有动态计数的分面搜索界面
• 为数据表或列表添加搜索功能
• 为高级用户构建高级布尔搜索
• 使用 SQLAlchemy 或 Django ORM 实现后端搜索
• 集成 Elasticsearch 以实现全文搜索
• 通过防抖和缓存优化搜索性能
• 创建无障碍搜索体验

核心组件

前端搜索模式

带防抖的搜索输入框

• 实现 300ms 防抖以提升性能
• 搜索期间显示加载状态
• 提供清除按钮（X）以重置
• 提供键盘快捷键（Cmd/Ctrl+K）
• 参见 references/search-input-patterns.md

自动补全/输入提示

• 提供支持键盘导航的建议下拉列表
• 在建议中突出显示匹配文本
• 提供最近搜索和热门项目
• 使用防抖避免请求过载
• 参见 references/autocomplete-patterns.md

筛选 UI 组件

• 使用复选框筛选器进行多选
• 使用范围滑块筛选数值
• 使用下拉筛选器进行单选
• 使用筛选标签显示当前启用的筛选项
• 参见 references/filter-ui-patterns.md

后端查询模式

数据库查询构建

• 使用 SQLAlchemy 动态构建查询
• 使用 Django ORM 链式添加筛选条件
• 优化搜索列的索引
• 在 PostgreSQL 中进行全文搜索
• 参见 references/database-querying.md

Elasticsearch 集成

• 文档索引策略
• 用于复杂搜索的查询 DSL
• 分面聚合
• 相关性评分和加权
• 参见 references/elasticsearch-integration.md

API 设计

• RESTful 搜索端点
• 查询参数验证
• 使用游标或偏移量进行分页
• 响应缓存策略
• 参见 references/api-design.md

实现工作流

客户端搜索（少于 1000 个项目）

1. 将数据加载到内存中
2. 使用 JavaScript 实现筛选函数
3. 对文本输入应用防抖搜索
4. 即时更新结果
5. 在 React 中维护筛选状态

服务端搜索（多于 1000 个项目）

1. 设计搜索 API 端点
2. 验证并清理查询参数
3. 动态构建数据库查询
4. 应用分页
5. 返回带有元数据的结果
6. 缓存频繁执行的查询

混合方案

1. 使用客户端筛选提供即时反馈
2. 在后台获取服务端结果
3. 合并结果并去重
4. 逐步更新 UI
5. 在本地缓存最近搜索

性能优化

前端优化

防抖实现

• 使用 lodash 中的 debounce 或自定义实现
• 有新输入时取消待处理请求
• 获取数据期间显示骨架屏加载器
• 脚本：scripts/debounce_calculator.js

查询参数管理

• 将筛选条件与 URL 同步，以便分享搜索
• 使用 React Router 或 Next.js 管理 URL 状态
• 压缩复杂查询
• 参见 references/query-parameter-management.md

后端优化

查询优化

• 创建合适的数据库索引
• 使用查询分析器识别瓶颈
• 实现查询结果缓存
• 脚本：scripts/generate_filter_query.py

验证与安全

• 清理所有搜索输入
• 防止 SQL 注入
• 限制搜索端点的请求速率
• 脚本：scripts/validate_search_params.py

无障碍要求

ARIA 模式

• 搜索区域使用 role="search"
• 使用 aria-live 更新结果
• 为筛选器提供清晰的标签
• 支持仅使用键盘进行导航

键盘支持

• 使用 Tab 键遍历所有交互元素
• 使用方向键浏览自动补全选项
• 按 Escape 键关闭下拉菜单
• 按 Enter 键选择／提交

技术栈

前端库

主要方案：Downshift（自动补全）

• 提供无障碍自动补全基础组件
• 无头／无样式设计，灵活性高
• 符合 WAI-ARIA 标准
• 安装：npm install downshift

替代方案：React Select

• 功能齐全的选择／筛选组件
• 内置异步搜索
• 支持多选

后端技术

Python/SQLAlchemy

• 动态构建查询
• 优化关系加载
• 查询结果分页

Python/Django

• Django Filter 后端
• Django REST Framework 筛选器
• 使用 PostgreSQL 进行全文搜索

Elasticsearch（Python）

• elasticsearch-py 客户端
• 使用 elasticsearch-dsl 构建查询

捆绑资源

参考资料

• references/search-input-patterns.md - 输入框实现
• references/autocomplete-patterns.md - 输入提示模式
• references/filter-ui-patterns.md - 筛选组件
• references/database-querying.md - SQL 查询模式
• references/elasticsearch-integration.md - Elasticsearch 设置
• references/api-design.md - API 端点模式
• references/performance-optimization.md - 性能优化建议
• references/library-comparison.md - 库评估

脚本

• scripts/generate_filter_query.py - 构建 SQL/ES 查询
• scripts/validate_search_params.py - 验证输入
• scripts/debounce_calculator.js - 计算防抖时间

示例

• examples/product-search.tsx - 电商搜索
• examples/autocomplete-search.tsx - 自动补全实现
• examples/sqlalchemy_search.py - SQLAlchemy 模式
• examples/fastapi_search.py - FastAPI 搜索端点
• examples/django_filter_backend.py - Django 筛选器

资源文件

• assets/filter-config-schema.json - 筛选器配置
• assets/search-api-spec.json - OpenAPI 规范