Melhores práticas e diretrizes para projetar uma API [fechado

StackOverflow https://stackoverflow.com/questions/2619854

  •  26-09-2019
  •  | 
  •  

Pergunta

Quais são algumas diretrizes e práticas recomendadas que eu posso aderir ao projetar uma API? No mínimo, sei que uma API deve ser fácil de usar e flexível. Infelizmente, esses termos podem ser bastante subjetivos, então eu estava procurando algumas diretrizes concretas relacionadas ao bom design da API.

Foi útil?

Solução

Eu achei o seguinte que vale a pena assistir Joshua Bloch - Como projetar uma boa API e por que isso importa

Os exemplos estão em Java, mas você ainda pode traçar paralelos. Já que você não mencionou uma tecnologia específica; Suponho que você não queira soluções de nicho.

Outras dicas

Como alguém que tem que consumir toneladas de APIs ...

Escreva sua API de maneira consistente:

  1. Nomeação consistente dentro da própria API. Use verbos, substantivos, palavras -chave exatamente no mesmo estilo.

  2. Consistente com o ambiente de destino em que será usado. Se .NET, consulte as diretrizes de nomeação da Microsoft.

  3. Conceitos consistentes. Padrão de fábrica? Padrão do construtor? Métodos estáticos? Interfaces? Basta escolher um e ficar com ele. VERDADE. Não existe um pequena exceção à regra. Ele se destacará como um grande polegar dolorido. Mais de 1 exceção? Sua API é cada vez mais amadora.

Aqui está outro: especificidade.

  1. As classes base que eu posso implementar, se você optar por fornecê-las, deve ter poucas e funções bem definidas para implementar. Não me diga "getData ()" retorna um "objeto [] e espere que eu o implemente, descubra por que tenho que lançá -lo para uma string [] e depois depurar por que está sendo chamado 20 vezes. É muito melhor ter DataPoint [] getChartData (), string [] getLabeldata () etc. e deixe -me escolher quais devo implementar.

  2. Por favor, não fique bobo com nomes: postrendercolorwheelmodifyhsvbaseHandler. Muitas vezes, você pode refatorar coisas super-específicas em um nome mais genérico + parâmetros.

  3. Os parâmetros da string são um não-não! Use enumerações. Eu não quero usar um manipulador como

    PostrenderHandler ("Colorwheel", "HSV", Somentelegate);

Eu prefiro gostar de uma enumeração que posso investigar:

PostRenderHandler(ModuleType.ColorWheel, Options.ColorWheelHSV, someDelegate);

Cara, eu poderia continuar ... poder para aquele cara de Josh Bloch - APIs bem escritas podem ser realmente incríveis ... as ruins podem ser realmente dolorosas.

Existe um boa apresentação sobre este tópico de Joshua Bloch. A apresentação usa Java, mas as idéias são independentes da linguagem. Outra fonte (PDF) Para uma visão geral rápida.

Este é um link da Microsoft:http://msdn.microsoft.com/en-us/library/ms229042.aspx

Há também este livro: Diretrizes de design da estrutura: convenções, expressões idiomáticas e padrões para bibliotecas .NET reutilizáveis

Acho que sua pergunta não será respondida nesta quantidade de espaço com a quantidade de informações que você está dando. Eu coloquei vários links de digitar 'API Design' no Google, e na primeira página obtenha esses que parecem muito bons

http://web.archive.org/web/20151229055009/http://lcsd05.cs.tamu.edu/slides/keynote.pdf

http://www.artima.com/weblogs/viewpost.jsp?thread=142428

http://web.archive.org/web/20090520234149/http://chaos.troll.no/~shausman/api-design/api-design.pdf

Licenciado em: CC-BY-SA com atribuição
Não afiliado a StackOverflow
scroll top