Nel mondo dinamico dei microservizi, tutto può cambiare: qualsiasi componente può essere riscritto in un linguaggio diverso, utilizzando framework e architetture diversi. Solo i contratti dovrebbero rimanere invariati in modo che il microservizio possa essere interagito dall’esterno in modo permanente, indipendentemente dalle metamorfosi interne. E oggi parleremo del nostro problema di scegliere un formato per descrivere i contratti e condividere gli artefatti che abbiamo trovato.
Posta preparata и
Microservizi. Durante lo sviluppo di Acronis Cyber Cloud, ci siamo resi conto che non potevamo sfuggirgli. E progettare un microservizio è impossibile senza formalizzare il contratto, che rappresenta l’interfaccia del microservizio.
Ma quando un prodotto contiene più di un componente e lo sviluppo del contratto diventa un'attività regolare, non si può fare a meno di iniziare a pensare all'ottimizzazione dei processi. Diventa ovvio che l’interfaccia (contratto) e l’implementazione (microservizio) devono corrispondere tra loro, che i diversi componenti devono fare le stesse cose nello stesso modo e che senza un processo decisionale centralizzato di tutte queste decisioni, ogni team sarà costretto a spendere tempo ancora e ancora per ottenerli.
Diagramma dei microservizi Amazon da Werner Vogelis, direttore tecnico di Amazon
Qual è il dilemma? Di fatto, esistono due modi per interagire con i microservizi: HTTP Rest e gRPC di Google. Non volendo rimanere intrappolati nello stack tecnologico di Google, abbiamo scelto HTTP Rest. Le annotazioni del contratto HTTP REST sono spesso descritte in uno dei due formati: RAML e OAS, precedentemente noto come Swagger, pertanto ogni team di sviluppo si trova di fronte alla necessità di scegliere uno degli standard. Ma a quanto pare, fare questa scelta può essere molto difficile.
Perché sono necessarie le annotazioni?
L'annotazione è necessaria affinché un utente esterno possa facilmente capire cosa si può fare con il tuo servizio attraverso la sua interfaccia HTTP. Cioè, a livello base, l'annotazione deve contenere almeno un elenco delle risorse disponibili, i relativi metodi HTTP, i corpi delle richieste, un elenco di parametri, un'indicazione delle intestazioni richieste e supportate, nonché codici di ritorno e formati di risposta. Un elemento estremamente importante dell'annotazione del contratto è la loro descrizione verbale (“cosa succederà se aggiungi questo parametro di query alla richiesta?”, “In che caso verrà restituito il codice 400?”)
Tuttavia, quando si tratta di sviluppare un gran numero di microservizi, è necessario estrarre ulteriore valore dalle annotazioni scritte. Ad esempio, basandosi su RAML/Swagger, puoi generare sia codice client che server in un numero enorme di linguaggi di programmazione. Puoi anche ricevere automaticamente la documentazione per il microservizio e caricarla sul tuo portale per sviluppatori :).
Esempio di descrizione di un contratto strutturato
Meno comune è la pratica di testare i microservizi in base alle descrizioni dei contratti. Se hai scritto sia un'annotazione che un componente, allora puoi creare un autotest che verifica l'adeguatezza del servizio con vari tipi di dati di input. Il servizio restituisce un codice di risposta non descritto nell'annotazione? Sarà in grado di elaborare correttamente dati evidentemente errati?
Inoltre, l'implementazione di alta qualità non solo dei contratti stessi, ma anche degli strumenti per la visualizzazione delle annotazioni consente di semplificare il lavoro con il microservizio. Cioè, se l'architetto descrive qualitativamente il contratto, sulla base di esso, progettisti e sviluppatori implementeranno il servizio in altri prodotti senza costi di tempo aggiuntivi.
Per abilitare strumenti aggiuntivi, sia RAML che OAS hanno la possibilità di aggiungere metadati non previsti dallo standard ().
In generale, lo spazio per la creatività nell’utilizzo dei contratti per i microservizi è enorme… almeno in teoria.
Confronto tra un riccio e un serpente
Attualmente, l'area di sviluppo prioritaria in Acronis è lo sviluppo della Acronis Cyber Platform. Acronis Cyber Platform rappresenta nuovi punti di integrazione di servizi di terze parti con Acronis Cyber Cloud e la parte agente. Sebbene fossimo soddisfatti delle nostre API interne descritte in RAML, la necessità di pubblicare l'API ha sollevato nuovamente la questione della scelta: quale standard di annotazione è meglio utilizzare per il nostro lavoro?
Inizialmente sembrava che esistessero due soluzioni: gli sviluppi più comuni erano RAML e Swagger (o OAS). Ma in realtà si è scoperto che almeno non ci sono 2 alternative, ma 3 o più.
Da un lato c'è RAML, un linguaggio potente ed efficiente. Implementa bene la gerarchia e l'ereditarietà, quindi questo formato è più adatto per le grandi aziende che necessitano di molte descrizioni, ovvero non un prodotto, ma molti microservizi che hanno parti comuni di contratti: schemi di autenticazione, stessi tipi di dati, corpi di errore .
Ma lo sviluppatore di RAML, Mulesoft, si è unito al consorzio Open API, che sta sviluppando . Pertanto, RAML ne ha sospeso lo sviluppo. Per immaginare il formato dell'evento, immagina che i manutentori dei principali componenti Linux siano partiti per lavorare per Microsoft. Questa situazione crea i prerequisiti per l'utilizzo di Swagger, che si sta sviluppando in modo dinamico e nell'ultima - la terza versione - praticamente raggiunge RAML in termini di flessibilità e funzionalità.
Se non per una cosa ma...
A quanto pare, non tutte le utility open source sono state aggiornate a OAS 3.0. Per i microservizi in Go, la cosa più critica sarà la mancanza di adattamento per l'ultima versione dello standard. Tuttavia, la differenza tra Swagger 2 e Swagger 3 è . Ad esempio, nella terza versione gli sviluppatori:
- descrizione migliorata degli schemi di autenticazione
- Supporto dello schema JSON
- migliorata la possibilità di aggiungere esempi
La situazione è divertente: quando si sceglie uno standard, è necessario considerare RAML, Swagger 2 e Swagger 3 come alternative separate. Tuttavia, solo Swagger 2 ha un buon supporto per gli strumenti OpenSource. RAML è molto flessibile...e complessa e Swagger 3 è scarsamente supportato dalla comunità, quindi dovrai utilizzare strumenti proprietari o soluzioni commerciali, che tendono ad essere piuttosto costose.
Inoltre, se ci sono molte funzionalità interessanti in Swagger, come un portale già pronto , su cui è possibile caricare un'annotazione e ottenerne la visualizzazione con una descrizione dettagliata, collegamenti e connessioni, quindi per la RAML più fondamentale e meno amichevole non esiste tale opportunità. Sì, puoi cercare qualcosa tra i progetti su GitHub, trovare un analogo lì e distribuirlo tu stesso. Tuttavia, in ogni caso, qualcuno dovrà mantenere il portale, il che non è così conveniente per esigenze di utilizzo o di test di base. Inoltre, la spavalderia è più "senza principi" o più liberale: può essere generata dai commenti nel codice, il che, ovviamente, va contro il principio API First e non è supportato da nessuna delle utilità RAML.
Un tempo abbiamo iniziato a lavorare con RAML come linguaggio più flessibile e di conseguenza abbiamo dovuto fare molte cose da soli. Ad esempio, uno dei progetti utilizza l'utilità nei test unitari, che supportano solo RAML 0.8. Quindi abbiamo dovuto aggiungere delle stampelle in modo che l'utilità potesse "mangiare" RAML versione 1.0.
Hai bisogno di scegliere?
Dopo aver lavorato al completamento dell'ecosistema di soluzioni per RAML, siamo giunti alla conclusione che dobbiamo convertire RAML in Swagger 2 ed eseguire in esso tutta l'automazione, la verifica, i test e la successiva ottimizzazione. Questo è un buon modo per sfruttare sia la flessibilità di RAML che il supporto degli strumenti della community di Swagger.
Per risolvere questo problema, esistono due strumenti OpenSource che dovrebbero fornire la conversione del contratto:
- è un'utilità attualmente non supportata. Mentre lo lavoravamo, abbiamo scoperto che presenta una serie di problemi con RAML complesse che sono "distribuite" su un gran numero di file. Questo programma è scritto in JavaScript ed esegue un attraversamento ricorsivo di un albero della sintassi. A causa della digitazione dinamica, diventa difficile comprendere questo codice, quindi abbiamo deciso di non perdere tempo a scrivere patch per un'utilità in via di estinzione.
- - uno strumento della stessa azienda che afferma di essere pronto a convertire qualsiasi cosa e in qualsiasi direzione. Ad oggi è stato annunciato il supporto per RAML 0.8, RAML 1.0 e Swagger 2.0. Tuttavia, al momento della nostra ricerca, l’utilità era ancora umido e inutilizzabile. Gli sviluppatori creano una sorta di , consentendo loro di aggiungere rapidamente nuovi standard in futuro. Ma finora semplicemente non funziona.
E queste non sono tutte le difficoltà che abbiamo incontrato. Uno dei passaggi della nostra pipeline è verificare che la RAML dal repository sia corretta rispetto alla specifica. Abbiamo provato diverse utilità. Sorprendentemente, tutti hanno imprecato contro le nostre annotazioni in luoghi diversi e con parolacce completamente diverse. E non sempre al punto :).
Alla fine, abbiamo optato per un progetto ormai obsoleto, che presenta anche una serie di problemi (a volte si blocca all'improvviso, ha problemi quando si lavora con le espressioni regolari). Pertanto non abbiamo trovato un modo per risolvere i problemi di validazione e conversione basandoci su strumenti gratuiti e abbiamo deciso di utilizzare un'utilità commerciale. In futuro, man mano che gli strumenti OpenSource diventeranno più maturi, questo problema potrebbe diventare più facile da risolvere. Nel frattempo, il costo della manodopera e del tempo per la “finitura” ci è sembrato più significativo del costo di un servizio commerciale.
conclusione
Dopo tutto questo, volevamo condividere la nostra esperienza e sottolineare che prima di scegliere uno strumento per descrivere i contratti, è necessario definire chiaramente cosa si vuole da esso e quale budget si è disposti a investire. Se dimentichiamo OpenSource, esistono già numerosi servizi e prodotti che ti aiuteranno a controllare, convertire e convalidare. Ma sono costosi e talvolta molto costosi. Per una grande azienda tali costi sono tollerabili, ma per una startup possono diventare un grosso onere.
Determina il set di strumenti che utilizzerai in seguito. Ad esempio, se devi solo visualizzare un contratto, sarà più semplice utilizzare Swagger 2, che ha una bellissima API, perché in RAML dovrai costruire e mantenere il servizio da solo.
Più compiti hai, più ampia sarà la necessità di strumenti, che sono diversi per le diverse piattaforme, ed è meglio familiarizzare immediatamente con le versioni disponibili per fare una scelta che riduca al minimo i costi in futuro.
Ma vale la pena riconoscere che tutti gli ecosistemi esistenti oggi sono imperfetti. Quindi, se in azienda ci sono fan a cui piace lavorare in RAML perché “permette di esprimere i propri pensieri in modo più flessibile” o, al contrario, preferiscono Swagger perché “è più chiaro”, è meglio lasciarli lavorare. in quello che sono Sono abituati e lo vogliono, perché gli strumenti di qualsiasi formato richiedono la modifica con un file.
Per quanto riguarda la nostra esperienza, nei post successivi parleremo di quali controlli statici e dinamici conduciamo in base alla nostra architettura RAML-Swagger, nonché di quale documentazione generiamo dai contratti e di come funziona il tutto.
Solo gli utenti registrati possono partecipare al sondaggio. Per favore.
Quale linguaggio utilizzi per annotare i contratti di microservizio?
-
RAML0.8
-
RAML1.0
-
Spavalderia 2
-
OAS3 (alias)
-
Cianografia
-
Altro
-
Non utilizzando
100 utenti hanno votato. 24 utenti si sono astenuti.
Fonte: habr.com