🥇కాబట్టి అది RAML లేదా OAS (స్వాగర్)?

మైక్రోసర్వీస్‌ల యొక్క డైనమిక్ ప్రపంచంలో, ఏదైనా మారవచ్చు - విభిన్న ఫ్రేమ్‌వర్క్‌లు మరియు నిర్మాణాన్ని ఉపయోగించి ఏదైనా భాగాన్ని వేరే భాషలో తిరిగి వ్రాయవచ్చు. కాంట్రాక్టులు మాత్రమే మారకుండా ఉండాలి, తద్వారా మైక్రోసర్వీస్ అంతర్గత రూపాంతరాలతో సంబంధం లేకుండా కొంత శాశ్వత ప్రాతిపదికన బయటి నుండి సంకర్షణ చెందుతుంది. మరియు ఈ రోజు మనం ఒప్పందాలను వివరించడానికి మరియు మేము కనుగొన్న కళాఖండాలను పంచుకోవడానికి ఒక ఆకృతిని ఎంచుకోవడంలో మా సమస్య గురించి మాట్లాడుతాము.

పోస్ట్ తయారు చేయబడింది అన్నా మెలేఖోవా и వ్లాదిమిర్ లాపటిన్

మైక్రోసర్వీసెస్. అక్రోనిస్ సైబర్ క్లౌడ్‌ను అభివృద్ధి చేస్తున్నప్పుడు, మేము వాటిని తప్పించుకోలేమని గ్రహించాము. మరియు మైక్రోసర్వీస్ యొక్క ఇంటర్‌ఫేస్‌ను సూచించే ఒప్పందాన్ని అధికారికం చేయకుండా మైక్రోసర్వీస్ రూపకల్పన చేయడం అసాధ్యం.

కానీ ఒక ఉత్పత్తి ఒకటి కంటే ఎక్కువ భాగాలను కలిగి ఉన్నప్పుడు మరియు కాంట్రాక్ట్ డెవలప్‌మెంట్ ఒక సాధారణ కార్యకలాపంగా మారినప్పుడు, మీరు ప్రాసెస్ ఆప్టిమైజేషన్ గురించి ఆలోచించకుండా ఉండలేరు. ఇంటర్‌ఫేస్ (కాంట్రాక్టు) మరియు ఇంప్లిమెంటేషన్ (మైక్రోసర్వీస్) ఒకదానికొకటి సరిపోలాలి, వేర్వేరు భాగాలు ఒకే విధంగా ఒకే విధంగా చేయాలి మరియు ఈ నిర్ణయాలన్నింటికీ కేంద్రీకృత నిర్ణయం తీసుకోకుండా, ప్రతి బృందం బలవంతం చేయబడుతుందని స్పష్టమవుతుంది. వాటిని పొందడానికి మళ్లీ మళ్లీ సమయాన్ని వెచ్చించండి.

నుండి Amazon microservices రేఖాచిత్రం ట్వీట్ వెర్నర్ వోగెలిస్, CTO అమెజాన్
డైలమా ఏమిటి? వాస్తవంగా, మైక్రోసర్వీస్‌లను ఇంటరాక్ట్ చేయడానికి రెండు మార్గాలు ఉన్నాయి - Google నుండి HTTP రెస్ట్ మరియు gRPC. Google సాంకేతికత స్టాక్‌లో చిక్కుకోవడం ఇష్టంలేక, మేము HTTP రెస్ట్‌ని ఎంచుకున్నాము. HTTP REST కాంట్రాక్ట్ ఉల్లేఖనాలు చాలా తరచుగా రెండు ఫార్మాట్‌లలో ఒకదానిలో వివరించబడ్డాయి: RAML మరియు OAS, గతంలో స్వాగర్ అని పిలుస్తారు. అందువల్ల, ప్రతి అభివృద్ధి బృందం ప్రమాణాలలో ఒకదాన్ని ఎంచుకోవాల్సిన అవసరాన్ని ఎదుర్కొంటుంది. కానీ అది మారుతుంది, ఈ ఎంపిక చేయడం చాలా కష్టం.

ఉల్లేఖనాలు ఎందుకు అవసరం?

ఉల్లేఖనం అవసరం కాబట్టి బాహ్య వినియోగదారు దాని HTTP ఇంటర్‌ఫేస్ ద్వారా మీ సేవతో ఏమి చేయవచ్చో సులభంగా గుర్తించగలరు. అంటే, ప్రాథమిక స్థాయిలో, ఉల్లేఖనం తప్పనిసరిగా అందుబాటులో ఉన్న వనరుల జాబితా, వాటి HTTP పద్ధతులు, అభ్యర్థన సంస్థలు, పారామితుల జాబితా, అవసరమైన మరియు మద్దతు ఉన్న హెడర్‌ల సూచన, అలాగే రిటర్న్ కోడ్‌లు మరియు ప్రతిస్పందన ఫార్మాట్‌లను కలిగి ఉండాలి. కాంట్రాక్ట్ ఉల్లేఖనం యొక్క అత్యంత ముఖ్యమైన అంశం వారి మౌఖిక వివరణ (“మీరు ఈ ప్రశ్న పరామితిని అభ్యర్థనకు జోడిస్తే ఏమి జరుగుతుంది?”, “ఏ సందర్భంలో కోడ్ 400 తిరిగి వస్తుంది?”)

అయినప్పటికీ, పెద్ద సంఖ్యలో మైక్రోసర్వీస్‌లను అభివృద్ధి చేయడానికి వచ్చినప్పుడు, మీరు వ్రాసిన ఉల్లేఖనాల నుండి అదనపు విలువను సంగ్రహించాలనుకుంటున్నారు. ఉదాహరణకు, RAML/Swagger ఆధారంగా, మీరు భారీ సంఖ్యలో ప్రోగ్రామింగ్ భాషలలో క్లయింట్ మరియు సర్వర్ కోడ్‌లను రూపొందించవచ్చు. మీరు మైక్రోసర్వీస్ కోసం స్వయంచాలకంగా డాక్యుమెంటేషన్‌ను కూడా స్వీకరించవచ్చు మరియు దానిని మీ డెవలపర్-పోర్టల్‌కు అప్‌లోడ్ చేయవచ్చు :).

నిర్మాణాత్మక ఒప్పంద వివరణకు ఉదాహరణ

కాంట్రాక్ట్ వివరణల ఆధారంగా మైక్రోసర్వీస్‌లను పరీక్షించే పద్ధతి తక్కువ సాధారణం. మీరు ఉల్లేఖనం మరియు ఒక భాగం రెండింటినీ వ్రాసినట్లయితే, మీరు వివిధ రకాల ఇన్‌పుట్ డేటాతో సేవ యొక్క సమర్ధతను తనిఖీ చేసే ఆటోటెస్ట్‌ను సృష్టించవచ్చు. ఉల్లేఖనంలో వివరించబడని ప్రతిస్పందన కోడ్‌ను సేవ తిరిగి ఇస్తుందా? ఇది స్పష్టంగా తప్పు డేటాను సరిగ్గా ప్రాసెస్ చేయగలదా?

అంతేకాకుండా, కాంట్రాక్టులు మాత్రమే కాకుండా, ఉల్లేఖనాలను దృశ్యమానం చేసే సాధనాల యొక్క అధిక-నాణ్యత అమలు మైక్రోసర్వీస్‌తో పనిని సులభతరం చేయడం సాధ్యపడుతుంది. అంటే, వాస్తుశిల్పి కాంట్రాక్టును గుణాత్మకంగా వివరించినట్లయితే, దాని ఆధారంగా, డిజైనర్లు మరియు డెవలపర్లు అదనపు సమయ ఖర్చులు లేకుండా ఇతర ఉత్పత్తులలో సేవను అమలు చేస్తారు.

అదనపు సాధనాలను ప్రారంభించడానికి, RAML మరియు OAS రెండూ ప్రమాణం ద్వారా అందించబడని మెటాడేటాను జోడించగల సామర్థ్యాన్ని కలిగి ఉంటాయి (ఉదాహరణకు, OASలో ఇది ఇలా జరుగుతుంది).

సాధారణంగా, మైక్రోసర్వీస్‌ల కోసం ఒప్పందాలను ఉపయోగించడంలో సృజనాత్మకతకు స్కోప్ చాలా పెద్దది... కనీసం సిద్ధాంతపరంగా.

ముళ్ల పందిని పాముతో పోల్చడం

ప్రస్తుతం, అక్రోనిస్‌లో ప్రాధాన్యత అభివృద్ధి ప్రాంతం అక్రోనిస్ సైబర్ ప్లాట్‌ఫారమ్ అభివృద్ధి. అక్రోనిస్ సైబర్ ప్లాట్‌ఫారమ్ అనేది అక్రోనిస్ సైబర్ క్లౌడ్ మరియు ఏజెంట్ పార్ట్‌తో థర్డ్-పార్టీ సేవల ఏకీకరణ యొక్క కొత్త పాయింట్లు. RAMLలో వివరించిన మా అంతర్గత APIలతో మేము సంతోషంగా ఉన్నప్పటికీ, APIని ప్రచురించాల్సిన అవసరం మళ్లీ ఎంపిక ప్రశ్నను లేవనెత్తింది: మా పని కోసం ఏ ఉల్లేఖన ప్రమాణాన్ని ఉపయోగించడం ఉత్తమం?

ప్రారంభంలో, రెండు పరిష్కారాలు ఉన్నాయని అనిపించింది - అత్యంత సాధారణ పరిణామాలు RAML మరియు స్వాగర్ (లేదా OAS). కానీ వాస్తవానికి కనీసం 2 ప్రత్యామ్నాయాలు లేవు, కానీ 3 లేదా అంతకంటే ఎక్కువ ఉన్నాయి.

ఒక వైపు RAML ఉంది - శక్తివంతమైన మరియు సమర్థవంతమైన భాష. ఇది సోపానక్రమం మరియు వారసత్వాన్ని బాగా అమలు చేస్తుంది, కాబట్టి ఈ ఫార్మాట్ చాలా వివరణలు అవసరమయ్యే పెద్ద కంపెనీలకు మరింత అనుకూలంగా ఉంటుంది - అంటే, ఒక ఉత్పత్తి కాదు, కానీ కాంట్రాక్ట్‌లలో సాధారణ భాగాలను కలిగి ఉన్న అనేక మైక్రోసర్వీస్‌లు - ప్రామాణీకరణ పథకాలు, అదే డేటా రకాలు, ఎర్రర్ బాడీలు .

కానీ RAML డెవలపర్, Mulesoft, అభివృద్ధి చెందుతున్న ఓపెన్ API కన్సార్టియంలో చేరారు ఆత్మ విశ్వాసం. Поэтому RAML приостановил свое развитие. Чтобы вообразить формат события представьте, что мейнтейнеры основных компонентов Linux ушли работать в Microsoft. Такая ситуация создает предпосылки для того, чтобы использовать Swagger, который динамично развивается и в последней — третьей версии — практически догоняет RAML по гибкости и функциональности.

ఒక్క విషయం కోసం కాకపోతే...

ఇది ముగిసినట్లుగా, అన్ని ఓపెన్ సోర్స్ యుటిలిటీలు OAS 3.0కి నవీకరించబడలేదు. గోలోని మైక్రోసర్వీస్‌ల కోసం, అనుకూలత లేకపోవడం అత్యంత క్లిష్టమైన విషయం గో-స్వాగర్ స్టాండర్డ్ యొక్క తాజా వెర్షన్ కోసం. అయితే, స్వాగర్ 2 మరియు స్వాగర్ 3 మధ్య వ్యత్యాసం భారీ. ఉదాహరణకు, మూడవ సంస్కరణలో డెవలపర్లు:

ప్రామాణీకరణ పథకాల యొక్క మెరుగైన వివరణ
పూర్తయింది JSON స్కీమా మద్దతు
ఉదాహరణలను జోడించే సామర్థ్యాన్ని అప్‌గ్రేడ్ చేసింది

పరిస్థితి హాస్యాస్పదంగా ఉంది: ప్రమాణాన్ని ఎన్నుకునేటప్పుడు, మీరు RAML, స్వాగర్ 2 మరియు స్వాగర్ 3లను ప్రత్యేక ప్రత్యామ్నాయాలుగా పరిగణించాలి. అయినప్పటికీ, కేవలం Swagger 2 మాత్రమే OpenSource సాధనాలకు మంచి మద్దతును కలిగి ఉంది. RAML చాలా అనువైనది...మరియు సంక్లిష్టమైనది, మరియు స్వాగర్ 3కి సంఘంలో సరైన మద్దతు లేదు, కాబట్టి మీరు యాజమాన్య సాధనాలు లేదా వాణిజ్య పరిష్కారాలను ఉపయోగించాల్సి ఉంటుంది, ఇవి చాలా ఖరీదైనవి.

అంతేకాకుండా, స్వాగర్‌లో రెడీమేడ్ పోర్టల్ వంటి అనేక మంచి ఫీచర్లు ఉంటే editor.swagger.io, దానిపై మీరు ఉల్లేఖనాన్ని అప్‌లోడ్ చేయవచ్చు మరియు వివరణాత్మక వివరణ, లింక్‌లు మరియు కనెక్షన్‌లతో దాని విజువలైజేషన్‌ను పొందవచ్చు, ఆపై మరింత ప్రాథమిక మరియు తక్కువ స్నేహపూర్వక RAML కోసం అలాంటి అవకాశం లేదు. అవును, మీరు GitHubలోని ప్రాజెక్ట్‌ల మధ్య ఏదైనా శోధించవచ్చు, అక్కడ ఒక అనలాగ్‌ను కనుగొని, దానిని మీరే అమలు చేసుకోవచ్చు. అయితే, ఏదైనా సందర్భంలో, ఎవరైనా పోర్టల్‌ను నిర్వహించవలసి ఉంటుంది, ఇది ప్రాథమిక ఉపయోగం లేదా పరీక్ష అవసరాలకు అంత సౌకర్యవంతంగా ఉండదు. అదనంగా, స్వాగర్ మరింత “సూత్రం లేనిది” లేదా మరింత ఉదారమైనది - ఇది కోడ్‌లోని వ్యాఖ్యల నుండి రూపొందించబడుతుంది, ఇది API మొదటి సూత్రానికి విరుద్ధంగా ఉంటుంది మరియు ఏ RAML యుటిలిటీల ద్వారా మద్దతు ఇవ్వదు.

ఒకానొక సమయంలో మేము RAMLతో మరింత సౌకర్యవంతమైన భాషగా పనిచేయడం ప్రారంభించాము మరియు ఫలితంగా మనమే చాలా పనులు చేయాల్సి వచ్చింది. ఉదాహరణకు, ప్రాజెక్ట్‌లలో ఒకటి యుటిలిటీని ఉపయోగిస్తుంది రాంఫికేషన్స్ యూనిట్ పరీక్షలలో, ఇది RAML 0.8కి మాత్రమే మద్దతు ఇస్తుంది. కాబట్టి మేము క్రచెస్‌లను జోడించాల్సి వచ్చింది, తద్వారా యుటిలిటీ RAML వెర్షన్ 1.0 "తినవచ్చు".

మీరు ఎంచుకోవాల్సిన అవసరం ఉందా?

RAML కోసం పరిష్కారాల పర్యావరణ వ్యవస్థను పూర్తి చేయడంలో పనిచేసిన తర్వాత, మేము RAMLని స్వాగర్ 2గా మార్చాలని మరియు దానిలో అన్ని ఆటోమేషన్, వెరిఫికేషన్, టెస్టింగ్ మరియు తదుపరి ఆప్టిమైజేషన్‌ను నిర్వహించాలని నిర్ణయానికి వచ్చాము. ఇది RAML యొక్క సౌలభ్యం మరియు స్వాగర్ నుండి కమ్యూనిటీ టూలింగ్ మద్దతు రెండింటినీ ప్రభావితం చేయడానికి మంచి మార్గం.

ఈ సమస్యను పరిష్కరించడానికి, ఒప్పంద మార్పిడిని అందించే రెండు OpenSource సాధనాలు ఉన్నాయి:

oas-raml-కన్వర్టర్ ప్రస్తుతం మద్దతు లేని యుటిలిటీ. దానితో పని చేస్తున్నప్పుడు, పెద్ద సంఖ్యలో ఫైల్‌లలో "విస్తరించిన" సంక్లిష్ట RAMLలతో దీనికి అనేక సమస్యలు ఉన్నాయని మేము కనుగొన్నాము. ఈ ప్రోగ్రామ్ జావాస్క్రిప్ట్‌లో వ్రాయబడింది మరియు సింటాక్స్ ట్రీ యొక్క రికర్సివ్ ట్రావర్సల్‌ను నిర్వహిస్తుంది. డైనమిక్ టైపింగ్ కారణంగా, ఈ కోడ్‌ను అర్థం చేసుకోవడం కష్టమవుతుంది, కాబట్టి మేము చనిపోయే యుటిలిటీ కోసం పాచెస్‌ని వ్రాసే సమయాన్ని వృథా చేయకూడదని నిర్ణయించుకున్నాము.
వెబ్‌పి-పార్సర్ - ఏదైనా మరియు ప్రతిదానిని మరియు ఏ దిశలోనైనా మార్చడానికి సిద్ధంగా ఉన్నట్లు చెప్పుకునే అదే కంపెనీ నుండి ఒక సాధనం. ఈ రోజు వరకు, RAML 0.8, RAML 1.0 మరియు స్వాగర్ 2.0 కోసం మద్దతు ప్రకటించబడింది. అయితే, మా పరిశోధన సమయంలో, ప్రయోజనం ఇప్పటికీ ఉంది అత్యంత తడిగా మరియు ఉపయోగించలేనిది. డెవలపర్లు ఒక రకాన్ని సృష్టిస్తారు IR, భవిష్యత్తులో కొత్త ప్రమాణాలను త్వరగా జోడించడానికి వారిని అనుమతిస్తుంది. కానీ ఇప్పటివరకు అది కేవలం పని లేదు.

మరియు మేము ఎదుర్కొన్న కష్టాలు అన్నీ ఇన్నీ కావు. స్పెసిఫికేషన్‌కు సంబంధించి రిపోజిటరీ నుండి RAML సరైనదని ధృవీకరించడం మా పైప్‌లైన్‌లోని దశల్లో ఒకటి. మేము అనేక యుటిలిటీలను ప్రయత్నించాము. ఆశ్చర్యకరంగా, వారందరూ వేర్వేరు ప్రదేశాలలో మరియు పూర్తిగా భిన్నమైన చెడు పదాలతో మా ఉల్లేఖనాలను తిట్టారు. మరియు ఎల్లప్పుడూ పాయింట్‌కి కాదు :).

చివరికి, మేము ఇప్పుడు పాత ప్రాజెక్ట్‌లో స్థిరపడ్డాము, దీనికి అనేక సమస్యలు కూడా ఉన్నాయి (కొన్నిసార్లు ఇది నీలిరంగులో క్రాష్ అవుతుంది, సాధారణ వ్యక్తీకరణలతో పని చేసేటప్పుడు సమస్యలు ఉంటాయి). అందువల్ల, ఉచిత సాధనాల ఆధారంగా ధ్రువీకరణ మరియు మార్పిడి సమస్యలను పరిష్కరించడానికి మేము ఒక మార్గాన్ని కనుగొనలేదు మరియు వాణిజ్య ప్రయోజనాన్ని ఉపయోగించాలని నిర్ణయించుకున్నాము. భవిష్యత్తులో, OpenSource సాధనాలు మరింత పరిణతి చెందినందున, ఈ సమస్యను పరిష్కరించడం సులభం కావచ్చు. ఈ సమయంలో, "పూర్తి" కోసం శ్రమ మరియు సమయం ఖర్చులు వాణిజ్య సేవ ఖర్చు కంటే మాకు చాలా ముఖ్యమైనవిగా అనిపించాయి.

తీర్మానం

వీటన్నింటి తర్వాత, మేము మా అనుభవాన్ని పంచుకోవాలనుకుంటున్నాము మరియు ఒప్పందాలను వివరించడానికి ఒక సాధనాన్ని ఎంచుకునే ముందు, దాని నుండి మీకు ఏమి కావాలో మరియు మీరు పెట్టుబడి పెట్టడానికి సిద్ధంగా ఉన్న బడ్జెట్‌ను స్పష్టంగా నిర్వచించాల్సిన అవసరం ఉందని గమనించండి. మేము OpenSource గురించి మరచిపోతే, తనిఖీ చేయడం, మార్చడం మరియు ధృవీకరించడంలో మీకు సహాయపడే అనేక సేవలు మరియు ఉత్పత్తులు ఇప్పటికే ఉన్నాయి. కానీ అవి ఖరీదైనవి, మరియు కొన్నిసార్లు చాలా ఖరీదైనవి. ఒక పెద్ద కంపెనీకి, అటువంటి ఖర్చులు భరించదగినవి, కానీ స్టార్టప్ కోసం అవి పెద్ద భారంగా మారవచ్చు.

మీరు తర్వాత ఉపయోగించే సాధనాల సమితిని నిర్ణయించండి. ఉదాహరణకు, మీరు ఒక ఒప్పందాన్ని ప్రదర్శించాల్సిన అవసరం ఉన్నట్లయితే, అందమైన APIని కలిగి ఉన్న Swagger 2ని ఉపయోగించడం సులభం అవుతుంది, ఎందుకంటే RAMLలో మీరు సేవను మీరే నిర్మించుకోవాలి మరియు నిర్వహించాలి.
మీకు ఎక్కువ పనులు ఉంటే, సాధనాల అవసరం విస్తృతంగా ఉంటుంది మరియు అవి వేర్వేరు ప్లాట్‌ఫారమ్‌లకు భిన్నంగా ఉంటాయి మరియు భవిష్యత్తులో మీ ఖర్చులను తగ్గించే ఎంపిక చేయడానికి అందుబాటులో ఉన్న సంస్కరణలతో మిమ్మల్ని మీరు వెంటనే పరిచయం చేసుకోవడం మంచిది.

కానీ నేడు ఉన్న అన్ని పర్యావరణ వ్యవస్థలు అసంపూర్ణమైనవని గుర్తించడం విలువ. అందువల్ల, కంపెనీలో RAMLలో పని చేయడానికి ఇష్టపడే అభిమానులు ఉన్నట్లయితే, "ఇది మీ ఆలోచనలను మరింత సరళంగా వ్యక్తీకరించడానికి మిమ్మల్ని అనుమతిస్తుంది" లేదా దీనికి విరుద్ధంగా, స్వాగర్‌ను ఇష్టపడతారు ఎందుకంటే "ఇది స్పష్టంగా ఉంది" కాబట్టి వారిని పనికి వదిలివేయడం ఉత్తమం. ఏ ఫార్మాట్‌ల సాధనాలకు ఫైల్‌తో మార్పు అవసరమో, అవి దేనిలో ఉన్నాయో వాటికి అలవాటు పడతారు మరియు దానిని కోరుకుంటారు.

మా అనుభవం విషయానికొస్తే, మా RAML-Swagger ఆర్కిటెక్చర్ ఆధారంగా మనం ఎలాంటి స్టాటిక్ మరియు డైనమిక్ చెక్‌లను నిర్వహిస్తాము, అలాగే కాంట్రాక్ట్‌ల నుండి మనం ఏ డాక్యుమెంటేషన్‌ను రూపొందిస్తాము మరియు అవన్నీ ఎలా పనిచేస్తాయో ఈ క్రింది పోస్ట్‌లలో మాట్లాడుతాము.

నమోదు చేసుకున్న వినియోగదారులు మాత్రమే సర్వేలో పాల్గొనగలరు. సైన్ ఇన్ చేయండిదయచేసి.