Στον δυναμικό κόσμο των μικροϋπηρεσιών, τα πάντα μπορούν να αλλάξουν—κάθε στοιχείο μπορεί να ξαναγραφτεί σε διαφορετική γλώσσα, χρησιμοποιώντας διαφορετικά πλαίσια και αρχιτεκτονική. Μόνο τα συμβόλαια πρέπει να παραμείνουν αμετάβλητα, έτσι ώστε η μικρουπηρεσία να μπορεί να αλληλεπιδρά εξωτερικά σε κάποια μόνιμη βάση, ανεξάρτητα από τις εσωτερικές μεταμορφώσεις. Και σήμερα θα μιλήσουμε για το πρόβλημά μας να επιλέξουμε μια μορφή για την περιγραφή των συμβολαίων και να μοιραστούμε τα αντικείμενα που βρήκαμε.
Έτοιμη η ανάρτηση и
Μικροϋπηρεσίες. Κατά την ανάπτυξη του Acronis Cyber Cloud, συνειδητοποιήσαμε ότι δεν μπορούσαμε να τους ξεφύγουμε. Και ο σχεδιασμός μιας microservice είναι αδύνατος χωρίς την επισημοποίηση της σύμβασης, η οποία αντιπροσωπεύει τη διεπαφή της microservice.
Αλλά όταν ένα προϊόν περιέχει περισσότερα από ένα συστατικά και η ανάπτυξη συμβάσεων γίνεται τακτική δραστηριότητα, δεν μπορείτε παρά να αρχίσετε να σκέφτεστε τη βελτιστοποίηση της διαδικασίας. Γίνεται προφανές ότι η διεπαφή (συμβόλαιο) και η υλοποίηση (microservice) πρέπει να ταιριάζουν μεταξύ τους, ότι διαφορετικά στοιχεία πρέπει να κάνουν τα ίδια πράγματα με τον ίδιο τρόπο και ότι χωρίς μια κεντρική λήψη αποφάσεων για όλες αυτές τις αποφάσεις, κάθε ομάδα θα αναγκαστεί να ξοδέψτε ξανά και ξανά για να τα αποκτήσετε.
Διάγραμμα microservices της Amazon από Werner Vogelis, CTO Amazon
Ποιο είναι το δίλημμα; Εκ των πραγμάτων, υπάρχουν δύο τρόποι αλληλεπίδρασης με μικροϋπηρεσίες - HTTP Rest και gRPC από την Google. Μη θέλοντας να εγκλωβιστούμε στη στοίβα τεχνολογίας της Google, επιλέξαμε το HTTP Rest. Οι σχολιασμοί συμβάσεων HTTP REST περιγράφονται συχνότερα σε μία από τις δύο μορφές: RAML και OAS, παλαιότερα γνωστές ως Swagger. Επομένως, κάθε ομάδα ανάπτυξης αντιμετωπίζει την ανάγκη να επιλέξει ένα από τα πρότυπα. Αλλά όπως αποδεικνύεται, η επιλογή αυτής της επιλογής μπορεί να είναι πολύ δύσκολη.
Γιατί χρειάζονται οι σχολιασμοί;
Ο σχολιασμός είναι απαραίτητος ώστε ένας εξωτερικός χρήστης να μπορεί εύκολα να καταλάβει τι μπορεί να γίνει με την υπηρεσία σας μέσω της διεπαφής HTTP. Δηλαδή, σε βασικό επίπεδο, ο σχολιασμός πρέπει να περιέχει τουλάχιστον μια λίστα διαθέσιμων πόρων, τις μεθόδους HTTP τους, τα σώματα αιτημάτων, μια λίστα παραμέτρων, μια ένδειξη των απαιτούμενων και υποστηριζόμενων κεφαλίδων, καθώς και κωδικούς επιστροφής και μορφές απόκρισης. Ένα εξαιρετικά σημαντικό στοιχείο του σχολιασμού της σύμβασης είναι η λεκτική περιγραφή τους ("τι θα συμβεί εάν προσθέσετε αυτήν την παράμετρο ερωτήματος στο αίτημα;", "Σε ποια περίπτωση θα επιστραφεί ο κωδικός 400;")
Ωστόσο, όταν πρόκειται για την ανάπτυξη μεγάλου αριθμού μικροϋπηρεσιών, θέλετε να εξαγάγετε πρόσθετη αξία από τους γραπτούς σχολιασμούς. Για παράδειγμα, με βάση το RAML/Swagger, μπορείτε να δημιουργήσετε κώδικα πελάτη και διακομιστή σε έναν τεράστιο αριθμό γλωσσών προγραμματισμού. Μπορείτε επίσης να λαμβάνετε αυτόματα τεκμηρίωση για την microservice και να την ανεβάσετε στην πύλη προγραμματιστή σας :).
Παράδειγμα δομημένης περιγραφής σύμβασης
Λιγότερο συνηθισμένη είναι η πρακτική της δοκιμής μικροϋπηρεσιών με βάση τις περιγραφές των συμβάσεων. Εάν έχετε γράψει και έναν σχολιασμό και ένα στοιχείο, τότε μπορείτε να δημιουργήσετε έναν αυτόματο έλεγχο που ελέγχει την επάρκεια της υπηρεσίας με διάφορους τύπους δεδομένων εισόδου. Επιστρέφει η υπηρεσία έναν κωδικό απόκρισης που δεν περιγράφεται στον σχολιασμό; Θα είναι σε θέση να επεξεργαστεί σωστά προφανώς λανθασμένα δεδομένα;
Επιπλέον, η εφαρμογή υψηλής ποιότητας όχι μόνο των ίδιων των συμβάσεων, αλλά και των εργαλείων για την οπτικοποίηση των σχολιασμών καθιστά δυνατή την απλοποίηση της εργασίας με την microservice. Δηλαδή, εάν ο αρχιτέκτονας περιέγραψε ποιοτικά τη σύμβαση, βάσει αυτής, οι σχεδιαστές και οι προγραμματιστές θα εφαρμόσουν την υπηρεσία σε άλλα προϊόντα χωρίς επιπλέον κόστος χρόνου.
Για να ενεργοποιηθούν πρόσθετα εργαλεία, τόσο το RAML όσο και το OAS έχουν τη δυνατότητα να προσθέτουν μεταδεδομένα που δεν προβλέπονται από το πρότυπο ().
Γενικά, τα περιθώρια δημιουργικότητας στη χρήση συμβολαίων για μικροϋπηρεσίες είναι τεράστια... τουλάχιστον θεωρητικά.
Σύγκριση σκαντζόχοιρου με φίδι
Επί του παρόντος, ο τομέας ανάπτυξης προτεραιότητας στο Acronis είναι η ανάπτυξη της πλατφόρμας Cyber Platform Acronis. Το Acronis Cyber Platform είναι νέα σημεία ενοποίησης υπηρεσιών τρίτων με το Acronis Cyber Cloud και το τμήμα agent. Αν και ήμασταν ευχαριστημένοι με τα εσωτερικά μας API που περιγράφονται στο RAML, η ανάγκη δημοσίευσης του API έθεσε ξανά το ερώτημα επιλογής: ποιο πρότυπο σχολιασμού είναι καλύτερο να χρησιμοποιήσουμε για την εργασία μας;
Αρχικά, φαινόταν ότι υπήρχαν δύο λύσεις - οι πιο συνηθισμένες εξελίξεις ήταν το RAML και το Swagger (ή OAS). Αλλά στην πραγματικότητα αποδείχθηκε ότι δεν υπάρχουν τουλάχιστον 2 εναλλακτικές, αλλά 3 ή περισσότερες.
Από τη μία πλευρά υπάρχει η RAML - μια ισχυρή και αποτελεσματική γλώσσα. Εφαρμόζει καλά την ιεραρχία και την κληρονομικότητα, επομένως αυτή η μορφή είναι πιο κατάλληλη για μεγάλες εταιρείες που χρειάζονται πολλές περιγραφές - δηλαδή όχι ένα προϊόν, αλλά πολλές μικροϋπηρεσίες που έχουν κοινά μέρη συμβάσεων - σχήματα ελέγχου ταυτότητας, ίδιοι τύποι δεδομένων, σώματα σφαλμάτων .
Αλλά ο προγραμματιστής του RAML, Mulesoft, έχει ενταχθεί στην κοινοπραξία Open API, η οποία αναπτύσσει . Ως εκ τούτου, η RAML ανέστειλε την ανάπτυξή της. Για να φανταστείτε τη μορφή της εκδήλωσης, φανταστείτε ότι οι συντηρητές των κύριων στοιχείων Linux έφυγαν για να εργαστούν για τη Microsoft. Αυτή η κατάσταση δημιουργεί τις προϋποθέσεις για τη χρήση του Swagger, το οποίο αναπτύσσεται δυναμικά και στην πιο πρόσφατη - τρίτη έκδοση - πρακτικά φτάνει το RAML όσον αφορά την ευελιξία και τη λειτουργικότητα.
Αν όχι για ένα αλλά...
Όπως αποδεικνύεται, δεν έχουν ενημερωθεί όλα τα βοηθητικά προγράμματα ανοιχτού κώδικα στο OAS 3.0. Για τις μικροϋπηρεσίες στο Go, το πιο κρίσιμο πράγμα θα είναι η έλλειψη προσαρμογής για την πιο πρόσφατη έκδοση του προτύπου. Ωστόσο, η διαφορά μεταξύ του Swagger 2 και του Swagger 3 είναι . Για παράδειγμα, στην τρίτη έκδοση οι προγραμματιστές:
- βελτιωμένη περιγραφή των σχημάτων ελέγχου ταυτότητας
- Υποστήριξη σχήματος JSON
- αναβάθμισε τη δυνατότητα προσθήκης παραδειγμάτων
Η κατάσταση είναι αστεία: όταν επιλέγετε ένα πρότυπο, πρέπει να λάβετε υπόψη τα RAML, Swagger 2 και Swagger 3 ως ξεχωριστές εναλλακτικές λύσεις. Ωστόσο, μόνο το Swagger 2 έχει καλή υποστήριξη για εργαλεία OpenSource. Το RAML είναι πολύ ευέλικτο...και πολύπλοκο, και το Swagger 3 υποστηρίζεται ελάχιστα από την κοινότητα, επομένως θα πρέπει να χρησιμοποιήσετε ιδιόκτητα εργαλεία ή εμπορικές λύσεις, που τείνουν να είναι αρκετά ακριβά.
Επιπλέον, αν υπάρχουν πολλά ωραία χαρακτηριστικά στο Swagger, όπως μια έτοιμη πύλη , στο οποίο μπορείτε να ανεβάσετε έναν σχολιασμό και να λάβετε την οπτικοποίηση του με λεπτομερή περιγραφή, συνδέσμους και συνδέσεις, τότε για το πιο θεμελιώδες και λιγότερο φιλικό RAML δεν υπάρχει τέτοια ευκαιρία. Ναι, μπορείτε να αναζητήσετε κάτι μεταξύ έργων στο GitHub, να βρείτε ένα ανάλογο εκεί και να το αναπτύξετε μόνοι σας. Ωστόσο, σε κάθε περίπτωση, κάποιος θα πρέπει να διατηρήσει την πύλη, η οποία δεν είναι τόσο βολική για βασικές ανάγκες χρήσης ή δοκιμών. Επιπλέον, το swagger είναι πιο «χωρίς αρχές» ή πιο φιλελεύθερο - μπορεί να δημιουργηθεί από σχόλια στον κώδικα, το οποίο, φυσικά, έρχεται σε αντίθεση με την πρώτη αρχή του API και δεν υποστηρίζεται από κανένα από τα βοηθητικά προγράμματα RAML.
Κάποτε ξεκινήσαμε να δουλεύουμε με τη RAML ως πιο ευέλικτη γλώσσα, και ως αποτέλεσμα έπρεπε να κάνουμε πολλά πράγματα μόνοι μας. Για παράδειγμα, ένα από τα έργα χρησιμοποιεί το βοηθητικό πρόγραμμα σε δοκιμές μονάδας, που υποστηρίζει μόνο RAML 0.8. Έπρεπε λοιπόν να προσθέσουμε πατερίτσες ώστε το βοηθητικό πρόγραμμα να μπορεί να «φάει» την έκδοση RAML 1.0.
Χρειάζεται να επιλέξετε;
Έχοντας εργαστεί για την ολοκλήρωση του οικοσυστήματος λύσεων για το RAML, καταλήξαμε στο συμπέρασμα ότι πρέπει να μετατρέψουμε το RAML σε Swagger 2 και να πραγματοποιήσουμε όλη την αυτοματοποίηση, την επαλήθευση, τη δοκιμή και την επακόλουθη βελτιστοποίηση σε αυτό. Αυτός είναι ένας καλός τρόπος για να αξιοποιήσετε τόσο την ευελιξία του RAML όσο και την υποστήριξη εργαλείων κοινότητας από το Swagger.
Για την επίλυση αυτού του προβλήματος, υπάρχουν δύο εργαλεία OpenSource που θα πρέπει να παρέχουν μετατροπή συμβολαίου:
- είναι ένα βοηθητικό πρόγραμμα που δεν υποστηρίζεται αυτήν τη στιγμή. Ενώ εργαζόμασταν με αυτό, ανακαλύψαμε ότι έχει μια σειρά προβλημάτων με πολύπλοκα RAML που είναι «απλωμένα» σε μεγάλο αριθμό αρχείων. Αυτό το πρόγραμμα είναι γραμμένο σε JavaScript και εκτελεί μια αναδρομική διέλευση ενός δέντρου σύνταξης. Λόγω της δυναμικής πληκτρολόγησης, γίνεται δύσκολη η κατανόηση αυτού του κώδικα, γι' αυτό αποφασίσαμε να μην χάνουμε χρόνο γράφοντας patches για ένα βοηθητικό πρόγραμμα που ετοιμάζεται.
- - ένα εργαλείο από την ίδια εταιρεία που ισχυρίζεται ότι είναι έτοιμο να μετατρέψει τα πάντα και τα πάντα, και προς οποιαδήποτε κατεύθυνση. Μέχρι σήμερα, έχει ανακοινωθεί υποστήριξη για RAML 0.8, RAML 1.0 και Swagger 2.0. Ωστόσο, τη στιγμή της έρευνάς μας, η χρησιμότητα ήταν ακόμα υγρό και άχρηστο. Οι προγραμματιστές δημιουργούν ένα είδος , επιτρέποντάς τους να προσθέτουν γρήγορα νέα πρότυπα στο μέλλον. Αλλά μέχρι στιγμής απλά δεν λειτουργεί.
Και δεν είναι μόνο αυτές οι δυσκολίες που συναντήσαμε. Ένα από τα βήματα στη διοχέτευσή μας είναι να επαληθεύσουμε ότι το RAML από το αποθετήριο είναι σωστό σε σχέση με τις προδιαγραφές. Δοκιμάσαμε πολλά βοηθητικά προγράμματα. Παραδόξως, όλοι βρίζουν τους σχολιασμούς μας σε διαφορετικά μέρη και με εντελώς διαφορετικά άσχημα λόγια. Και όχι πάντα στην ουσία :).
Στο τέλος, καταλήξαμε σε ένα απαρχαιωμένο πλέον έργο, το οποίο έχει επίσης μια σειρά από προβλήματα (μερικές φορές κολλάει από το μπλε, έχει προβλήματα όταν δουλεύει με κανονικές εκφράσεις). Έτσι, δεν βρήκαμε τρόπο να λύσουμε τα προβλήματα επικύρωσης και μετατροπής με βάση δωρεάν εργαλεία και αποφασίσαμε να χρησιμοποιήσουμε ένα εμπορικό βοηθητικό πρόγραμμα. Στο μέλλον, καθώς τα εργαλεία OpenSource γίνονται πιο ώριμα, αυτό το πρόβλημα μπορεί να γίνει πιο εύκολο να λυθεί. Εν τω μεταξύ, το κόστος εργασίας και χρόνου για το «φινίρισμα» μας φαινόταν πιο σημαντικό από το κόστος μιας εμπορικής υπηρεσίας.
Συμπέρασμα
Μετά από όλα αυτά, θέλαμε να μοιραστούμε την εμπειρία μας και να σημειώσουμε ότι πριν επιλέξετε ένα εργαλείο για την περιγραφή των συμβολαίων, πρέπει να προσδιορίσετε με σαφήνεια τι θέλετε από αυτό και ποιον προϋπολογισμό είστε διατεθειμένοι να επενδύσετε. Αν ξεχάσουμε το OpenSource, υπάρχει ήδη ένας μεγάλος αριθμός υπηρεσιών και προϊόντων που θα σας βοηθήσουν να ελέγξετε, να μετατρέψετε και να επικυρώσετε. Αλλά είναι ακριβά, και μερικές φορές πολύ ακριβά. Για μια μεγάλη εταιρεία, τέτοια κόστη είναι ανεκτά, αλλά για μια startup μπορεί να γίνουν μεγάλο βάρος.
Καθορίστε το σύνολο των εργαλείων που θα χρησιμοποιήσετε αργότερα. Για παράδειγμα, εάν χρειάζεται απλώς να εμφανίσετε ένα συμβόλαιο, θα είναι πιο εύκολο να χρησιμοποιήσετε το Swagger 2, το οποίο έχει ένα όμορφο API, επειδή στο RAML θα πρέπει να δημιουργήσετε και να διατηρήσετε την υπηρεσία μόνοι σας.
Όσο περισσότερες εργασίες έχετε, τόσο μεγαλύτερη θα είναι η ανάγκη για εργαλεία και είναι διαφορετικά για διαφορετικές πλατφόρμες και είναι καλύτερο να εξοικειωθείτε αμέσως με τις διαθέσιμες εκδόσεις για να κάνετε μια επιλογή που ελαχιστοποιεί το κόστος σας στο μέλλον.
Αξίζει όμως να αναγνωρίσουμε ότι όλα τα οικοσυστήματα που υπάρχουν σήμερα είναι ατελή. Επομένως, εάν υπάρχουν θαυμαστές στην εταιρεία που τους αρέσει να εργάζονται στη RAML επειδή "σας επιτρέπει να εκφράζετε τις σκέψεις σας πιο ευέλικτα" ή, αντίθετα, προτιμούν το Swagger επειδή "είναι πιο ξεκάθαρο", είναι καλύτερο να τους αφήσετε να δουλέψουν. σε αυτό που είναι Το έχουν συνηθίσει και το θέλουν, γιατί τα εργαλεία οποιασδήποτε μορφής απαιτούν τροποποίηση με ένα αρχείο.
Όσον αφορά την εμπειρία μας, στις επόμενες αναρτήσεις θα μιλήσουμε για τους στατικούς και δυναμικούς ελέγχους που πραγματοποιούμε με βάση την αρχιτεκτονική RAML-Swagger, καθώς και για το ποια τεκμηρίωση δημιουργούμε από τα συμβόλαια και πώς λειτουργούν όλα.
Μόνο εγγεγραμμένοι χρήστες μπορούν να συμμετάσχουν στην έρευνα. , Σας παρακαλούμε.
Ποια γλώσσα χρησιμοποιείτε για να σχολιάσετε τις συμβάσεις μικροϋπηρεσιών;
-
RAML 0.8
-
RAML 1.0
-
Swagger 2
-
OAS3 (γνωστός και ως)
-
Προσχέδιο
-
Άλλος
-
Μη χρήση
Ψήφισαν 100 χρήστες. 24 χρήστες απείχαν.
Πηγή: www.habr.com