null ou omitir o campo

Resumo da ópera: envie null quando o consumidor precisar distinguir "limpo" de "intocado" — em um corpo PATCH, a omissão deixa o campo intacto e um null explícito o limpa — e mantenha uma convenção por campo para que respostas e mesclagens de configuração fiquem estáveis.

A diferença

复制{ "nickname": null }

Presente, vazio. O consumidor sabe que o campo foi explicitamente limpo.

复制{ }

Ausente. O consumidor não consegue distinguir "nunca definido" de "não suportado".

Em JavaScript a distinção é concreta:

复制'nickname' in obj          // false — ausente
obj.nickname === null      // true  — presente e null
obj.nickname === undefined // true  — os dois casos

Onde isso importa

Corpos PATCH. {"nickname": null} limpa o apelido. {} não muda nada. Se o handler trata "null" e "ausente" como iguais, os usuários nunca conseguem limpar o campo — só podem definir uma string vazia, que é outra coisa.

Implemente pela presença da chave, não pelo valor:

复制if (Object.hasOwn(patch, 'nickname')) {
  target.nickname = patch.nickname;   // null permitido
}

Mesclagem de configuração. A omissão herda o padrão; null o desativa explicitamente. É exatamente assim que os valores do Helm e do Kubernetes se comportam.

Preenchimento de formulário. Um null renderiza como vazio, e um campo ausente também, mas o envio difere: tinha um valor, agora limpo → envie null; nunca preenchido → omita. Sem a distinção, limpar parece idêntico a não tocar.

Convenções

Mantenha as formas de resposta estáveis. Uma lista em que alguns itens carregam avatar e outros não força verificações 'avatar' in item em todo ponto de chamada. avatar: null é mais fácil de consumir.

Três coisas a não fazer

Não use "" para null. Um apelido vazio e um apelido não definido são estados diferentes na maioria dos domínios.

Não use 0 ou -1 como sentinelas. Zero é um número legítimo, e a sentinela corrompe toda média que você calcula.

Não misture convenções por endpoint. Duas convenções significam dois caminhos de código em todo cliente.

Perguntas frequentes

O que decide entre null e um campo omitido?

Pergunte se o consumidor precisa distinguir "explicitamente limpo" de "nunca definido". Em um corpo PATCH ele precisa, então null limpa e a ausência preserva; em respostas, manter null torna a forma estável e os tipos do cliente mais simples.

Como um endpoint PATCH distingue limpar de deixar intacto?

Verifique a presença da chave, não o valor: Object.hasOwn(patch, 'nickname') diz que o campo foi enviado, e só então atribua, null incluído. Se o handler trata null e ausente como iguais, os usuários nunca conseguem limpar o campo e só podem recair em uma string vazia.

Por que corpos de resposta devem manter null?

Uma forma estável significa que clientes não precisam de uma verificação 'avatar' in item para cada chave opcional. Quando alguns itens de lista carregam avatar e outros o omitem, essa verificação é duplicada em todo ponto de chamada e é fácil de errar.

Leitura adicional

• Que estrutura uma resposta de API deve usar
• JSON Pointer, Patch e Merge Patch