{"id":38022,"date":"2019-10-31T22:21:14","date_gmt":"2019-10-31T19:21:14","guid":{"rendered":"https:\/\/prohoster.info\/blog\/tak-vse-taki-raml-ili-oas-swagger\/"},"modified":"2019-10-31T22:21:14","modified_gmt":"2019-10-31T19:21:14","slug":"tak-vse-taki-raml-ili-oas-swagger","status":"publish","type":"post","link":"https:\/\/prohoster.info\/it\/blog\/administrirovanie\/tak-vse-taki-raml-ili-oas-swagger","title":{"rendered":"Ma quindi RAML o OAS (Swagger)?","gt_translate_keys":[{"key":"rendered","format":"text"}]},"content":{"rendered":"

Nel dinamico mondo dei microservizi, tutto pu\u00f2 cambiare \u2014 qualsiasi componente pu\u00f2 essere riscritto in un altro linguaggio, utilizzando framework e architetture diversi. Ci\u00f2 che deve rimanere invariato sono solo i contratti, affinch\u00e9 sia possibile interagire con il microservizio dall'esterno su una base costante, indipendentemente dalle metamorfosi interne. Oggi parleremo del nostro dilemma nella scelta del formato di descrizione dei contratti e condivideremo gli artefatti trovati. <\/p>\n

\"Ma
\n<\/a><\/noindex>
\nPost preparato da Anna Melekhova<\/a><\/noindex> e Vladimir Lapatin<\/a><\/noindex> <\/p>\n

Microservizi.<\/b> Nello sviluppo di Acronis Cyber Cloud abbiamo capito che non possiamo fare a meno dei microservizi. La progettazione di un microservizio \u00e8 impossibile senza la formalizzazione di un contratto, che rappresenta l'interfaccia del microservizio.<\/p>\n

Tuttavia, quando un prodotto contiene pi\u00f9 di un componente e lo sviluppo del contratto diventa un'attivit\u00e0 regolare, ci si inizia a chiedere come ottimizzare il processo. Diventa evidente che l'interfaccia (contratto) e l'implementazione (microservizio) devono corrispondere, che diversi componenti devono svolgere le stesse funzioni in modo uniforme e che, senza una centralizzazione di tutte queste decisioni, ogni squadra si trover\u00e0 a spendere tempo ripetutamente per ottenerle. <\/p>\n

\"Ma
\nSchema dei microservizi di Amazon da un tweet<\/a><\/noindex> di Werner Vogels, CTO di Amazon<\/i>
\nQual \u00e8 dunque il dilemma? De facto ci sono due modi di interazione tra microservizi \u2013 HTTP Rest e gRPC di Google. Non volendo essere coinvolti nel stack tecnologico di Google, abbiamo scelto HTTP Rest. Le annotazioni sui contratti HTTP REST sono per lo pi\u00f9 descritte in uno dei due formati: RAML e OAS, precedentemente noto come Swagger. Pertanto, ogni squadra di sviluppo si trova di fronte alla necessit\u00e0 di scegliere uno degli standard. Ma, come \u00e8 emerso, effettuare questa scelta pu\u00f2 rivelarsi molto difficile.<\/p>\n

A cosa servono le annotazioni?<\/h3>\n

\nL'annotazione \u00e8 necessaria affinch\u00e9 l'utente esterno possa facilmente comprendere cosa si pu\u00f2 fare con il proprio servizio attraverso la sua interfaccia HTTP. Cio\u00e8, a un livello di base, l'annotazione dovrebbe contenere almeno un elenco delle risorse disponibili, i relativi metodi HTTP, i corpi delle richieste, l'elenco dei parametri, l'indicazione degli header necessari e supportati, nonch\u00e9 i codici di risposta e i formati delle risposte. Un elemento estremamente importante dell'annotazione del contratto \u00e8 anche la loro descrizione verbale (\u201ccosa succede se si aggiunge questo query-parameter alla richiesta?\u201d, \u201cin quale caso verr\u00e0 restituito il codice 400?\u201d)<\/p>\n

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, \u00e8 possibile generare sia codice client che server in un'enorme variet\u00e0 di linguaggi di programmazione. Inoltre \u00e8 possibile ottenere automaticamente la documentazione per il microservizio e caricarla sul proprio developer-portal :).<\/p>\n

\"Ma
\nEsempio di descrizione strutturata del contratto<\/i><\/p>\n

Raramente si incontra la pratica di testare i microservizi sulla base delle descrizioni dei contratti. Se hai scritto sia l'annotazione che il componente, puoi creare un test automatico che verifica l'adeguatezza del funzionamento del servizio con diversi tipi di dati in ingresso. Il servizio restituisce un codice di risposta non descritto nell'annotazione? Sar\u00e0 in grado di gestire correttamente dati palesemente errati?<\/p>\n

Inoltre, una realizzazione di qualit\u00e0 non solo dei contratti stessi, ma anche degli strumenti per visualizzare le annotazioni consente di semplificare il lavoro con il microservizio. Cio\u00e8, se l'architetto ha descritto accuratamente il contratto, sulla base di esso, designer e sviluppatori potranno implementare il servizio in altri prodotti senza costi di tempo aggiuntivi.<\/p>\n

Per il funzionamento di strumenti aggiuntivi, sia RAML che OAS hanno la possibilit\u00e0 di aggiungere metadati non previsti dallo standard (per esempio, cos\u00ec facendo in OAS<\/a><\/noindex>).<\/p>\n

In generale, il campo per la creativit\u00e0 nell'applicazione dei contratti ai microservizi \u00e8 enorme\u2026 almeno teoricamente<\/p>\n

Confronto tra una lucertola e un riccio<\/h3>\n

\nAttualmente, la principale direzione di sviluppo in Acronis \u00e8 l'evoluzione di Acronis Cyber Platform. Acronis Cyber Platform rappresenta nuovi punti di integrazione di servizi di terze parti con Acronis Cyber Cloud e la parte agent. Anche se le nostre API interne, descritte in RAML, ci soddisfacevano, la necessit\u00e0 di pubblicare l'API ha di nuovo sollevato la questione della scelta: quale standard di annotazioni \u00e8 meglio utilizzare per il nostro lavoro?<\/p>\n

Inizialmente sembrava che ci fossero due soluzioni \u2014 le pi\u00f9 diffuse erano RAML e Swagger (o OAS). Ma in realt\u00e0 si \u00e8 rivelato che le alternative sono almeno 3 o pi\u00f9.<\/p>\n

Da un lato c'\u00e8 RAML, un linguaggio potente ed efficiente. Presenta una buona implementazione della gerarchia e dell'ereditariet\u00e0, rendendo questo formato pi\u00f9 adatto per grandi aziende che necessitano di molte descrizioni, cio\u00e8 non un solo prodotto, ma molti microservizi con parti comuni nei contratti, come schemi di autenticazione, tipi di dati identici e corpi di errore.<\/p>\n

Tuttavia, lo sviluppatore di RAML, la societ\u00e0 Mulesoft, si \u00e8 unita al consorzio Open API, che si occupa dello sviluppo Swagger<\/a><\/noindex>. Pertanto, lo sviluppo di RAML \u00e8 stato sospeso. Per immaginare il formato evento, si potrebbe pensare a come i manutentori dei componenti principali di Linux siano andati a lavorare per Microsoft. Tale situazione crea presupposti per l'uso di Swagger, che si sviluppa dinamicamente e, con la sua terza versione, sta quasi raggiungendo RAML in termini di flessibilit\u00e0 e funzionalit\u00e0.<\/p>\n

Se non fosse per un piccolo particolare...<\/h3>\n

\nA quanto pare, non tutte le utilit\u00e0 open-source sono state aggiornate alla versione OAS 3.0. Per i microservizi su Go, il problema pi\u00f9 critico \u00e8 l'assenza di adattamento del go-swagger<\/a><\/noindex> alla nuova versione dello standard. Tuttavia, la differenza tra Swagger 2 e Swagger 3 \u00e8 enorme<\/a><\/noindex>. Ad esempio, nella terza versione gli sviluppatori:<\/p>\n