{"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":"Quindi RAML o OAS (Swagger)?","gt_translate_keys":[{"key":"rendered","format":"text"}]},"content":{"rendered":"

Nel mondo dinamico dei microservizi pu\u00f2 cambiare qualsiasi cosa: ogni componente pu\u00f2 essere riscritto in un'altra lingua, utilizzando diversi framework e architetture. Gli unici elementi che devono rimanere invariati sono i contratti, affinch\u00e9 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. <\/p>\n

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

Microservizi.<\/b> Durante lo sviluppo di Acronis Cyber Cloud ci siamo resi conto che non potevamo evitarli. La progettazione di un microservizio \u00e8 impossibile senza formalizzare il contratto, che rappresenta l'interfaccia del microservizio.<\/p>\n

Ma quando nel prodotto c'\u00e8 pi\u00f9 di un componente, e lo sviluppo di contratti diventa un'attivit\u00e0 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\u00e0 costretto a spendere tempo a ripetere queste scelte. <\/p>\n

\"Quindi
\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 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\u00e0 di scegliere uno degli standard. Ma, come si \u00e8 rivelato, fare questa scelta pu\u00f2 essere molto complicato.<\/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 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\u00e9 dei codici di risposta e dei formati di risposta. Un elemento estremamente importante dell'annotazione del contratto \u00e8 anche la loro descrizione verbale (\"cosa succeder\u00e0 se aggiungo questo parametro di query alla richiesta?\", \"in quale caso verr\u00e0 restituito il codice 400?\")<\/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 gran numero di linguaggi di programmazione. Inoltre, si pu\u00f2 ottenere automaticamente la documentazione per il microservizio e caricarla sul vostro developer-portal :).<\/p>\n

\"Quindi
\nEsempio di descrizione strutturata di un contratto<\/i><\/p>\n

\u00c8 meno comune la pratica di testare i microservizi basandosi sulle descrizioni dei contratti. Se hai scritto sia l'annotazione che il componente, \u00e8 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\u00e0 in grado di gestire correttamente dati manifestamente errati?<\/p>\n

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.<\/p>\n

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

In generale, c'\u00e8 uno spazio enorme per la creativit\u00e0 nell'applicazione dei contratti per i microservizi... almeno in teoria<\/p>\n

Confronto tra un riccio e un serpente<\/h3>\n

\nAttualmente, la direzione prioritaria dello sviluppo in Acronis \u00e8 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\u00e0 di pubblicare API ha nuovamente sollevato la questione della scelta: quale standard di annotazioni \u00e8 meglio utilizzare per il nostro lavoro?<\/p>\n

Inizialmente sembrava che le soluzioni fossero due: le pi\u00f9 comuni implementazioni di 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, quindi questo formato \u00e8 pi\u00f9 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.<\/p>\n

Ma lo sviluppatore di RAML, l'azienda Mulesoft, si \u00e8 unita al consorzio Open API, che si occupa dello sviluppo di Swagger<\/a><\/noindex>. Pertanto, lo sviluppo di RAML \u00e8 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 \u2014 la terza \u2014 sta praticamente recuperando terreno rispetto a RAML in termini di flessibilit\u00e0 e funzionalit\u00e0.<\/p>\n

Se non fosse per una cosa\u2026<\/h3>\n

\nA 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 go-swagger<\/a><\/noindex> alla nuova versione dello standard sar\u00e0 la pi\u00f9 critica. Tuttavia, la differenza tra Swagger 2 e Swagger 3 \u00e8 enorme<\/a><\/noindex>. Ad esempio, nella terza versione gli sviluppatori:<\/p>\n