Use isto quando precisar guiar o leitor por um pipeline inteiro — requisição entra, resposta sai — com um sumário fixo, prosa simples, um trecho de código real e um diagrama anotado do fluxo.
Este é um exemplar copiável. Pegue o bloco de demo <section> abaixo e leve para uma lição construída a partir de assets/lesson-template.html — mantenha os tokens de design e o padrão .tech-toggle ao pé da letra.
Você digita algumas palavras em uma caixa de busca e, uma fração de segundo depois, surge uma lista ordenada de resultados. No meio do caminho, suas palavras passam por cinco repasses: seu navegador as envia, uma API as arruma, um índice acha toda página que poderia corresponder, uma etapa de ordenação decide quais correspondências são as melhores, e uma resposta leva as vencedoras de volta à sua tela.
Pense nisso como… pedir a um bibliotecário "livros sobre vulcões". Você fala (navegador). Ele repete para ter certeza de que ouviu direito (API). Ele caminha até o catálogo de fichas e puxa toda ficha marcada com vulcões (índice). Ele organiza essa pilha para que os livros mais úteis fiquem no topo (ordenação). Então ele te entrega os primeiros e diz quantos outros existem (resposta).
O navegador emite um GET /search?q=… via HTTPS que termina em um balanceador de carga à frente de uma camada de API sem estado. A API normaliza a consulta (deixa em minúsculas, faz dobramento Unicode, trata stop-words, tokeniza) e então consulta um índice invertido — um mapa de cada termo para uma lista de postagens de IDs de documentos. Os documentos candidatos recebem uma pontuação, em geral por BM25 para relevância léxica somada a sinais como recência e popularidade, e então um ranqueador treinado reordena os melhores candidatos. A API serializa os k melhores resultados em JSON e os retorna; o ciclo inteiro de ida e volta costuma se completar em dezenas de milissegundos.
Quando você aperta Enter, o navegador empacota suas palavras em uma requisição web e a envia pela rede. Nada foi "buscado" ainda — esta etapa apenas entrega sua pergunta a um computador que sabe como respondê-la.
O serviço que recebe arruma o seu texto: remove espaços, deixa em minúsculas, divide em palavras individuais e verifica se está seguro e bem formado. Um bagunçado " Volcanoes! " vira o termo limpo que o resto do sistema espera.
O índice é uma tabela de consulta pré-construída: para cada palavra, ele já sabe quais documentos a contêm. Em vez de varrer milhões de páginas, o sistema salta direto para a lista de "volcanoes" e traz de volta todo documento correspondente — muitas vezes milhares deles.
Milhares de correspondências são inúteis sem ordem. A etapa de ordenação pontua cada candidato — quão bem corresponde, quão recente é, com que frequência as pessoas clicam nele — e ordena para que os resultados mais úteis subam ao topo. Só o punhado do topo sobrevive.
Os melhores resultados são empacotados em um formato de dados compacto (JSON) e enviados de volta pela mesma conexão. Seu navegador os recebe e desenha a familiar lista de links azuis — e a jornada inteira termina antes de você terminar de piscar.
Aqui está o handler que amarra as cinco etapas — leia de cima a baixo e você reconhecerá cada passo do diagrama.
# GET /search?q=... — uma requisição, cinco etapas def search(request): raw = request.query.get("q", "") query = normalize(raw) # 2 · analisar + validar if not query.terms: return json({"hits": [], "total": 0}) candidates = index.lookup(query.terms) # 3 · achar candidatos ranked = rank(candidates, query) # 4 · pontuar + ordenar top = ranked[: 10] # mantém top k return json({ # 5 · resposta "hits": [hit.to_dict() for hit in top], "total": len(candidates), })
Abra o handler e salte para o ponto de entrada com: grep -n "def search" services/search/handler.py
normalize, index.lookup e rank vivem cada um em seu próprio módulo sob services/search/ — aprofunde qualquer etapa com grep -rn "def normalize\|def rank" services/search/.