Προγραμματισμός

Προγραμματισμός με Java APIs, Μέρος 1: OpenAPI και Swagger

Ενώ πήρατε τον καφέ σας, η ανάπτυξη εφαρμογών Java άλλαξε--πάλι.

Σε έναν κόσμο που οδηγείται από την ταχεία αλλαγή και την καινοτομία, είναι ειρωνικό ότι τα API επιστρέφουν. Όπως και το αντίστοιχο κωδικοποιητικό σύστημα του μετρό της Νέας Υόρκης στην εποχή των αυτόνομων αυτοκινήτων, τα API είναι παλιά τεχνολογία- βολικό αλλά απαραίτητο. Αυτό που είναι ενδιαφέρον είναι πώς αυτή η αόρατη, καθημερινή αρχιτεκτονική πληροφορικής επανεξετάζεται και χρησιμοποιείται στις τρέχουσες τεχνολογικές τάσεις.

Ενώ τα API είναι παντού, έχουν γίνει ιδιαίτερα εμφανή στην απομακρυσμένη ενσάρκωσή τους ως υπηρεσίες RESTful, οι οποίες αποτελούν τη ραχοκοκαλιά της ανάπτυξης cloud. Οι υπηρεσίες Cloud είναι δημόσια API, τα οποία χαρακτηρίζονται από δημόσια σημεία και δημοσιευμένες δομές. Οι εφαρμογές που βασίζονται σε σύννεφο τείνουν επίσης μικροϋπηρεσίες, οι οποίες είναι ανεξάρτητες αλλά σχετικές αναπτύξεις. Όλοι αυτοί οι παράγοντες αυξάνουν την προβολή των API.

Σε αυτό το σεμινάριο δύο μερών θα μάθετε πώς να τοποθετείτε τα Java API στο επίκεντρο της διαδικασίας σχεδιασμού και ανάπτυξης, από την ιδέα έως την κωδικοποίηση. Το μέρος 1 ξεκινά με μια επισκόπηση και σας παρουσιάζει στο OpenAPI, επίσης γνωστό ως Swagger. Στο Μέρος 2, θα μάθετε πώς να χρησιμοποιείτε τους ορισμούς API της Swagger για να αναπτύξετε μια εφαρμογή Spring Web MVC με μια διεπαφή Angular 2.

Τι είναι το Java API;

Τα API είναι τόσο συνηθισμένα στην ανάπτυξη λογισμικού που μερικές φορές υποτίθεται ότι οι προγραμματιστές απλά γνωρίζουν τι είναι. Αντί να στηριχθούμε στην όσμωση, ας αφιερώσουμε ένα λεπτό για να αποσυμπιέσουμε τι εννοούμε όταν μιλάμε για API.

Σε γενικές γραμμές, μπορούμε να πούμε ότι τα API ορίζουν και διαχειρίζονται τα όρια μεταξύ των συστημάτων.

Πρώτα, API σημαίνει "διεπαφή προγραμματισμού εφαρμογών". Ο ρόλος ενός API είναι να καθορίσει τον τρόπο αλληλεπίδρασης των στοιχείων του λογισμικού. Εάν είστε εξοικειωμένοι με τον αντικειμενοστραφή προγραμματισμό, γνωρίζετε τα API στην ενσάρκωσή τους ως διασυνδέσεις και τάξεις που χρησιμοποιούνται για να αποκτήσετε πρόσβαση σε υποκείμενες δυνατότητες της γλώσσας ή ως δημόσιο πρόσωπο βιβλιοθηκών τρίτων και δυνατοτήτων λειτουργικού συστήματος.

Γενικά, μπορούμε να πούμε ότι τα API ορίζουν και διαχειρίζονται τα όρια μεταξύ συστημάτων, όπως φαίνεται στο Σχήμα 1.

Μάθιου Τάισον

Λοιπόν, που μας αφήνει με ανάπτυξη βάσει API;

Java API για υπολογιστικό νέφος, μικροσυσκευές και REST

Ο προγραμματισμός με API έρχεται στο προσκήνιο με το σύγχρονο API Ιστού: α API εκτεθειμένο σε δίκτυο (NEA), όπου το όριο μεταξύ των συστημάτων είναι "πάνω από το καλώδιο." Αυτά τα όρια βρίσκονται ήδη στο επίκεντρο των εφαρμογών ιστού, τα οποία αποτελούν το κοινό σημείο επαφής μεταξύ των πελατών front-end και των διακομιστών back-end. Η επανάσταση στο cloud έχει αυξήσει εκθετικά τη σημασία των API Java.

Κάθε δραστηριότητα προγραμματισμού που απαιτεί την κατανάλωση υπηρεσιών cloud (που είναι βασικά δημόσια API) και την αποδόμηση συστημάτων σε μικρότερες, ανεξάρτητες αλλά συναφείς αναπτύξεις (επίσης γνωστές ως μικροϋπηρεσίες), βασίζεται σε μεγάλο βαθμό στα API. Τα API που εκτίθενται στο δίκτυο είναι απλώς πιο καθολικά, πιο εύκολα λαμβανόμενα και πιο εύκολα τροποποιημένα και επεκτεινόμενα από τα παραδοσιακά API. Η τρέχουσα αρχιτεκτονική τάση είναι να αξιοποιήσουμε αυτά τα χαρακτηριστικά.

Οι μικροσυσκευές και τα δημόσια API αναπτύσσονται από τις ρίζες της αρχιτεκτονικής προσανατολισμένης στις υπηρεσίες (SOA) και του λογισμικού ως υπηρεσία (SaaS). Αν και το SOA υπήρξε τάση εδώ και πολλά χρόνια, η ευρεία υιοθέτηση παρεμποδίστηκε από την πολυπλοκότητα και τα γενικά έξοδα της SOA. Η βιομηχανία έχει εγκατασταθεί σε RESTful API ως de facto πρότυπο, παρέχοντας αρκετή δομή και σύμβαση με μεγαλύτερη πραγματική ευελιξία. Με το REST ως φόντο, μπορούμε να δημιουργήσουμε επίσημους ορισμούς API που διατηρούν την ανθρώπινη αναγνωσιμότητα. Οι προγραμματιστές δημιουργούν εργαλεία γύρω από αυτούς τους ορισμούς.

Γενικά, το REST είναι μια σύμβαση για τη χαρτογράφηση πόρων σε διαδρομές HTTP και τις σχετικές ενέργειές τους. Πιθανότατα τα έχετε δει ως μεθόδους HTTP GET και POST. Αυτό που είναι το κλειδί είναι να χρησιμοποιήσετε το ίδιο το HTTP ως το τυπικό και να τοποθετήσετε συμβατικές αντιστοιχίσεις πάνω από αυτό για προβλεψιμότητα.

Χρήση Java APIs στο σχεδιασμό

Μπορείτε να δείτε τη σημασία των API, αλλά πώς θα τα χρησιμοποιούσατε προς όφελός σας;

Η χρήση των ορισμών Java API για την προώθηση της διαδικασίας σχεδιασμού και ανάπτυξης είναι ένας αποτελεσματικός τρόπος για να δομήσετε τη σκέψη σας για τα συστήματα πληροφορικής. Χρησιμοποιώντας ορισμούς Java API από την αρχή του κύκλου ζωής ανάπτυξης λογισμικού (συλλογή συλλογών και απαιτήσεων), θα δημιουργήσετε ένα πολύτιμο τεχνικό τεχνούργημα που είναι χρήσιμο μέχρι την ανάπτυξη, καθώς και για συνεχή συντήρηση.

Ας εξετάσουμε πώς οι ορισμοί Java API γεφυρώνουν τα εννοιολογικά και τα στάδια υλοποίησης της ανάπτυξης.

Περιγραφικά έναντι προδιαγραφικών API

Είναι χρήσιμο να γίνει διάκριση μεταξύ περιγραφικών και προδιαγραφικών API. ΕΝΑ περιγραφικό API περιγράφει τον τρόπο λειτουργίας του κώδικα, ενώ a προδιαγραφικό API περιγράφει πώς ο κώδικας πρέπει λειτουργία.

Και τα δύο αυτά στυλ είναι χρήσιμα και και τα δύο βελτιώνονται πολύ χρησιμοποιώντας μια δομημένη, τυπική μορφή για ορισμό API. Κατά κανόνα, η χρήση του API για την προώθηση της δημιουργίας κώδικα είναι μια προδιαγραφική χρήση, ενώ η χρήση του κώδικα για την έξοδο του ορισμού Java API είναι μια περιγραφική χρήση.

Συγκέντρωση απαιτήσεων με Java API

Όσον αφορά το φάσμα εννοιολογικής εφαρμογής, η συλλογή απαιτήσεων έχει περάσει από την πλευρά της έννοιας. Αλλά ακόμη και στο εννοιολογικό στάδιο της εφαρμογής dev, μπορούμε να αρχίσουμε να σκεφτόμαστε ως προς τα API.

Ας πούμε ότι ο σχεδιασμός του συστήματός σας ασχολείται με ποδήλατα βουνού - κατασκευή, ανταλλακτικά κ.ο.κ. Ως αντικειμενοστραφής προγραμματιστής, θα ξεκινήσετε μιλώντας με τους ενδιαφερόμενους σχετικά με τις απαιτήσεις. Αρκετά γρήγορα μετά από αυτό, θα σκεφτόσασταν μια περίληψη BikePart τάξη.

Στη συνέχεια, θα σκεφτόσασταν μέσω της διαδικτυακής εφαρμογής που θα διαχειριζόταν τα διάφορα αντικείμενα ανταλλακτικών ποδηλάτων. Σύντομα, θα φτάσετε σε κοινές απαιτήσεις για τη διαχείριση αυτών των ανταλλακτικών ποδηλάτου. Ακολουθεί ένα στιγμιότυπο του φάση απαιτήσεων τεκμηρίωσης για μια εφαρμογή ανταλλακτικών ποδηλάτων:

  • Η εφαρμογή πρέπει να μπορεί να δημιουργήσει έναν τύπο εξαρτήματος ποδηλάτου (αλλαγή ταχυτήτων, φρένο κ.λπ.).
  • Ένας εξουσιοδοτημένος χρήστης πρέπει να είναι σε θέση να παραθέτει, να δημιουργεί και να ενεργοποιεί έναν τύπο εξαρτήματος.
  • Ένας μη εξουσιοδοτημένος χρήστης πρέπει να μπορεί να παραθέτει ενεργούς τύπους ανταλλακτικών και να προβάλλει λίστες μεμονωμένων περιπτώσεων τύπων ανταλλακτικών στο σύστημα.

Ήδη μπορείτε να δείτε τα περιγράμματα των υπηρεσιών να διαμορφώνονται. Έχοντας κατά νου τα τελικά API, μπορείτε να αρχίσετε να σχεδιάζετε αυτές τις υπηρεσίες. Για παράδειγμα, εδώ είναι μια μερική λίστα των υπηρεσιών RESTful CRUD για τύπους ανταλλακτικών ποδηλάτων:

  • Δημιουργία τύπου ανταλλακτικού ποδηλάτου: PUT / ανταλλακτικός τύπος /
  • Ενημέρωση τύπου ανταλλακτικού ποδηλάτου: POST / μέρος-είδος /
  • Λίστα μερών τύπων: GET / μέρος-μέρος /
  • Λάβετε λεπτομέρειες τύπου ανταλλακτικού: GET / part-type /: id

Παρατηρήστε πώς οι υπηρεσίες CRUD αρχίζουν να υπονοούν τη μορφή διαφόρων ορίων υπηρεσιών. Αν δημιουργείτε στυλ μικροϋπηρεσιών, μπορείτε ήδη να δείτε τρεις μικροσυσκευές να αναδύονται από τη σχεδίαση:

  • Υπηρεσία ανταλλακτικών ποδηλάτων
  • Υπηρεσία ανταλλακτικών τύπου ποδηλάτου
  • Υπηρεσία ελέγχου ταυτότητας / εξουσιοδότησης

Επειδή πιστεύω ότι τα API είναι όρια των σχετικών οντοτήτωνΘεωρώ ότι είναι οι μικρο-υπηρεσίες από αυτήν τη λίστα API επιφάνειες. Μαζί, προσφέρουν μια μεγάλη εικόνα της αρχιτεκτονικής της εφαρμογής. Λεπτομέρειες για τις ίδιες τις υπηρεσίες περιγράφονται επίσης με τρόπο που θα χρησιμοποιήσετε για την τεχνική προδιαγραφή, η οποία είναι η επόμενη φάση του κύκλου ζωής ανάπτυξης λογισμικού.

Τεχνική προδιαγραφή με Java API

Εάν έχετε συμπεριλάβει την εστίαση API ως μέρος της συλλογής απαιτήσεων, τότε έχετε ήδη ένα καλό πλαίσιο για τεχνικές προδιαγραφές. Το επόμενο στάδιο είναι η επιλογή της στοίβας τεχνολογίας που θα χρησιμοποιήσετε για την εφαρμογή των προδιαγραφών.

Με τόσο μεγάλη έμφαση στη δημιουργία RESTful API, οι προγραμματιστές έχουν μια αμηχανία πλούτου όταν πρόκειται για εφαρμογή. Ανεξάρτητα από τη στοίβα που θα επιλέξετε, το να συμπληρώσετε το API ακόμη περισσότερο σε αυτό το στάδιο θα αυξήσει την κατανόησή σας σχετικά με τις αρχιτεκτονικές ανάγκες της εφαρμογής. Στις επιλογές μπορεί να περιλαμβάνεται ένα VM (εικονική μηχανή) για τη φιλοξενία της εφαρμογής, μια βάση δεδομένων ικανή να διαχειρίζεται τον όγκο και τον τύπο δεδομένων που εξυπηρετείτε και μια πλατφόρμα cloud στην περίπτωση ανάπτυξης IaaS ή PaaS.

Μπορείτε να χρησιμοποιήσετε το API για να οδηγήσετε "προς τα κάτω" προς σχήματα (ή δομές εγγράφων n NoSQL) ή "προς τα πάνω" προς στοιχεία διεπαφής χρήστη. Καθώς αναπτύσσετε τις προδιαγραφές API, πιθανότατα θα παρατηρήσετε μια αλληλεπίδραση μεταξύ αυτών των ανησυχιών. Όλα αυτά είναι καλά και μέρος της διαδικασίας. Το API γίνεται ένα κεντρικό, ζωντανό μέρος για την καταγραφή αυτών των αλλαγών.

Μια άλλη ανησυχία που πρέπει να θυμάστε είναι ποια δημόσια API θα εκθέσει το σύστημά σας. Δώστε επιπλέον σκέψη και φροντίδα σε αυτά. Μαζί με την υποστήριξη στην προσπάθεια ανάπτυξης, τα δημόσια API χρησιμεύουν ως το δημοσιευμένο συμβόλαιο που χρησιμοποιούν εξωτερικά συστήματα για διασύνδεση με το δικό σας.

Δημόσια API cloud

Σε γενικές γραμμές, τα API ορίζουν τη σύμβαση ενός συστήματος λογισμικού, παρέχοντας μια γνωστή και σταθερή διεπαφή με την οποία προγραμματίζονται άλλα συστήματα. Συγκεκριμένα, ένα δημόσιο API cloud είναι μια δημόσια σύμβαση με άλλους οργανισμούς και συστήματα δημιουργίας προγραμματιστών. Παραδείγματα είναι τα API GitHub και Facebook.

Τεκμηρίωση του Java API

Σε αυτό το στάδιο, θα θελήσετε να αρχίσετε να καταγράφετε τα API σας σε επίσημη σύνταξη. Έχω αναφέρει μερικά εξέχοντα πρότυπα API στον Πίνακα 1.

Σύγκριση μορφών API

 
ΟνομαΠερίληψηΑστέρια στο GitHubΔιεύθυνση URL
OpenAPIΤο JSON και το YML υποστηριζόμενο πρότυπο API προέρχονται από το έργο Swagger, περιλαμβάνει ποικιλία εργαλείων στο οικοσύστημα Swagger.~6,500//github.com/OAI/OpenAPI-Προδιαγραφή
RAMLΠροδιαγραφές με βάση το YML που υποστηρίζονται κυρίως από το MuleSoft~3,000//github.com/raml-org/raml-spec
API BluePrintΓλώσσα σχεδιασμού API χρησιμοποιώντας σύνταξη τύπου MarkDown~5,500//github.com/apiaryio/api-blueprint/

Σχεδόν κάθε μορφή που επιλέγετε για την τεκμηρίωση του API σας θα πρέπει να είναι εντάξει. Απλώς αναζητήστε μια μορφή που είναι δομημένη, έχει μια τυπική προδιαγραφή και καλά εργαλεία γύρω της, και φαίνεται ότι θα διατηρηθεί ενεργά μακροπρόθεσμα. Τόσο το RAML όσο και το OpenAPI ταιριάζουν σε αυτόν τον λογαριασμό. Ένα άλλο τακτοποιημένο έργο είναι το API Blueprint, το οποίο χρησιμοποιεί σύνταξη markdown. Για παραδείγματα σε αυτό το άρθρο θα χρησιμοποιήσουμε το OpenAPI και το Swagger.

OpenAPI και Swagger

Το OpenAPI είναι μια μορφή JSON για την περιγραφή API που βασίζονται σε REST. Το Swagger ξεκίνησε ως OpenAPI, αλλά έχει εξελιχθεί σε ένα σύνολο εργαλείων γύρω από τη μορφή OpenAPI. Οι δύο τεχνολογίες αλληλοσυμπληρώνονται καλά.

Παρουσιάζουμε το OpenAPI

Το OpenAPI είναι προς το παρόν η πιο κοινή επιλογή για τη δημιουργία ορισμών RESTful. Μια συναρπαστική εναλλακτική λύση είναι το RAML (RESTful API Markup Language), το οποίο βασίζεται στο YAML. Προσωπικά, έχω βρει τα εργαλεία στο Swagger (ειδικά στον οπτικό σχεδιαστή) πιο στιλβωμένα και χωρίς λάθη από ό, τι στο RAML.

Το OpenAPI χρησιμοποιεί τη σύνταξη JSON, η οποία είναι γνωστή στους περισσότερους προγραμματιστές. Εάν προτιμάτε να μην τεντώσετε τα μάτια σας, αναλύοντας το JSON, υπάρχουν UI που διευκολύνουν την εργασία με αυτό. Το Μέρος 2 εισάγει UI για RESTful ορισμούς.

Η λίστα 1 είναι ένα δείγμα της σύνταξης JSON του OpenAPI.

Λίστα 1. Ορισμός OpenAPI για ένα απλό BikePart

 "paths": {"/ part-type": {"get": {"description": "Παρέχει όλους τους τύπους ανταλλακτικών στο σύστημα", "operationId": "getPartTypes", "menghasilkan": ["εφαρμογή / json "]," απαντήσεις ": {" 200 ": {" περιγραφή ":" Παίρνει τα BikeParts "," σχήματα ": {" type ":" array "," item ": {" $ ref ":" # / ορισμοί / BikePart "}}}}}}} 

Αυτός ο ορισμός είναι τόσο συνοπτικός, είναι ουσιαστικά Σπαρτιάτης, κάτι που είναι καλό για τώρα. Υπάρχει αρκετός χώρος για να αυξηθεί η λεπτομέρεια και η πολυπλοκότητα του ορισμού API. Θα σας δείξω μια πιο λεπτομερή επανάληψη αυτού του ορισμού σύντομα.

Κωδικοποίηση από το Java API

Η συλλογή απαιτήσεων έχει ολοκληρωθεί και η βασική εφαρμογή έχει οριστεί, πράγμα που σημαίνει ότι είστε έτοιμοι για το διασκεδαστικό μέρος --- κωδικοποίηση! Έχοντας έναν επίσημο ορισμό Java API σας δίνει ορισμένα ξεχωριστά πλεονεκτήματα. Καταρχήν, γνωρίζετε ποια τελικά σημεία πρέπει να δημιουργήσουν και να κωδικοποιήσουν οι προγραμματιστές back-end και front-end, αντίστοιχα. Ακόμα κι αν είστε μια ομάδα, θα δείτε γρήγορα την αξία μιας προσέγγισης που βασίζεται σε API όταν ξεκινάτε την κωδικοποίηση.

Καθώς αναπτύσσετε την εφαρμογή, θα δείτε επίσης την αξία της χρήσης API για να αποτυπώσετε τις διαπραγματεύσεις μεταξύ της ανάπτυξης και της επιχείρησης. Η χρήση εργαλείων API θα επιταχύνει τόσο την εφαρμογή όσο και την τεκμηρίωση των αλλαγών κώδικα.

Οι πιο λεπτομερείς προδιαγραφές και η πραγματική κωδικοποίηση ενδέχεται να απαιτούν μεγαλύτερη λεπτομέρεια από τον πιο σύντομο ορισμό στην Λίστα 1. Επιπλέον, μεγαλύτερα και πιο περίπλοκα συστήματα θα μπορούσαν να αξίζουν δυνατότητες που θα κλιμακώνονται, όπως οι αναφορές εγγράφων. Η λίστα 2 δείχνει ένα πιο ολοκληρωμένο παράδειγμα του BikePart API.

Λίστα 2. Προσθήκη λεπτομερειών στον ορισμό API BikePart

 "paths": {"/ part-type": {"get": {"description": "Παίρνει όλους τους τύπους ανταλλακτικών διαθέσιμο στο σύστημα", "operationId": "getPartTypes", "menghasilkan": ["εφαρμογή / json "]," παράμετροι ": [{" name ":" limit "," in ":" query "," description ":" μέγιστος αριθμός αποτελεσμάτων προς επιστροφή "," απαιτείται ": false," type ": "integer", "format": "int32"}], "αποκρίσεις": {"200": {"description": "part-type listing", "schema": {"type": "array", "item ": {" $ ref ":" # / definitions / PartType "}}}," default ": {" description ":" απροσδόκητο σφάλμα "," schema ": {" $ ref ":" # / definitions / Error " }}}}