Come organizzi i contratti dell'endpoint API

La soluzione più semplice IMO sarebbe quella di utilizzare le richieste di pull e una buona copertura di test automatizzata. È un cambio di paradigma per coloro che non sono abituati, ma i benefici sono innegabili.

Github ha alcuni buoni documenti: link così come BitBucket: link

I PR funzionano solo quando l'intera squadra è a bordo. Quando viene inviato un nuovo PR, tutti gli sviluppatori tranne quelli sul percorso critico dovrebbero interrompere ciò che stanno facendo e richiedere alcuni minuti per rivedere il PR e lasciare commenti come: this code will break the current contract for the Xyz method, please revisit o looks good . Molti sviluppatori lasceranno semplicemente un +1 se pensano che il codice debba essere unito. Una volta che hai ottenuto abbastanza occhi e approvazioni sul codice, può essere unito al ramo development .

Inoltre, farei in modo che il team mantenga buoni test automatizzati.

Se non usi git , Github o BitBucket e non puoi o non vuoi cambiare ...

Potresti avvicinarti a questo in un paio di modi diversi:

1. Un sistema interno: questo genererebbe e servirà la documentazione API / Endpoint sulla base di firme e commenti di metodo. È possibile utilizzare uno strumento automatico per generare la documentazione in formato HTML. Il problema con questo è che gli sviluppatori possono facilmente cambiare i contratti (firme del metodo) e commettere quel codice che rompe le cose. Il vantaggio sarebbe praticamente zero manutenzione e un'interfaccia leggibile / ricercabile per gli sviluppatori per scoprire contratti endpoint esistenti.

2. Un sistema esterno: questo suona più come vuoi tu. Potresti farlo in molti modi diversi. Un modo sarebbe utilizzare uno strumento di documentazione come Yard per generare i documenti di base attuali, quindi assegnare il compito di modificarli ogni volta che un contratto deve essere modificato. Facendolo in questo modo ti permetterebbe di configurare un web stack separato (esterno) come servizio. Un altro modo sarebbe quello di creare un'app separata che modella la funzionalità desiderata. Avrebbe Klass e Method modelli. Lo svantaggio sarebbe che qualcuno dovrebbe mantenerlo. Il vantaggio sarebbe che gli sviluppatori non potevano facilmente cambiare i contratti, o affatto se si limitava l'accesso al codice.

In base ai tuoi casi d'uso sopra, tenderei ad andare con un'app separata. È possibile avere un'interfaccia di manutenzione per un responsabile del team o un amministratore per modificare un contratto e una versione dell'API / endpoint. Potresti anche avere un'interfaccia di sola lettura per gli sviluppatori per cercare le cose.

Flusso di lavoro:

• Bug arriva alla scrivania degli sviluppatori.
• Lo sviluppatore trova la radice del problema in un metodo particolare.
• Lo sviluppatore ricerca il metodo sul sito del contratto esterno e scopre che è necessario modificare il valore restituito che interromperà il contratto.
• Lo sviluppatore porta la scoperta al caposquadra o cambia scheda di controllo
• Team Lead assegna allo sviluppatore di modificare anche il codice che si interrompe a causa della modifica, di conseguenza
• Lo sviluppatore scrive codice per correggere il bug (e si spera che i test automatizzati)
• A questo punto lo sviluppatore dovrebbe eseguire una suite di test di regressione completa per assicurarsi che nessuno del nuovo codice abbia violato qualcosa di inaspettato.
• Lo sviluppatore commette la (risolta) correzione di bug

Ho finito per fare questo, usando i test come documentazione interna per i contratti link