---
name: search-pattern
when: '搜索, 全文搜索, 搜索功能, 筛选, 过滤, 查询条件, 多条件查询, 动态查询, Elasticsearch, 搜索引擎, 模糊搜索'
scope:
  - backend
  - frontend
products:
  - '*'
id: ka-pattern-search-pattern
asset_kind: pattern
lifecycle_status: active
authority: supporting
routes:
  - '*'
primary_triggers:
  - 搜索
  - 全文搜索
  - 搜索功能
  - 筛选
  - 过滤
  - 查询条件
  - 多条件查询
  - 动态查询
  - Elasticsearch
  - 搜索引擎
  - 模糊搜索
priority: P2
specificity: 3
version: 1.0.0
last_reviewed: '2026-05-22'
consumes: []
emits: []
secondary_triggers: []
negative_triggers: []
type: pattern
status: active
---

## 决策规则
- 列表筛选条件超过 3 个必须封装为 SearchRequest 对象，禁止平铺查询参数
- 动态查询必须使用 MyBatis 动态 SQL 或 JPA Specification，禁止字符串拼接 SQL
- 模糊搜索（LIKE）必须考虑前缀匹配和索引利用，禁止全表扫描 `%keyword%`
- 大数据量全文搜索必须使用 Elasticsearch，禁止数据库 LIKE 性能瓶颈
- 搜索结果必须分页，禁止返回全量匹配结果
- 搜索条件组合必须明确 AND/OR 语义，禁止歧义
- 搜索接口响应时间目标 < 200ms，超过时必须优化（索引/缓存/ES）
- 前端搜索框必须有防抖（建议 300ms），禁止每次按键触发请求
- 搜索接口必须支持分页，禁止无限制返回结果
- 搜索结果必须高亮关键词，提升用户定位效率
- 搜索字段必须建立索引（Elasticsearch mapping 或数据库索引），禁止全表扫描
- 搜索关键词必须做长度限制和特殊字符过滤，防止恶意查询
- 搜索结果必须按相关度排序，支持用户自定义排序条件

## 验收项
- [AC-01] 筛选条件封装为对象
- [AC-02] 动态查询无 SQL 拼接
- [AC-03] 搜索结果分页
- [AC-04] 搜索接口响应 < 200ms
- [AC-05] 前端搜索有防抖
- [AC-06] 搜索接口分页
- [AC-07] 关键词高亮
- [AC-08] 搜索字段有索引
