Nel mondo dinamico dei microservizi può cambiare qualsiasi cosa: ogni componente può essere riscritto in un'altra lingua, utilizzando diversi framework e architetture. Gli unici elementi che devono rimanere invariati sono i contratti, affinché si possa interagire con i microservizi in modo costante, indipendentemente dalle metamorfosi interne. Oggi parleremo del nostro problema nella scelta del formato di descrizione dei contratti e condivideremo gli artefatti trovati.
Post preparato da e
Microservizi. Durante lo sviluppo di Acronis Cyber Cloud ci siamo resi conto che non potevamo evitarli. La progettazione di un microservizio è impossibile senza formalizzare il contratto, che rappresenta l'interfaccia del microservizio.
Ma quando nel prodotto c'è più di un componente, e lo sviluppo di contratti diventa un'attività regolare, si comincia a pensare a come ottimizzare il processo. Diventa evidente che l'interfaccia (contratto) e l'implementazione (microservizio) devono corrispondere, che i diversi componenti devono fare le stesse cose in modo coerente e che senza un processo centralizzato per prendere tutte queste decisioni, ogni team sarà costretto a spendere tempo a ripetere queste scelte.
Schema dei microservizi di Amazon da di Werner Vogels, CTO di Amazon
Qual è dunque il dilemma? De facto ci sono due modi per interagire fra microservizi: HTTP Rest e gRPC di Google. Non volendo essere coinvolti nello stack tecnologico di Google, abbiamo scelto HTTP Rest. Le annotazioni per i contratti HTTP Rest vengono solitamente 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, come si è rivelato, fare questa scelta può essere molto complicato.
A cosa servono le annotazioni?
L'annotazione è necessaria affinché l'utente esterno possa facilmente comprendere cosa si può fare con il tuo servizio tramite la sua interfaccia HTTP. In altre parole, a un livello base, l'annotazione dovrebbe contenere almeno un elenco delle risorse disponibili, i loro metodi HTTP, i corpi delle richieste, un elenco dei parametri, l'indicazione degli header necessari e supportati, nonché dei codici di risposta e dei formati di risposta. Un elemento estremamente importante dell'annotazione del contratto è anche la loro descrizione verbale ("cosa succederà se aggiungo questo parametro di query alla richiesta?", "in quale caso verrà restituito il codice 400?")
Tuttavia, quando si tratta di sviluppare un gran numero di microservizi, si desidera estrarre ulteriore valore dalle annotazioni scritte. Ad esempio, sulla base di RAML/Swagger, è possibile generare sia codice client che server in un gran numero di linguaggi di programmazione. Inoltre, si può ottenere automaticamente la documentazione per il microservizio e caricarla sul vostro developer-portal :).
Esempio di descrizione strutturata di un contratto
È meno comune la pratica di testare i microservizi basandosi sulle descrizioni dei contratti. Se hai scritto sia l'annotazione che il componente, è possibile creare un test automatico che verifica l'adeguatezza del funzionamento del servizio con vari tipi di dati in ingresso. Il servizio restituisce un codice di risposta non descritto nell'annotazione? Sarà in grado di gestire correttamente dati manifestamente errati?
Inoltre, una buona implementazione non solo dei contratti stessi, ma anche degli strumenti per la visualizzazione delle annotazioni consente di semplificare il lavoro con il microservizio. In altre parole, se l'architetto ha descritto il contratto in modo efficace, i designer e gli sviluppatori saranno in grado di integrare il servizio in altri prodotti senza ulteriori perdite di tempo.
Per consentire il funzionamento di strumenti aggiuntivi, sia RAML che OAS hanno la possibilità di aggiungere metadati non previsti dallo standard ().
In generale, c'è uno spazio enorme per la creatività nell'applicazione dei contratti per i microservizi... almeno in teoria
Confronto tra un riccio e un serpente
Attualmente, la direzione prioritaria dello sviluppo in Acronis è l'evoluzione della Acronis Cyber Platform. La Acronis Cyber Platform rappresenta nuovi punti di integrazione per i servizi di terze parti con Acronis Cyber Cloud e il suo lato agenziale. Anche se le nostre API interne, descritte in RAML, ci soddisfacevano, la necessità di pubblicare API ha nuovamente sollevato la questione della scelta: quale standard di annotazioni è meglio utilizzare per il nostro lavoro?
Inizialmente sembrava che le soluzioni fossero due: le più comuni implementazioni di RAML e Swagger (o OAS). Ma in realtà si è rivelato che le alternative sono almeno 3 o più.
Da un lato c'è RAML, un linguaggio potente ed efficiente. Presenta una buona implementazione della gerarchia e dell'ereditarietà, quindi questo formato è più adatto per grandi aziende che necessitano di molte descrizioni, ovvero non un solo prodotto, ma diversi microservizi che condividono parti comuni dei contratti: schemi di autenticazione, tipi di dati identici, corpi di errore.
Ma lo sviluppatore di RAML, l'azienda Mulesoft, si è unita al consorzio Open API, che si occupa dello sviluppo di . Pertanto, lo sviluppo di RAML è stato sospeso. Per immaginare il formato dell'evento, pensate che i manutentori dei componenti fondamentali di Linux siano andati a lavorare in Microsoft. Una situazione del genere crea presupposti per utilizzare Swagger, che si evolve dinamicamente e nell'ultima versione — la terza — sta praticamente recuperando terreno rispetto a RAML in termini di flessibilità e funzionalità.
Se non fosse per una cosa…
A quanto pare, non tutte le utility open-source si sono aggiornate alla versione OAS 3.0. Per i microservizi in Go, la mancanza di adattamento del alla nuova versione dello standard sarà la più critica. Tuttavia, la differenza tra Swagger 2 e Swagger 3 è . Ad esempio, nella terza versione gli sviluppatori:
- hanno migliorato la descrizione degli schemi di autenticazione
- il supporto per JSON Schema
- hanno potenziato la possibilità di aggiungere esempi
La situazione risulta interessante: nella scelta dello standard è necessario considerare RAML, Swagger 2 e Swagger 3 come alternative distinte. Solo Swagger 2 offre un buon supporto per gli strumenti Open Source. RAML è molto flessibile… e complesso, mentre Swagger 3 è poco supportato dalla comunità, quindi dovrete fare affidamento su strumenti sviluppati internamente o soluzioni commerciali che, generalmente, hanno un costo piuttosto elevato.
Inoltre, se in Swagger ci sono molte funzioni interessanti, come un portale pronto all'uso , sul quale è possibile caricare un'annotazione e ottenere la sua visualizzazione con una descrizione dettagliata, link e relazioni, mentre per il RAML, che è più fondamentale e meno user-friendly, questa possibilità non è presente. È possibile cercare qualcosa tra i progetti su GitHub, trovare un equivalente e implementarlo autonomamente. Tuttavia, in ogni caso, qualcuno dovrà gestire il portale, il che non è molto conveniente per un utilizzo base o per scopi di test. Inoltre, Swagger è più "senza principi", o liberale — può essere generato dai commenti nel codice, il che, ovviamente, contrasta con il principio API first e non è supportato da nessuno degli strumenti RAML.
Un tempo, abbiamo iniziato a lavorare con RAML, come un linguaggio più flessibile, e alla fine abbiamo dovuto fare molto da soli. Ad esempio, in uno dei progetti si utilizza un'utilità nei test unitari, che supporta solo RAML 0.8. Quindi abbiamo dovuto aggiungere dei workaround affinché l'utilità potesse "gestire" RAML versione 1.0.
È necessario scegliere?
Dopo aver esplorato l'ecosistema delle soluzioni per RAML, siamo giunti alla conclusione che dovevamo convertire RAML in Swagger 2 e svolgere tutta l'automazione, verifica, test e successiva ottimizzazione in questo formato. È un ottimo modo per utilizzare sia la flessibilità di RAML sia il supporto degli strumenti della comunità di Swagger.
Per affrontare questa problematica esistono due strumenti OpenSource che dovrebbero garantire la conversione dei contratti:
- – un'utilità attualmente non supportata. Durante il lavoro con essa abbiamo scoperto che presenta una serie di problemi con i RAML complessi, che sono "sparsi" su un gran numero di file. Questo programma è scritto in JavaScript e esegue una traversata ricorsiva dell'albero sintattico. A causa della tipizzazione dinamica, diventa difficile comprendere questo codice, quindi abbiamo deciso di non perdere tempo a scrivere patch per un'utilità in fase di estinzione.
- — uno strumento della stessa azienda, che pretende di poter convertire tutto e di tutto, in entrambe le direzioni. Ad oggi, è dichiarato il supporto per RAML 0.8, RAML 1.0 e Swagger 2.0. Tuttavia, al momento della nostra ricerca, l'utilità era ancora instabile e inadeguata per l'uso. Gli sviluppatori creano una sorta di , che permetterà loro di aggiungere rapidamente nuovi standard in futuro. Ma per ora tutto ciò semplicemente non funziona.
E questa non è nemmeno l'unica difficoltà che abbiamo affrontato. Uno dei passaggi del nostro pipeline è verificare che il RAML del repository sia conforme alla specifica. Abbiamo provato diversi strumenti. Sorprendentemente, tutti si sono lamentati delle nostre annotazioni in vari punti e con parole molto poco gentili. E non sempre a buon diritto :).
Alla fine ci siamo fermati su un progetto ora obsoleto, che ha anche una serie di problemi (a volte si blocca senza motivo, ha problemi con le espressioni regolari). Di conseguenza, non siamo riusciti a trovare un modo per risolvere i problemi di validazione e conversione basandoci su strumenti gratuiti e abbiamo deciso di utilizzare uno strumento commerciale. In futuro, quando gli strumenti Open Source saranno più sviluppati, la risoluzione di questo problema potrebbe diventare più semplice. Per ora, i costi in termini di tempo e lavoro per "aggiustare" ci sono sembrati più significativi rispetto al costo del servizio commerciale.
Conclusione
Dopo tutto questo, abbiamo avuto voglia di condividere la nostra esperienza e sottolineare che, prima di scegliere uno strumento per descrivere i contratti, è necessario definire chiaramente cosa si desidera e quale budget si è pronti a investire. Se si ignora l'Open Source, ci sono già molti servizi e prodotti che possono aiutare a fare verifiche, convertire e validare. Ma costano caro, e a volte – carissimo. Per una grande azienda, tali costi sono sostenibili, ma per una startup possono rappresentare un grande peso.
Definire un insieme di strumenti che utilizzerai in seguito. Ad esempio, se hai bisogno solo di visualizzare il contratto, sarà più semplice usare Swagger 2, che ha una bellissima API, mentre con RAML dovrai attivare e mantenere il servizio da solo.
Più saranno le tue esigenze, maggiore sarà la necessità di strumenti, che sono diversi per diverse piattaforme, ed è meglio informarsi subito sulle versioni disponibili per fare una scelta che minimizzi i tuoi costi futuri.
Ma va riconosciuto che tutti gli ecosistemi esistenti oggi non sono perfetti. Pertanto, se in azienda ci sono appassionati che amano lavorare in RAML perché "consente di esprimere le idee in modo più flessibile", o viceversa, che preferiscono Swagger perché "è più chiaro", è meglio lasciarli lavorare in quello che conoscono e desiderano, poiché gli strumenti di ciascuno dei formati richiedono un po' di lavoro di affinamento.
Per quanto riguarda la nostra esperienza, nei prossimi post parleremo di quali controlli statici e dinamici effettuiamo sulla nostra architettura RAML-Swagger, oltre a quale documentazione generiamo dai contratti e come tutto questo funzioni.
Solo gli utenti registrati possono partecipare al sondaggio. , per favore.
Quale linguaggio utilizzate per le annotazioni dei contratti dei microservizi?
RAML 0.8
RAML 1.0
Swagger 2
OAS3 (alias )
Blueprint
Altro
Non uso
Hanno votato 100 utenti. 24 utenti si sono astenuti.
Fonte: habr.com
