Design de chave de objeto: Comportamento e interfaces
Define atores, operações, estados, interfaces, erros, limites e autorização para design de chave de objeto. Esta referência fixa o limite de adoção, comportamento em falhas e evidências observáveis, deixando limites específicos do ambiente configuráveis.
Status do pacote: contexto de referência pronto para revisão humana. O contrato e os cenários de teste estão completos, mas não se afirma que uma implementação adotante os tenha aprovado.
Decisão
Para o design de chave de objeto, adote um registro de propriedade separado da chave opaca do objeto. Exponha um contrato de recurso ou evento com identidade estável, autorização, validação, idempotência, compatibilidade e erros explícitos. Este pacote é um contrato de referência: a equipe adotante deve escolher limites numéricos, provedores, jurisdições e responsáveis operacionais a partir de evidências em seu próprio ambiente.
Escopo
- Os atores, entradas, saídas, estados, versões de política ou esquema e resultados visíveis externamente do design de chave de objeto descritos por este bloco de API.
- Interfaces primárias e alternativas, trabalho em segundo plano, caches, integrações, caminhos de suporte e evidências que podem exercer o mesmo limite.
- Configuração específica de adoção, implantação, recuperação e responsabilidades de verificação necessárias para aplicar a referência com segurança.
Fora deste bloco
- Escolher um fornecedor universal, framework, jurisdição, limite numérico, período de retenção ou objetivo de nível de serviço para todos os adotantes.
- Afirmar que cenários empacotados foram executados contra uma implementação a jusante ou que esta referência concede certificação legal, de segurança ou acessibilidade.
Contrato
- Autorizar contra o registro de propriedade para upload, leitura, visualização, compartilhamento e exclusão; posse de uma URL ou chave não é autorização.
- Limitar tamanho, quantidade, tipo de mídia, descompressão, tempo de processamento e consumo de armazenamento antes de iniciar trabalho custoso.
- Manter objetos novos ou suspeitos em quarentena até que validação e varredura alcancem um resultado terminal da política.
- Gerar chaves de objeto independentemente dos nomes de arquivo do usuário e impedir que nomes de arquivo, rótulos MIME e metadados selecionem comportamento executável.
- Documentar semântica de métodos ou eventos, campos obrigatórios, comportamento condicional, limites e um vocabulário de erros legível por máquina.
- Rejeitar campos desconhecidos sensíveis à segurança e preservar compatibilidade futura para dados explicitamente extensíveis.
- Usar chaves de armazenamento opacas e imutáveis independentes de nomes de exibição e atributos comerciais mutáveis, com escopo explícito de locatário, namespace, distribuição de fragmentos, comprimento, codificação e regras de colisão.
- Canonicalizar antes da autorização, prevenir ambiguidade de prefixo e travessia, evitar embutir segredos ou dados pessoais e migrar chaves por meio de cópia, verificação, troca de ponteiro e limpeza limitada.
Orientação para implementação
- Publicar fixtures de contrato e testes de consumidor antes de direcionar tráfego de produção para uma nova versão.
- Modelar entradas, saídas, atores, estados, invariantes, efeitos colaterais e evidências do design de chave de objeto antes de selecionar detalhes de framework ou fornecedor.
- Armazenar a versão aplicável do contrato ou política do design de chave de objeto com estado material para que migrações, reprodução e decisões de suporte permaneçam atribuíveis.
- Introduzir o caminho por trás de implantação controlada, comparar resultados esperados e observados e manter uma rota de recuperação testada até que a evidência de adoção esteja completa.
Tratamento de falhas e salvaguardas
- Processamento ou propriedade ambígua deixa o objeto em quarentena; limpeza requer evidência de propriedade e um período de carência recuperável.
- Estado inválido ou contraditório do design de chave de objeto é rejeitado ou colocado em quarentena; a implementação nunca supõe um valor que amplie autoridade ou duplique um efeito.
- Retentativas são limitadas e usam identidade durável; após esgotamento, o trabalho alcança um estado terminal inspecionável com um responsável contabilizável.
Verificação e operações
- Testar retentativas, requisições duplicadas, atualizações condicionais, paginação ou retomada, credenciais inválidas, limites e timeout de dependência.
- Monitorar sucesso, negação, falha de validação, falha de dependência, esgotamento de retentativas e recuperação do design de chave de objeto por versão de contrato sem dimensões sensíveis do payload.
- Reexecutar fixtures positivos e negativos pareados após mudanças de política, esquema, dependência, migração ou limite e preservar a evidência resultante.
Suposições de adoção
- Nomes e valores no exemplo são um fixture concreto, não padrões universais; adotantes os substituem por meio de evidência documentada e propriedade.
- O sistema adotante pode fornecer identidade autenticada, versões duráveis de operação ou registro, telemetria limitada e um caminho controlado para mudança.
Os exemplos com aparência executável neste pacote são fixtures e contratos de aceitação. Execute o validador da coleção para verificar estrutura e metadados, depois traduza e execute os cenários no repositório alvo antes de registrar evidência da implementação.