APRENDER. PRATICAR. EVOLUIR.Definir o conjunto que o negócio espera
Uma exportação pode querer os dados atuais à medida que lê ou os dados tal como existiam num instante de corte. Estas exigências produzem critérios diferentes. Escreve população, filtros, campos, versão, destino e condição de conclusão antes de escolher o cursor. O fim da navegação não comprova que todos os itens chegaram ao destino. Num caso fictício, a origem enumera mil IDs, mas o destino confirma 980. O relatório deve mostrar os vinte pendentes e a sua causa, mesmo quando cada pedido de leitura devolveu 200.
Comparar posições com identidades
Depois de ler [1,2], eliminar 1 transforma a coleção em [2,3,4,5,6]. Pedir offset=2 salta agora 2 e 3, devolvendo [4,5]. O laboratório demonstra a omissão através de pedidos HTTP reais à sua coleção fictícia. Uma fronteira id>2 com ordenação por ID imutável evita esta deslocação específica. Não garante um snapshot: se o valor de 3 mudar, a página seguinte pode mostrar o novo valor. Uma ordenação só por data também precisa de desempate quando vários registos têm a mesma data.
Distinguir corte, snapshot e duração
Fixar o maior ID da primeira leitura limita entradas posteriores acima desse ID, mas não congela os restantes campos. Para reproduzir valores num instante, considera um mecanismo de versões ou uma exportação materializada com identidade de snapshot. A escolha tem custos de retenção, duração, capacidade e acesso. Leituras HTTP separadas não partilham automaticamente a mesma transação da base de dados. O fixture mantém uma cópia Python dos registos para comparação; isso demonstra uma vista congelada em memória, sem implementar isolamento PostgreSQL ou persistência após restart.
Manter o âmbito e a autorização
Um cursor opaco permite mudar detalhes internos sem obrigar o consumidor a interpretar offsets ou datas. No contrato do exercício, cada token está ligado a tenant, filtro e modo, expira segundo um relógio sintético e não pode ser editado pelo cliente. Mudar o filtro inicia outra enumeração. A autorização atual é verificada antes de consultar páginas guardadas. AIP-158 é orientação de desenho de um fornecedor, não uma regra universal de todas as APIs REST. Os códigos 400, 403 e 410 usados no fixture pertencem ao seu contrato explícito.
Guardar progresso depois de entrega confirmada
Se o próximo cursor é guardado antes de aplicar a página atual, uma falha pode fazer a retoma saltar itens nunca entregues. Se a ordem for invertida, pode existir replay após falha antes de guardar progresso. O desenho deve relacionar confirmação, checkpoint e identidade estável no destino. Conforme os sistemas envolvidos, utiliza efeitos idempotentes, reconciliação ou uma transação que realmente abranja o âmbito necessário. Não declares execução única apenas porque o cursor é único. Um token expirado exige seguir o contrato de reinício e reconciliar o trabalho anterior.
Oficina e handover em quarenta minutos
Nos primeiros dez minutos, prevê as páginas após a eliminação de 1. Nos dez seguintes, compara o montante 30 com 999 em keyset e snapshot. Depois usa dez minutos para rever o acesso revogado, o filtro alterado e o cursor expirado. Nos dez finais, desenha uma falha entre entrega e checkpoint e define a evidência necessária para retomar. Entrega a matriz de IDs, critérios de conclusão e plano de escalamento. O laboratório não executa escrita num destino externo, falha de disco ou uma transação distribuída; estas partes continuam como exercício de desenho.
# Workshop: 40 minutes / Oficina: 40 minutos
# 00-10: offset deletion / eliminação e offset
# 10-20: live values versus frozen copy / valores atuais e cópia congelada
# 20-30: scope, revocation, expiry / âmbito, revogação, expiração
# 30-40: delivery checkpoint and handover / checkpoint de entrega e handover
# Run the previous lesson code; inspect evidence.json.
# Executa o código da aula anterior e analisa evidence.json.
# External writes and distributed transactions are design exercises only.
A primeira página [1,2] não torna offset=2 uma identidade estável. Após eliminar 1, o próximo pedido pode saltar 3 sem devolver erro HTTP.
Armadilhas comuns
Parar só porque a página é curta; tratar cursor como autorização; confundir keyset com snapshot; guardar progresso antes de confirmar entrega.
Tópicos relacionados: Pedidos e resultados · Cache e paginação · Alterações concorrentes e recuperação verificável
Uma exportação completa precisa de população definida, navegação coerente, acesso válido, entrega confirmada e retoma demonstrável.
Referência: AIP-158 Pagination · HTTP semantics RFC9110; OpenAPI3.2.1; selected primary standards and provider contracts consulted2026-09-30