Conteúdo do curso Lição 67 de 148 · APIs que ninguém pode usar de forma errada
APIs que ninguém pode usar de forma errada

Mau uso por design

Por que isso importa A maioria dos bugs em uma fronteira de API não está na API. Eles estão em um chamador que a usou de uma forma que parecia correta e fez a coisa errada silenciosamente. Você não pode consertar cada chamador; você pode tornar o uso errado impossível ou barulhento.

Um assistente escrevendo uma API tende a ser prestativo: se você envia antes de conectar, ele conecta para você; se você passa uma string onde bytes eram esperados, ele a codifica; se você esquece uma opção, existe um padrão. Cada gentileza esconde um erro até que ele apareça em algum lugar distante.

Falhe cedo, falhe alto: lance um erro na chamada exata que está errada, antes que qualquer coisa mude, com uma mensagem que diz o que era esperado.

Quatro ferramentas

  • Estados explícitos: um objeto que sabe se está novo, aberto ou fechado, e recusa chamadas que não se encaixam.
  • Opções nomeadas, sem booleanos: mode="dry_run" não pode ser trocado por outra flag por acidente; copy(a, b, True, False) pode.
  • Não use padrões silenciosos para escolhas que são perigosas de errar: faça quem chama declarar.
  • Tipos que carregam significado: dinheiro que conhece sua moeda não pode ser somado a dinheiro em outra.

Neste módulo, scripts de uso indevido ocultos chamam sua API erradamente e esperam um erro na chamada errada, sem nada alterado. Scripts de uso correto esperam que funcione simplesmente. Cada problema lista os usos indevidos para se proteger.

Resumo Palpites úteis escondem bugs. Recuse o uso errado na chamada que está errada, antes de qualquer efeito.

Viu um problema nesta lição? Reporte-o · Pergunte sobre esta lição

Este exercício abre em breve

Termine a lição anterior para que esta seja desbloqueada. O curso inteiro é gratuito, não precisa de conta, e você pode ler esta lição agora mesmo.