Consulta de catálogo

Fluxo de consulta de catálogo: do frontend até o microsserviço de catálogo, passando pelo banco de dados e pela camada de cache para otimizar respostas.

Por que a consulta de catálogo é um fluxo representativo

A consulta de catálogo é um dos fluxos mais frequentes em qualquer aplicação de comércio ou gestão. É um caso de leitura intensiva: muitos usuários consultam os mesmos dados, os dados mudam com pouca frequência e a velocidade de resposta impacta diretamente na experiência do usuário.

Este fluxo ilustra como a arquitetura lida com leituras otimizadas usando cache e como o BFF adapta os dados para o frontend.

O fluxo completo

sequenceDiagram
    participant FE as Frontend
    participant GW as API Gateway
    participant BFF as BFF
    participant CACHE as Caché
    participant MS as ms-catalog
    participant DB as Catalog DB

    FE->>GW: GET /catalog/products?category=electronics
    GW->>GW: Auth, rate limiting
    GW->>BFF: Forward

    BFF->>CACHE: ¿Datos en caché?
    alt Cache HIT
        CACHE-->>BFF: Datos cacheados
    else Cache MISS
        BFF->>MS: GET /products?category=electronics
        MS->>DB: SELECT * FROM products WHERE category = ...
        DB-->>MS: Resultados
        MS-->>BFF: Lista de productos
        BFF->>CACHE: Guardar en caché (TTL: 5 min)
    end

    BFF->>BFF: Transformar para UI
    BFF-->>GW: Respuesta formateada
    GW-->>FE: 200 OK + productos

O que cada camada faz

Frontend

1. O usuário navega até uma categoria ou usa a busca
2. O frontend monta a requisição com filtros (categoria, preço, ordenação)
3. Envia a requisição ao Gateway
4. Recebe os produtos e os renderiza em um grid ou lista
5. Pode implementar paginação ou scroll infinito

API Gateway

1. Valida o token JWT do usuário
2. Aplica rate limiting (as consultas de catálogo podem ser muito frequentes)
3. Roteia para o BFF

BFF

O BFF é onde ocorre a maior parte da otimização:

1. Recebe a requisição com os filtros do frontend
2. Consulta o cache para verificar se já tem os dados
3. Se houver cache hit, devolve os dados em cache diretamente
4. Se houver cache miss, invoca o microsserviço de catálogo
5. Salva a resposta no cache com um TTL apropriado
6. Transforma os dados para o formato que o frontend precisa

Microsserviço de catálogo (ms-catalog)

1. Recebe a consulta com os filtros
2. Monta a query no banco de dados
3. Aplica paginação, ordenação e filtros
4. Devolve os produtos com seus dados de domínio

Banco de dados

• Armazena produtos, categorias, preços, estoque
• Possui índices otimizados para as consultas mais frequentes
• Pode usar visões materializadas para consultas complexas

A camada de cache em detalhe

Onde posicionar o cache

Há várias opções, e elas podem ser combinadas:

Nesta arquitetura, o cache principal fica no BFF porque é o ponto onde é possível controlar melhor a transformação e a invalidação.

Estratégia de invalidação

O cache do catálogo é invalidado de duas formas:

Por TTL (Time To Live): cada entrada tem um tempo de vida (por exemplo, 5 minutos). Depois desse tempo, ela é considerada obsoleta e o microsserviço é consultado novamente.

Por evento: quando o microsserviço de catálogo atualiza um produto, ele publica um evento ProductUpdated. O BFF escuta esse evento e invalida as entradas de cache afetadas.

sequenceDiagram
    participant ADMIN as Admin
    participant MS as ms-catalog
    participant EB as Event Bus
    participant BFF as BFF
    participant CACHE as Caché

    ADMIN->>MS: PUT /products/123 (actualizar precio)
    MS->>MS: Actualizar en DB
    MS->>EB: Publicar ProductUpdated
    EB->>BFF: Evento ProductUpdated
    BFF->>CACHE: Invalidar entradas relacionadas

Cache key design

As chaves de cache devem ser determinísticas e refletir os parâmetros da consulta:

catalog:products:category=electronics:sort=price:page=1
catalog:products:category=electronics:sort=price:page=2
catalog:product:123

Transformação no BFF

O microsserviço devolve dados de domínio completos, mas o frontend não precisa de tudo. O BFF transforma:

Resposta do microsserviço:

{
  "id": "prod-123",
  "internalSku": "SKU-2024-001",
  "name": "Laptop Pro",
  "description": "...",
  "priceInCents": 99900,
  "currency": "USD",
  "stockQuantity": 45,
  "warehouseLocation": "A-12-3",
  "categoryId": "cat-electronics",
  "createdAt": "2024-01-01T00:00:00Z",
  "updatedAt": "2024-01-15T10:00:00Z"
}

Resposta do BFF ao frontend:

{
  "id": "prod-123",
  "name": "Laptop Pro",
  "description": "...",
  "price": "$999.00",
  "inStock": true,
  "category": "Electrónica",
  "imageUrl": "/images/prod-123.jpg"
}

O BFF elimina dados internos (internalSku, warehouseLocation), formata o preço, simplifica o estoque para um booleano e resolve a categoria para seu nome legível.

Paginação e desempenho

Para catálogos grandes, a paginação é essencial:

• O frontend envia page e pageSize
• O microsserviço aplica LIMIT e OFFSET na query
• A resposta inclui metadados de paginação (totalItems, totalPages, currentPage)
• Cada página é armazenada em cache de forma independente

Cenários de erro

Microsserviço indisponível

Se o microsserviço de catálogo estiver fora do ar, mas houver dados em cache (mesmo que expirados), o BFF pode devolver os dados desatualizados com um header indicando que são stale. Isso é melhor do que exibir um erro ao usuário.

Cache indisponível

Se o Redis estiver fora do ar, o BFF simplesmente consulta o microsserviço diretamente. A latência aumenta, mas o fluxo não é interrompido.

Consulta sem resultados

Não é um erro. O microsserviço devolve uma lista vazia e o frontend exibe uma mensagem de “Nenhum produto encontrado”.

Resumo

A consulta de catálogo mostra como a arquitetura otimiza fluxos de leitura intensiva. O cache no BFF reduz a carga sobre o microsserviço e o banco de dados, enquanto a invalidação por eventos mantém os dados razoavelmente atualizados. O BFF transforma os dados de domínio para o formato que o frontend precisa, mantendo a separação de responsabilidades entre as camadas.