Ohjelmointi

Ohjelmointi Java-sovellusliittymillä, osa 1: OpenAPI ja Swagger

Kun sait kahvia, Java-sovelluskehitys muuttui -uudelleen.

Nopean muutoksen ja innovaatioiden ohjaamassa maailmassa on ironista, että sovellusliittymät palaavat. Kuten New Yorkin metrojärjestelmän koodausekvivalentti autonomisten autojen aikakaudella, API: t ovat vanha tekniikka--terve, mutta välttämätön. Mielenkiintoista on, kuinka tätä näkymätöntä, jokapäiväistä IT-arkkitehtuuria suunnitellaan uudelleen ja käytetään nykyisissä tekniikan trendeissä.

Vaikka sovellusliittymät ovat kaikkialla, niistä on tullut erityisen näkyvä etäkehityksessään RESTful-palveluina, jotka ovat pilvipalvelujen selkäranka. Pilvipalvelut ovat julkiset sovellusliittymät, joille on ominaista julkisesti näkyvät päätepisteet ja julkaistut rakenteet. Pilvipohjaiset sovellukset suuntaavat myös kohti mikropalvelut, jotka ovat itsenäisiä mutta niihin liittyviä käyttöönottoja. Kaikki nämä tekijät lisäävät sovellusliittymien näkyvyyttä.

Tässä kaksiosaisessa opetusohjelmassa opit asettamaan Java-sovellusliittymät suunnittelu- ja kehitysprosessin ytimeen konseptista koodaukseen. Osa 1 alkaa yleiskatsauksella ja esittelee OpenAPI: n, joka tunnetaan myös nimellä Swagger. Osassa 2 opit käyttämään Swaggerin sovellusliittymämääritelmiä kehittämään Spring Web MVC -sovelluksen Angular 2 -käyttöliittymällä.

Mikä on Java-sovellusliittymä?

Sovellusliittymät ovat niin yleisiä ohjelmistokehityksessä, että joskus oletetaan, että ohjelmoijat yksinkertaisesti tietävät mitä he ovat. Sen sijaan, että luotamme osmoosiin, otetaan minuutti aikaa purkamaan mitä tarkoitamme puhuessamme API: sta.

Yleensä voimme sanoa, että API: t asettavat ja hallitsevat rajoja järjestelmien välillä.

Ensimmäinen, API tarkoittaa "sovelluksen ohjelmointirajapintaa". API: n tehtävänä on määrittää, miten ohjelmistokomponentit ovat vuorovaikutuksessa. Jos olet perehtynyt olio-ohjelmointiin, tunnet API: t niiden inkarnaatiossa käyttöliittyminä ja luokkina, joita käytetään pääsyn kielen perusominaisuuksiin, tai kolmansien osapuolten kirjastojen ja käyttöjärjestelmän ominaisuuksien julkisena kasvona.

Yleensä voimme sanoa, että API: t asettavat ja hallitsevat rajoja järjestelmien välillä, kuten kuvassa 1 näkyy.

Matthew Tyson

Joten mihin se jättää meille API-ohjattavan kehityksen?

Java-sovellusliittymät pilvipalveluja, mikropalveluja ja REST-palvelua varten

Ohjelmointi API: illa tulee esiin modernin web-API: n avulla: a verkkoaltistuva API (NEA), jossa järjestelmien välinen raja on "langan yli". Nämä rajat ovat jo keskeisiä verkkosovelluksissa, jotka ovat yhteinen yhteyspiste käyttöliittymän asiakkaiden ja taustapalvelimien välillä. Pilvirevoluutio on eksponentiaalisesti lisännyt Java-sovellusliittymien merkitystä.

Kaikki ohjelmointitoiminnot, jotka edellyttävät pilvipalvelujen (jotka ovat pohjimmiltaan julkisia sovellusliittymiä) kuluttamista ja järjestelmien purkamista pienemmiksi, itsenäisiksi mutta niihin liittyviksi käyttöönotoksiksi (tunnetaan myös nimellä mikropalvelut), riippuu vahvasti API: sta. Verkolle altistuvat sovellusliittymät ovat yksinkertaisesti yleisempiä, helpommin hankittavia ja helpommin muokattavia ja laajennettuja kuin perinteiset sovellusliittymät. Nykyinen arkkitehtoninen suuntaus on hyödyntää näitä ominaisuuksia.

Mikropalvelut ja julkiset sovellusliittymät ovat kasvaneet palvelukeskeisen arkkitehtuurin (SOA) ja ohjelmisto palveluna (SaaS) juurista. Vaikka SOA on ollut trendi monien vuosien ajan, laajaa käyttöönottoa on haitannut SOA: n monimutkaisuus ja yleiskustannukset. Teollisuus on asettunut RESTful-sovellusliittymiin tosiasiallisena standardina, joka tarjoaa juuri tarpeeksi rakennetta ja käytäntöjä enemmän reaalimaailman joustavuutta. Kun taustana on REST, voimme luoda muodolliset API-määritelmät, jotka säilyttävät ihmisten luettavuuden. Kehittäjät luovat työkaluja näiden määritelmien ympärille.

Yleensä REST on käytäntö resurssien kartoittamiseksi HTTP-polkuihin ja niihin liittyviin toimintoihin. Olet todennäköisesti nähnyt nämä HTTP GET- ja POST-menetelminä. Tärkeintä on käyttää itse HTTP: tä vakiona ja kerrata sen päälle tavanomaiset kartoitukset ennustettavuutta varten.

Java-sovellusliittymien käyttö suunnittelussa

Voit nähdä sovellusliittymien tärkeyden, mutta miten käyttäisit niitä hyödyksi?

Java API -määritysten käyttäminen suunnittelu- ja kehitysprosessin ohjaamiseksi on tehokas tapa jäsentää ajatteluasi IT-järjestelmistä. Käyttämällä Java-sovellusliittymämääritelmiä ohjelmistokehityksen elinkaaren alusta alkaen (konseptin ja vaatimusten kerääminen) luot arvokkaan teknisen artefaktin, joka on hyödyllinen käyttöönottoon saakka ja jatkuvaan ylläpitoon.

Tarkastellaan, miten Java-sovellusliittymämääritykset yhdistävät kehityksen käsitteelliset ja toteutusvaiheet.

Kuvaavat vs. määrittävät sovellusliittymät

On hyödyllistä tehdä ero kuvailevien ja määrättävien sovellusliittymien välillä. A kuvaava API kuvaa tapaa, jolla koodi todella toimii, kun taas a ohjeellinen API kuvaa kuinka koodi pitäisi toiminto.

Molemmat tyylit ovat hyödyllisiä, ja molempia parannetaan huomattavasti käyttämällä jäsenneltyä, vakiomuotoa API-määritykseen. Nyrkkisääntönä on, että sovellusliittymän käyttäminen koodin luomiseen on ohjeellinen käyttö, kun taas koodin käyttäminen Java-sovellusliittymän määrityksen tuottamiseen on kuvaava käyttö.

Vaatimusten kerääminen Java-sovellusliittymien kanssa

Käsitteellisestä toteutukseen -vaatimusten osalta vaatimusten kerääminen on aivan käsitteellistä. Mutta jopa sovelluskehityksen käsitteellisessä vaiheessa voimme alkaa ajatella API: ta.

Oletetaan, että suunnittelussa oleva järjestelmäsi käsittelee maastopyöriä - rakentamista, osia ja niin edelleen. Objektisuuntautuneena kehittäjänä aloitat keskustelemalla sidosryhmien kanssa vaatimuksista. Melko nopeasti sen jälkeen ajattelet abstraktia BikePart luokassa.

Seuraavaksi ajattelisit verkkosovelluksen kautta, joka hallitsisi erilaisia ​​pyöräosien esineitä. Pian saavutat yhteiset vaatimukset näiden pyöräosien hallitsemiseksi. Tässä on tilannekuva vaatimusten vaihe dokumentaatio polkupyörän osien sovelluksesta:

  • Sovelluksen on kyettävä luomaan tietyntyyppinen pyöräosa (vaihdevipu, jarru jne.).
  • Valtuutetun käyttäjän on kyettävä luetteloimaan, luomaan ja aktivoimaan osan tyyppi.
  • Luvattoman käyttäjän on pystyttävä luetteloimaan aktiiviset osatyypit ja tarkastelemaan luetteloita yksittäisistä osan tyyppisistä ilmentymistä järjestelmässä.

Jo nyt voit nähdä palvelujen ääriviivat muotoutuvan. Kun otetaan huomioon mahdolliset sovellusliittymät, voit aloittaa näiden palveluiden luonnostelun. Esimerkiksi tässä on osittainen luettelo RESTful CRUD -palveluista pyöräosien tyypeille:

  • Luo pyörän osan tyyppi: PUT / osa-tyyppi /
  • Päivitä pyörän osan tyyppi: POST / osa-tyyppi /
  • Luettele osan tyypit: GET / part-type /
  • Hanki osan tyyppi: GET / part-type /: id

Huomaa, kuinka CRUD-palvelut alkavat vihjata erilaisten palvelurajojen muodosta. Jos rakennat mikropalvelutyyliä, näet jo kolme mikropalvelua, jotka tulevat esiin suunnittelusta:

  • Pyöräosapalvelu
  • Pyörän osa-tyyppinen palvelu
  • Todennus- / valtuutuspalvelu

Koska ajattelen API: ita sidosryhmien rajat, Pidän tämän luettelon mikropalveluja API-pinnat. Yhdessä ne tarjoavat kokonaiskuvan sovellusarkkitehtuurista. Palvelujen yksityiskohdat kuvataan myös tavalla, jota käytät teknisissä eritelmissä, jotka ovat ohjelmistokehityksen elinkaaren seuraava vaihe.

Tekniset tiedot Java-sovellusliittymillä

Jos olet sisällyttänyt API-painopisteen vaatimusten keräämiseen, sinulla on jo hyvät puitteet teknisille määrittelyille. Seuraava vaihe on valita tekniikkapino, jota käytetään määrityksen toteuttamiseen.

Kehittäjät keskittyvät niin paljon RESTful-sovellusliittymien rakentamiseen, että niiden toteutuminen on hämmentävää. Valitsemastasi pinosta riippumatta API: n täsmentäminen tässä vaiheessa lisää ymmärrystäsi sovelluksen arkkitehtonisista tarpeista. Vaihtoehdot voivat sisältää virtuaalikoneen (virtuaalikone) sovelluksen isännöimiseksi, tietokannan, joka pystyy hallitsemaan palvelemiesi tietojen määrää ja tyyppiä, sekä pilvialustan IaaS- tai PaaS-käyttöönoton yhteydessä.

Voit käyttää sovellusliittymää ajaaksesi "alaspäin" kohti skeemejä (tai dokumenttirakenteita n NoSQL) tai "ylöspäin" kohti käyttöliittymän elementtejä. Kun kehität API-määrittelyä, huomaat todennäköisesti näiden ongelmien välisen vuorovaikutuksen. Tämä on kaikki hyvää ja osa prosessia. API: sta tulee keskeinen asuinpaikka näiden muutosten kaappaamiseksi.

Toinen mielessä oleva huolenaihe on se, mitkä julkiset sovellusliittymät järjestelmäsi paljastaa. Anna ylimääräistä miettiä ja huolta näistä. Kehitystyön avustamisen ohella julkiset sovellusliittymät toimivat julkaistuina sopimuksina, joita ulkoiset järjestelmät käyttävät sinun kanssasi.

Julkiset pilvi-sovellusliittymät

Yleensä API: t määrittelevät ohjelmistojärjestelmän sopimuksen, joka tarjoaa tunnetun ja vakaan käyttöliittymän muiden järjestelmien ohjelmointiin. Erityisesti julkinen pilvi-sovellusliittymä on julkinen sopimus muiden järjestelmiä rakentavien organisaatioiden ja ohjelmoijien kanssa. Esimerkkejä ovat GitHub ja Facebook -sovellusliittymät.

Java-sovellusliittymän dokumentointi

Tässä vaiheessa haluat aloittaa sovellusliittymiesi sieppaamisen muodollisessa syntaksissa. Olen luetellut muutamia merkittäviä API-standardeja taulukossa 1.

API-muotojen vertailu

 
NimiYhteenvetoTähdet GitHubissaURL
OpenAPISwagger-projektista syntynyt JSON- ja YML-tuettu API-standardi sisältää useita työkaluja Swagger-ekosysteemiin.~6,500//github.com/OAI/OpenAPI-Specification
RAMLYML-pohjainen tekninen tuki, jota pääasiassa tukee MuleSoft~3,000//github.com/raml-org/raml-spec
API BluePrintAPI-suunnittelukieli, joka käyttää MarkDownin kaltaista syntaksia~5,500//github.com/apiaryio/api-blueprint/

Lähes minkä tahansa muodon, jonka valitset sovellusliittymän dokumentoimiseksi, pitäisi olla kunnossa. Etsi vain muoto, joka on jäsennelty, siinä on muodollinen tekninen muoto ja hyvät työkalut, ja näyttää siltä, ​​että sitä ylläpidetään aktiivisesti pitkällä aikavälillä. Sekä RAML että OpenAPI sopivat tähän laskuun. Toinen siisti projekti on API Blueprint, joka käyttää markdown-syntaksia. Esimerkkejä tässä artikkelissa aiomme käyttää OpenAPI: tä ja Swaggeria.

OpenAPI ja Swagger

OpenAPI on JSON-muoto REST-pohjaisten sovellusliittymien kuvaamiseen. Swagger aloitti nimellä OpenAPI, mutta on kehittynyt joukoksi työkaluja OpenAPI-muodon ympärillä. Nämä kaksi tekniikkaa täydentävät toisiaan hyvin.

Esittelyssä OpenAPI

OpenAPI on tällä hetkellä yleisin valinta RESTful-määritelmien luomiseen. Pakottava vaihtoehto on RAML (RESTful API Markup Language), joka perustuu YAML: ään. Henkilökohtaisesti olen löytänyt Swaggerin (erityisesti visuaalisen suunnittelijan) työkalut kiillotetusta ja virheettömästä kuin RAML: ssä.

OpenAPI käyttää JSON-syntaksia, joka on tuttu useimmille kehittäjille. Jos et halua rasittaa silmiäsi jäsentämällä JSONia, käyttöliittymät helpottavat työskentelyäsi. Osa 2 esittelee käyttöliittymät RESTful-määritelmille.

Listaus 1 on esimerkki OpenAPI: n JSON-syntaksista.

Luettelo 1. OpenAPI-määritelmä yksinkertaiselle BikePart-osalle

 "polut": {"/ part-type": {"get": {"description": "Noutaa kaikki järjestelmässä käytettävissä olevat osatyypit", "operationId": "getPartTypes", "tuottaa": ["sovellus / json "]," responses ": {" 200 ": {" description ":" Gets the BikeParts "," schema ": {" type ":" array "," items ": {" $ ref ":" # / definitions / BikePart "}}}}}}} 

Tämä määritelmä on niin ytimekäs, että se on käytännössä Spartan, mikä on hieno toistaiseksi. API-määritelmän yksityiskohtien ja monimutkaisuuden lisäämiseksi on paljon tilaa. Näytän sinulle tarkemman iteraation tästä määritelmästä pian.

Koodaus Java-sovellusliittymästä

Vaatimusten kerääminen on suoritettu ja perussovellus on määritelty, mikä tarkoittaa, että olet valmis hauska osa --- koodaus! Muodollisen Java-sovellusliittymämääritelmän saaminen antaa sinulle eräitä etuja. Ensinnäkin tiedät mitä loppupisteitä back-end- ja front-end-kehittäjien on luotava ja koodattava vastaavasti. Vaikka olisitkin yhden tiimi, näet nopeasti API: n perustuvan lähestymistavan arvon, kun aloitat koodauksen.

Kun rakennat sovellusta, näet myös API: n käytön arvon kehityksen ja liiketoiminnan edestakaisin neuvottelujen sieppaamiseksi. API-työkalujen käyttö nopeuttaa sekä koodimuutosten soveltamista että dokumentointia.

Yksityiskohtaisemmat tiedot ja varsinainen koodaus saattavat vaatia yksityiskohtaisempia tietoja kuin luettelon 1 täsmällinen määritelmä. Lisäksi suuremmat ja monimutkaisemmat järjestelmät voisivat ansaita skaalautuvia ominaisuuksia, kuten asiakirjaviitteet. Luettelossa 2 on tarkempi esimerkki BikePart-sovellusliittymästä.

Listaus 2. Lisätään yksityiskohtia BikePart API -määritykseen

 "polut": {"/ part-type": {"get": {"description": "Noutaa kaikki järjestelmässä käytettävissä olevat osatyypit", "operationId": "getPartTypes", "tuottaa": ["sovellus / json "]," parametrit ": [{" nimi ":" rajoitus "," sisään ":" kysely "," kuvaus ":" palautettavien tulosten enimmäismäärä "," vaadittu ": epätosi," tyyppi ": "kokonaisluku", "format": "int32"}], "vastaukset": {"200": {"description": "part-type list", "schema": {"type": "array", "items ": {" $ ref ":" # / definitions / PartType "}}}," default ": {" description ":" odottamaton virhe "," schema ": {" $ ref ":" # / definitions / Error " }}}}