Реализация поиска с автодополнением для веб-приложения

Реализация поиска с автодополнением для веб-приложения

Автодополнение — поле поиска которое показывает подсказки по мере ввода. Технически это пересечение нескольких задач: быстрый fuzzy-поиск по индексу, debounce чтобы не перегружать сервер, корректная работа с клавиатурой (ARIA combobox), отмена устаревших запросов. Каждая из них решается отдельно, вместе они составляют полноценный компонент.

Архитектура поиска

Client-side — данные загружаются разом, поиск в браузере. Подходит до ~50 000 записей. Библиотеки: Fuse.js (fuzzy), MiniSearch (полнотекстовый). Нет latency после загрузки.

Server-side — каждый ввод — запрос к серверу. Нужен debounce и отмена запросов. Подходит для больших данных. Elasticsearch suggest API, Typesense, PostgreSQL trgm.

Гибридный — кешируем популярные запросы в памяти, редкие идут на сервер.

Базовый хук с debounce и отменой

import { useState, useEffect, useRef, useCallback } from 'react';

type SearchResult = {
  id: string;
  title: string;
  category?: string;
  url: string;
};

function useAutocomplete(
  fetchFn: (query: string, signal: AbortSignal) => Promise<SearchResult[]>,
  delay = 250
) {
  const [query, setQuery] = useState('');
  const [results, setResults] = useState<SearchResult[]>([]);
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState<Error | null>(null);
  const abortRef = useRef<AbortController | null>(null);
  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);

  const search = useCallback((value: string) => {
    setQuery(value);

    if (timerRef.current) clearTimeout(timerRef.current);
    if (abortRef.current) abortRef.current.abort();

    if (value.trim().length < 2) {
      setResults([]);
      return;
    }

    timerRef.current = setTimeout(async () => {
      const controller = new AbortController();
      abortRef.current = controller;
      setLoading(true);
      setError(null);

      try {
        const data = await fetchFn(value, controller.signal);
        if (!controller.signal.aborted) {
          setResults(data);
        }
      } catch (err) {
        if (err instanceof Error && err.name !== 'AbortError') {
          setError(err);
        }
      } finally {
        if (!controller.signal.aborted) {
          setLoading(false);
        }
      }
    }, delay);
  }, [fetchFn, delay]);

  useEffect(() => () => {
    if (timerRef.current) clearTimeout(timerRef.current);
    if (abortRef.current) abortRef.current.abort();
  }, []);

  return { query, results, loading, error, search };
}

Компонент с ARIA combobox

Корректная реализация по ARIA-паттерну combobox:

import { useId, useRef, useState } from 'react';

interface AutocompleteProps {
  placeholder?: string;
  onSelect: (result: SearchResult) => void;
  fetchResults: (query: string, signal: AbortSignal) => Promise<SearchResult[]>;
}

export function Autocomplete({ placeholder, onSelect, fetchResults }: AutocompleteProps) {
  const id = useId();
  const listId = `${id}-listbox`;
  const inputRef = useRef<HTMLInputElement>(null);
  const listRef = useRef<HTMLUListElement>(null);

  const { query, results, loading, search } = useAutocomplete(fetchResults);
  const [activeIndex, setActiveIndex] = useState(-1);
  const [open, setOpen] = useState(false);

  const isOpen = open && (results.length > 0 || loading);

  const handleKeyDown = (e: React.KeyboardEvent) => {
    switch (e.key) {
      case 'ArrowDown':
        e.preventDefault();
        setActiveIndex((i) => Math.min(i + 1, results.length - 1));
        break;
      case 'ArrowUp':
        e.preventDefault();
        setActiveIndex((i) => Math.max(i - 1, -1));
        break;
      case 'Enter':
        if (activeIndex >= 0 && results[activeIndex]) {
          onSelect(results[activeIndex]);
          setOpen(false);
          setActiveIndex(-1);
        }
        break;
      case 'Escape':
        setOpen(false);
        setActiveIndex(-1);
        inputRef.current?.focus();
        break;
    }
  };

  return (
    <div className="autocomplete" role="combobox" aria-expanded={isOpen} aria-haspopup="listbox">
      <input
        ref={inputRef}
        type="search"
        placeholder={placeholder}
        value={query}
        aria-autocomplete="list"
        aria-controls={listId}
        aria-activedescendant={activeIndex >= 0 ? `${id}-option-${activeIndex}` : undefined}
        onChange={(e) => {
          search(e.target.value);
          setOpen(true);
          setActiveIndex(-1);
        }}
        onFocus={() => query.length >= 2 && setOpen(true)}
        onBlur={() => setTimeout(() => setOpen(false), 150)}
        onKeyDown={handleKeyDown}
      />

      {isOpen && (
        <ul
          ref={listRef}
          id={listId}
          role="listbox"
          className="autocomplete__dropdown"
        >
          {loading && (
            <li role="option" aria-selected="false" className="autocomplete__loading">
              Поиск...
            </li>
          )}
          {results.map((result, index) => (
            <li
              key={result.id}
              id={`${id}-option-${index}`}
              role="option"
              aria-selected={index === activeIndex}
              className={`autocomplete__option ${index === activeIndex ? 'autocomplete__option--active' : ''}`}
              onMouseDown={() => {
                onSelect(result);
                setOpen(false);
              }}
              onMouseEnter={() => setActiveIndex(index)}
            >
              <HighlightMatch text={result.title} query={query} />
              {result.category && (
                <span className="autocomplete__category">{result.category}</span>
              )}
            </li>
          ))}
        </ul>
      )}
    </div>
  );
}

Подсветка совпадений

function HighlightMatch({ text, query }: { text: string; query: string }) {
  if (!query.trim()) return <span>{text}</span>;

  const escaped = query.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
  const parts = text.split(new RegExp(`(${escaped})`, 'gi'));

  return (
    <span>
      {parts.map((part, i) =>
        part.toLowerCase() === query.toLowerCase()
          ? <mark key={i}>{part}</mark>
          : <span key={i}>{part}</span>
      )}
    </span>
  );
}

Серверная часть: Elasticsearch suggest

// POST /api/suggest
async function suggestHandler(req: Request) {
  const { q } = await req.json();

  if (!q || q.length < 2) return Response.json({ hits: [] });

  const response = await esClient.search({
    index: 'products',
    body: {
      suggest: {
        title_suggest: {
          prefix: q,
          completion: {
            field: 'title.suggest',  // поле типа completion
            size: 10,
            fuzzy: { fuzziness: 'AUTO' },
          },
        },
      },
      // Дополнительно — полнотекстовый поиск для более релевантных результатов
      query: {
        multi_match: {
          query: q,
          fields: ['title^3', 'description', 'tags^2'],
          type: 'bool_prefix',
        },
      },
      _source: ['id', 'title', 'category', 'url', 'image'],
      size: 10,
    },
  });

  return Response.json({
    hits: response.hits.hits.map((h) => h._source),
  });
}

Индекс с полем completion:

{
  "mappings": {
    "properties": {
      "title": {
        "type": "text",
        "fields": {
          "suggest": {
            "type": "completion",
            "analyzer": "standard"
          },
          "keyword": { "type": "keyword" }
        }
      }
    }
  }
}

PostgreSQL с pg_trgm

Для проектов без Elasticsearch:

-- Расширение для триграммного поиска
CREATE EXTENSION IF NOT EXISTS pg_trgm;

-- Индекс
CREATE INDEX products_title_trgm_idx ON products
  USING gin (title gin_trgm_ops);

-- Запрос с подсказками
SELECT id, title, category, similarity(title, $1) AS score
FROM products
WHERE title % $1           -- триграммное совпадение
   OR title ILIKE $1 || '%' -- starts-with (быстрее для точных совпадений)
ORDER BY
  title ILIKE $1 || '%' DESC,  -- starts-with в приоритете
  score DESC
LIMIT 10;

Кеширование на стороне клиента

const cache = new Map<string, { data: SearchResult[]; ts: number }>();
const TTL = 30_000; // 30 секунд

async function fetchWithCache(query: string, signal: AbortSignal) {
  const cached = cache.get(query);
  if (cached && Date.now() - cached.ts < TTL) {
    return cached.data;
  }

  const res = await fetch(`/api/suggest?q=${encodeURIComponent(query)}`, { signal });
  const data = await res.json();

  cache.set(query, { data: data.hits, ts: Date.now() });
  if (cache.size > 100) {
    // Удаляем самую старую запись
    cache.delete(cache.keys().next().value);
  }

  return data.hits;
}

Сроки

• Простое автодополнение (fetch + debounce, без ARIA, без подсветки): 4–8 часов
• Полноценный компонент (ARIA combobox, keyboard navigation, подсветка, client cache): 2–3 дня
• С серверным индексом Elasticsearch (маппинг completion, настройка индекса, fuzzy): ещё 1–2 дня