Este artigo foi traduzido por máquina.

{End Bracket}

Design da API de transferência

James Waletzky

Por que é bom design de interface de programação de aplicativo (API) tão difícil? Apenas lançar juntos algumas classes com alguns métodos básicos sobre eles e chame-feito.

Você poderia fazer isso, se você não se importar outros desenvolvedores cursing você — e referenciar o API como um antipadrão. Como isso pode ser evitado? Visam para perfeição com design de API. Sim, perfeição.

Criação de uma API é semelhante à criação de uma interface de usuário. Ambos são pontos de entrada em um aplicativo e a primeira coisa que um usuário (ou desenvolvedor) interage. Imagem seu dispositivo de eletrônica de consumidor favoritos em conjunto com seus concorrentes. Meu é meu gravador vídeo digital para TiVo amada. O que torna a interface do usuário TiVo grande?

  • O uso é simples
  • Uso indevido é difícil
  • TiVo faz algo bem
  • Ele não faz nada inesperado
  • Ele nunca tenha travou nos vários anos de uso
  • Ações/tarefas são intuitivas e fáceis de descobrir
  • A interface do usuário é consistente, elegante e perfeita ou próximo a ele

Os mesmos princípios mantenha verdadeiras com design de API. Vamos escolher em um dos meus favoritos antipadrões de API do mundo COM: IOleCommandTarget::Exec. Essa API é normalmente usada para habilitar a algum tipo de objeto e o contêiner que ele fica no, para enviar comandos para si.

Um exemplo de implementação é um controle COM que se comunica com seu contêiner para modificar itens de menu e barras de ferramentas. Essa API é uma versão mais um pouco seguro-digitada de uma interface de comando que leva em uma seqüência genérica ditando o que a implementação deve para fazer.

Aqui está a assinatura IOleCommandTarget::Exec API:

HRESULT Exec( 
  const GUID *pguidCmdGroup,  // Pointer to command group
  DWORD nCmdID,               // Identifier of command to execute
  DWORD nCmdExecOpt,          // Options for executing the command
  VARIANTARG *pvaIn,          // Pointer to input arguments
  VARIANTARG *pvaOut          // Pointer to command output
);

Vamos analisar este API de acordo com os princípios discutidos apenas.

É a API intuitivo e detectável? Este É o primeiro lugar, um desenvolvedor teria uma aparência para modificar uma barra de ferramentas? Provavelmente não, é a menos que você tenha o conhecimento de grupo sobre essa API. Até mesmo uma pesquisa de documentação do MSDN deve terminar em frustração.

É ele simples? A API tem cinco parâmetros que são chamados genericamente. Documentação é necessário para compreender completamente o uso de cada parâmetro. Uma API simples apresenta intenção e clareza apenas pelo nome do objeto (por contexto) e o nome do método.

É a API fortemente tipados e difícil para uso indevido? Não. As variantes do não são fortemente tipadas e as opções de execução não são enumerações, mas DWORDs genéricos. Parâmetros de tipo forte ajudam a localizar erros em tempo de compilação em vez de em tempo de execução.

É a API consistente? Uma implementação dessa função geralmente tem muitas responsabilidades, não apenas um. Uma API well-named para um propósito específico (por exemplo, AddToolbarButton) é muito mais consistente. Uma implementação do método Exec provavelmente alterna na ID de comando e tiver ações diferentes com base nessa condição.

É a API livre de efeitos colaterais? Difícil digamos, mas uma implementação da API poderia fazer praticamente qualquer coisa devido à sua falta de coesão.

É ele confiável? O princípio de design famoso "design para interfaces" ajuda a impor testability em um objeto. Essa API é inerentemente teste, mas o número de casos de teste para verificar pode ser enorme devido à sua falta de coesão. Confiabilidade é em risco.

É ele consistente? Essa API tem alguns consistência no que ele retorna um HRESULT e usa GUIDs para identificar conjuntos de informações. No entanto, é difícil avaliar a consistência sem saber como mal criado o resto das interfaces de um objeto são.

Qualquer pessoa aprendendo a usar IOleCommandTarget::Exec provavelmente precisa instrução sobre o uso de um ponto ou um livro. As APIs de melhores são simples e pode ser usado sem documentação, embora documentação ainda pode ser necessárias para compreender os detalhes, como o tratamento de erros.

Finalmente, o APIs e as APIs você analisar deve ser como fácil de usar como TiVo. Um altamente localizável fortemente tipadas, coeso, efeito colateral livre, confiável e consistente e elegante API facilita vidas dos seus desenvolvedores por aumentar a satisfação e reduzir os custos de suporte. Várias interfaces no Microsoft .NET Framework são exemplos excelentes. Para obter todos esses ganhos de design, visam para perfeição quando criando ou revisando a qualquer projeto de API.

James Waletzky é chefe de desenvolvimento de sênior da equipe Internet do consumidor e experiência de desenvolvedor no Windows Mobile. Além de levando uma equipe de desenvolvimento do produto, James é beijos sobre como melhorar as práticas de engenharia na Microsoft.