Temos de 20 a 30 módulos / soluções independentes. Cada um deles tem cerca de 7 a 10 projetos com diferentes classes, componentes, etc. Estes são todos utilizados internamente em nossa empresa.
Nosso problema é que, quando fazemos uma alteração em um módulo, precisamos garantir a atualização de todos os outros módulos que acessam esse código. Isso é difícil de saber porque está em diferentes bases de código.
Como podemos documentar onde estão todos os usos externos de uma API? Ou impedir que pequenas alterações quebrem outros módulos?
Respostas:
A solução mais simples, a IMO, é ter um número decente de testes automatizados para cada produto. Ao atualizar uma biblioteca, você executa o conjunto de testes para cada produto. Se os testes falharem, você saberá quais produtos precisam ser atualizados.
fonte
Eu sugeriria não tentar documentar isso (pelo menos manualmente) como se você exigisse que as pessoas atualizassem, será necessário um alto nível de precisão para funcionar corretamente. Mas você nunca terá esse nível de precisão, porque adicionar esse tipo de documentação ... não seria divertido e ninguém fará isso.
Algumas opções melhores:
Você também pode considerar que refatorar lentamente as APIs não é tão frágil, mas espero que isso esteja fora do escopo do que você pode razoavelmente realizar se for um indivíduo e tiver mais de 20 módulos em grande escala para trabalhar.
fonte
Primeiro de tudo, uma API com usos externos não deve mudar.
Como o @BryanOakley mencionou, o uso de testes de unidade automatizados é muito importante e pode salvar vidas nessas situações. Além disso, algumas sugestões que podem (ou não, de acordo com a situação) ajudá-lo
Muitas linguagens (como Java e C #) oferecem
Function/Method Overriding
. Idiomas como o Python oferecem a você passar (número ilimitado de) argumentos e argumentos de palavras-chave para uma função:Java:
Pitão
Muitas línguas ofertas
public
,private
eprotected
métodos. Você pode manipular a chamada de função em umapublic
função e executar o trabalho emprivate/protected
funções.Em python, não há definição pública / privada para métodos e funções, mas um sublinhado (
_
) principal indica que um método é privado e não deve ser usado externamente. As chamadas externas à API são entregues por um método aberto ao mundo externo e todas as tarefas são realizadas nas chamadas funções locais :Como eu disse, uma definição de API que também é usada por aplicativos externos não deve ser alterada com tanta frequência. Você pode procurar maneiras de tornar suas funções externas mais flexíveis, para alterar como a API funciona sem interromper o estado atual.
fonte
Eu sugeriria que isso é impossível saber.
Você é responsável pelos componentes e suas interfaces.
Você não é responsável por tudo e qualquer coisa que possa fazer uso deles.
Resposta curta? Testes.
Escreva testes que exercitem as interfaces publicadas. Execute-os novamente sempre que fizer uma alteração. Enquanto os testes "passarem", você não quebrou nada. Quando um teste é interrompido (e será) (a) encontre e corrija o problema ou (b) se você puder justificar a alteração como legítima, reescreva o teste para acomodá-lo.
fonte
Eu vi e codifiquei APIs com números de versão nos caminhos e / ou nomes das funções.
Dessa forma, você pode ter diferentes versões da API disponíveis - APIs completas e versões diferentes das funções em uma API.
Isso coloca o trabalho de manter todas as versões da API no código da API - nenhum código de outros aplicativos precisa ser alterado além daquele para o qual o novo recurso da API foi produzido.
Eu acho que isso é especialmente importante ao escrever APIs que serão usadas por aplicativos fora da sua organização.
Como exemplo, aqui está um exemplo de código para enviar um SMS usando a API de bulksms:
http://developer.bulksms.com/eapi/code-samples/csharp/send_sms/
a partir daí é a linha:
onde 2 e 2.0 são números de versão da API.
Como essa API é destinada ao uso por muitos clientes de SMS em massa, uma alteração nessa API poderia interromper muitos aplicativos e fazer com que o telefone de suporte tocasse rapidamente.
fonte