তাহলে এটা কি RAML বা OAS (Swagger)?

মাইক্রোসার্ভিসের গতিশীল বিশ্বে, যেকোনো কিছু পরিবর্তন হতে পারে—যেকোনো উপাদানকে ভিন্ন ভাষায়, বিভিন্ন কাঠামো এবং স্থাপত্য ব্যবহার করে পুনরায় লেখা যেতে পারে। শুধুমাত্র চুক্তিগুলি অপরিবর্তিত থাকা উচিত যাতে মাইক্রোসার্ভিসের সাথে অভ্যন্তরীণ রূপান্তর নির্বিশেষে কিছু স্থায়ী ভিত্তিতে বাইরে থেকে যোগাযোগ করা যায়। এবং আজ আমরা চুক্তি বর্ণনা করার জন্য একটি বিন্যাস নির্বাচন করার আমাদের সমস্যা সম্পর্কে কথা বলব এবং আমরা যে নিদর্শনগুলি পেয়েছি তা শেয়ার করব।

পোস্ট প্রস্তুত আনা মেলেখোভা и ভ্লাদিমির ল্যাপটিন

মাইক্রোসার্ভিস। অ্যাক্রোনিস সাইবার ক্লাউড বিকাশ করার সময়, আমরা বুঝতে পেরেছিলাম যে আমরা তাদের এড়াতে পারিনি। এবং একটি মাইক্রোসার্ভিস ডিজাইন করা চুক্তির আনুষ্ঠানিকতা ছাড়া অসম্ভব, যা মাইক্রোসার্ভিসের ইন্টারফেসকে প্রতিনিধিত্ব করে।

কিন্তু যখন একটি পণ্যে একাধিক উপাদান থাকে এবং চুক্তির বিকাশ একটি নিয়মিত কার্যকলাপে পরিণত হয়, তখন আপনি সাহায্য করতে পারবেন না কিন্তু প্রক্রিয়া অপ্টিমাইজেশন সম্পর্কে চিন্তা শুরু করতে পারবেন। এটা স্পষ্ট হয়ে ওঠে যে ইন্টারফেস (চুক্তি) এবং বাস্তবায়ন (মাইক্রোসার্ভিস) একে অপরের সাথে মিলিত হতে হবে, বিভিন্ন উপাদান একইভাবে একই জিনিসগুলি করতে হবে এবং এই সমস্ত সিদ্ধান্তের কেন্দ্রীভূত সিদ্ধান্ত ছাড়াই প্রতিটি দলকে বাধ্য করা হবে তাদের পেতে বার বার সময় ব্যয় করুন।

অ্যামাজন মাইক্রোসার্ভিসেস ডায়াগ্রাম থেকে টুইট ওয়ার্নার ভোগেলিস, সিটিও আমাজন
দ্বিধা কি? প্রকৃতপক্ষে, মাইক্রোসার্ভিসে ইন্টারঅ্যাক্ট করার দুটি উপায় আছে - HTTP বিশ্রাম এবং Google থেকে gRPC। গুগলের টেকনোলজি স্ট্যাকের মধ্যে আটকা পড়তে চাই না, আমরা HTTP রেস্ট বেছে নিয়েছি। HTTP REST চুক্তির টীকাগুলি প্রায়শই দুটি ফর্ম্যাটের একটিতে বর্ণনা করা হয়: RAML এবং OAS, যা আগে Swagger নামে পরিচিত ছিল৷ তাই, প্রতিটি উন্নয়ন দলকে মানগুলির মধ্যে একটি বেছে নেওয়ার প্রয়োজন হয়৷ কিন্তু দেখা যাচ্ছে, এই পছন্দটি করা খুব কঠিন হতে পারে।

কেন টীকা প্রয়োজন?

টীকাটি প্রয়োজন যাতে একজন বহিরাগত ব্যবহারকারী সহজেই বুঝতে পারে যে আপনার পরিষেবাটি তার HTTP ইন্টারফেসের মাধ্যমে কী করা যেতে পারে। অর্থাৎ, একটি মৌলিক স্তরে, টীকাটিতে অবশ্যই উপলব্ধ সংস্থানগুলির একটি তালিকা, তাদের HTTP পদ্ধতি, অনুরোধ সংস্থা, পরামিতির একটি তালিকা, প্রয়োজনীয় এবং সমর্থিত শিরোনামগুলির একটি ইঙ্গিত, সেইসাথে রিটার্ন কোড এবং প্রতিক্রিয়া বিন্যাস থাকতে হবে। চুক্তির টীকাটির একটি অত্যন্ত গুরুত্বপূর্ণ উপাদান হল তাদের মৌখিক বিবরণ ("আপনি অনুরোধে এই ক্যোয়ারী প্যারামিটার যোগ করলে কি হবে?", "কোন ক্ষেত্রে কোড 400 ফেরত দেওয়া হবে?")

যাইহোক, যখন প্রচুর সংখ্যক মাইক্রোসার্ভিস তৈরি করার কথা আসে, আপনি লিখিত টীকা থেকে অতিরিক্ত মান বের করতে চান। উদাহরণস্বরূপ, RAML/Swagger-এর উপর ভিত্তি করে, আপনি প্রচুর সংখ্যক প্রোগ্রামিং ভাষায় ক্লায়েন্ট এবং সার্ভার কোড উভয়ই তৈরি করতে পারেন। এছাড়াও আপনি মাইক্রোসার্ভিসের জন্য স্বয়ংক্রিয়ভাবে ডকুমেন্টেশন গ্রহণ করতে পারেন এবং এটি আপনার ডেভেলপার-পোর্টালে আপলোড করতে পারেন :)।

একটি কাঠামোগত চুক্তির বিবরণের উদাহরণ

চুক্তির বিবরণের উপর ভিত্তি করে মাইক্রোসার্ভিস পরীক্ষা করার অভ্যাস কম সাধারণ। আপনি যদি একটি টীকা এবং একটি উপাদান উভয়ই লিখে থাকেন, তাহলে আপনি একটি স্বয়ংক্রিয় পরীক্ষা তৈরি করতে পারেন যা বিভিন্ন ধরণের ইনপুট ডেটা সহ পরিষেবাটির পর্যাপ্ততা পরীক্ষা করে৷ পরিষেবাটি কি একটি প্রতিক্রিয়া কোড ফেরত দেয় যা টীকাতে বর্ণিত হয় না? এটা সঠিকভাবে স্পষ্টভাবে ভুল তথ্য প্রক্রিয়া করতে সক্ষম হবে?

তদুপরি, কেবলমাত্র চুক্তিগুলিই নয়, টীকাগুলিকে ভিজ্যুয়ালাইজ করার সরঞ্জামগুলির উচ্চ-মানের বাস্তবায়ন মাইক্রোসার্ভিসের সাথে কাজটিকে সহজ করা সম্ভব করে তোলে। অর্থাৎ, যদি স্থপতি গুণগতভাবে চুক্তিটি বর্ণনা করেন, এর ভিত্তিতে, ডিজাইনার এবং বিকাশকারীরা অতিরিক্ত সময় ব্যয় ছাড়াই অন্যান্য পণ্যগুলিতে পরিষেবাটি বাস্তবায়ন করবে।

অতিরিক্ত সরঞ্জামগুলি সক্ষম করতে, RAML এবং OAS উভয়েরই মেটাডেটা যুক্ত করার ক্ষমতা রয়েছে যা স্ট্যান্ডার্ড দ্বারা সরবরাহ করা হয়নি (উদাহরণস্বরূপ, এইভাবে এটি OAS এ করা হয়).

সাধারণভাবে, মাইক্রোসার্ভিসের জন্য চুক্তি ব্যবহারে সৃজনশীলতার সুযোগ বিশাল... অন্তত তাত্ত্বিকভাবে।

একটি সাপের সাথে একটি হেজহগের তুলনা

বর্তমানে, অ্যাক্রোনিসের অগ্রাধিকার বিকাশের ক্ষেত্রটি হল অ্যাক্রোনিস সাইবার প্ল্যাটফর্মের বিকাশ। অ্যাক্রোনিস সাইবার প্ল্যাটফর্ম অ্যাক্রোনিস সাইবার ক্লাউড এবং এজেন্ট অংশের সাথে তৃতীয় পক্ষের পরিষেবাগুলির একীকরণের নতুন পয়েন্ট। যদিও আমরা RAML-এ বর্ণিত আমাদের অভ্যন্তরীণ APIগুলির সাথে খুশি ছিলাম, API প্রকাশ করার প্রয়োজনীয়তা আবার পছন্দের প্রশ্ন উত্থাপন করেছে: আমাদের কাজের জন্য কোন টীকা মান ব্যবহার করা ভাল?

প্রাথমিকভাবে, মনে হয়েছিল যে দুটি সমাধান ছিল - সবচেয়ে সাধারণ উন্নয়নগুলি হল RAML এবং Swagger (বা OAS)। কিন্তু বাস্তবে দেখা গেল যে কমপক্ষে 2টি বিকল্প নয়, তবে 3 বা তার বেশি।

একদিকে রয়েছে RAML - একটি শক্তিশালী এবং দক্ষ ভাষা। এটি শ্রেণিবিন্যাস এবং উত্তরাধিকারকে ভালভাবে প্রয়োগ করে, তাই এই বিন্যাসটি বড় কোম্পানিগুলির জন্য আরও উপযুক্ত যেগুলির জন্য অনেকগুলি বিবরণের প্রয়োজন - অর্থাৎ, একটি পণ্য নয়, কিন্তু অনেকগুলি মাইক্রোসার্ভিস যা চুক্তির সাধারণ অংশ রয়েছে - প্রমাণীকরণ স্কিম, একই ডেটা প্রকার, ত্রুটি সংস্থাগুলি .

কিন্তু RAML এর বিকাশকারী, Mulesoft, Open API কনসোর্টিয়ামে যোগদান করেছে, যা বিকাশ করছে সদম্ভ চাল. অতএব, RAML এর উন্নয়ন স্থগিত করেছে। ইভেন্টের বিন্যাস কল্পনা করতে, কল্পনা করুন যে প্রধান লিনাক্স উপাদানগুলির রক্ষণাবেক্ষণকারীরা মাইক্রোসফ্টে কাজ করতে ছেড়ে গেছে। এই পরিস্থিতি সোয়াগার ব্যবহার করার পূর্বশর্ত তৈরি করে, যা গতিশীলভাবে বিকাশ করছে এবং সর্বশেষ - তৃতীয় সংস্করণে - নমনীয়তা এবং কার্যকারিতার ক্ষেত্রে কার্যত RAML-এর সাথে ধরা পড়ে।

একের জন্য না হলে কিন্তু...

এটি দেখা যাচ্ছে, সমস্ত ওপেন-সোর্স ইউটিলিটিগুলি OAS 3.0-তে আপডেট করা হয়নি। Go-তে মাইক্রোসার্ভিসের জন্য, সবচেয়ে গুরুত্বপূর্ণ বিষয় হবে অভিযোজনের অভাব দোলাচল স্ট্যান্ডার্ডের সর্বশেষ সংস্করণের জন্য। যাইহোক, Swagger 2 এবং Swagger 3 এর মধ্যে পার্থক্য বিপুল. উদাহরণস্বরূপ, তৃতীয় সংস্করণে বিকাশকারীরা:

• প্রমাণীকরণ স্কিমগুলির উন্নত বিবরণ
• সম্পন্ন JSON স্কিমা সমর্থন
• উদাহরণ যোগ করার ক্ষমতা আপগ্রেড

পরিস্থিতিটি মজার: একটি মান নির্বাচন করার সময়, আপনাকে আলাদা বিকল্প হিসাবে RAML, Swagger 2 এবং Swagger 3 বিবেচনা করতে হবে। যাইহোক, শুধুমাত্র Swagger 2 এর ওপেনসোর্স সরঞ্জামগুলির জন্য ভাল সমর্থন রয়েছে। RAML খুবই নমনীয়...এবং জটিল, এবং Swagger 3 সম্প্রদায়ের দ্বারা দুর্বলভাবে সমর্থিত, তাই আপনাকে মালিকানাধীন সরঞ্জাম বা বাণিজ্যিক সমাধান ব্যবহার করতে হবে, যা বেশ ব্যয়বহুল হতে থাকে।

তদুপরি, যদি সোয়াগারে অনেক সুন্দর বৈশিষ্ট্য থাকে, যেমন একটি রেডিমেড পোর্টাল editor.swagger.io, যার উপর আপনি একটি টীকা আপলোড করতে পারেন এবং একটি বিশদ বিবরণ, লিঙ্ক এবং সংযোগ সহ এর ভিজ্যুয়ালাইজেশন পেতে পারেন, তারপরে আরও মৌলিক এবং কম বন্ধুত্বপূর্ণ RAML-এর জন্য এমন কোনও সুযোগ নেই। হ্যাঁ, আপনি গিটহাবের প্রকল্পগুলির মধ্যে কিছু অনুসন্ধান করতে পারেন, সেখানে একটি অ্যানালগ খুঁজে পেতে এবং এটি নিজেই স্থাপন করতে পারেন। যাইহোক, যে কোনও ক্ষেত্রে, কাউকে পোর্টালটি বজায় রাখতে হবে, যা মৌলিক ব্যবহার বা পরীক্ষার প্রয়োজনের জন্য এতটা সুবিধাজনক নয়। তদতিরিক্ত, সোয়াগার আরও "নীতিবিহীন" বা আরও উদার - এটি কোডের মন্তব্য থেকে তৈরি করা যেতে পারে, যা অবশ্যই API প্রথম নীতির বিরুদ্ধে যায় এবং RAML ইউটিলিটিগুলির কোনও দ্বারা সমর্থিত নয়।

এক সময় আমরা আরও নমনীয় ভাষা হিসাবে RAML এর সাথে কাজ শুরু করেছিলাম এবং ফলস্বরূপ আমাদের নিজেদের অনেক কিছু করতে হয়েছিল। উদাহরণস্বরূপ, প্রকল্পগুলির মধ্যে একটি ইউটিলিটি ব্যবহার করে ramlfications ইউনিট পরীক্ষায়, যা শুধুমাত্র RAML 0.8 সমর্থন করে। তাই আমাদের ক্রাচ যোগ করতে হয়েছিল যাতে ইউটিলিটি RAML সংস্করণ 1.0 "খেতে" পারে।

আপনি নির্বাচন করতে হবে?

RAML-এর সমাধানের ইকোসিস্টেম সম্পূর্ণ করার জন্য কাজ করার পরে, আমরা এই সিদ্ধান্তে পৌঁছেছি যে আমাদের RAML-কে Swagger 2-এ রূপান্তর করতে হবে এবং এতে সমস্ত অটোমেশন, যাচাইকরণ, পরীক্ষা এবং পরবর্তী অপ্টিমাইজেশন করতে হবে। এটি RAML-এর নমনীয়তা এবং Swagger থেকে কমিউনিটি টুলিং সমর্থন উভয়ই লাভ করার একটি ভাল উপায়।

এই সমস্যাটি সমাধান করার জন্য, দুটি ওপেনসোর্স সরঞ্জাম রয়েছে যা চুক্তি রূপান্তর প্রদান করবে:

1. oas-raml-কনভার্টার বর্তমানে একটি অসমর্থিত ইউটিলিটি। এটির সাথে কাজ করার সময়, আমরা আবিষ্কার করেছি যে এটির জটিল RAML-এর সাথে অনেকগুলি সমস্যা রয়েছে যা প্রচুর সংখ্যক ফাইলের উপর "বিস্তৃত"। এই প্রোগ্রামটি জাভাস্ক্রিপ্টে লেখা এবং একটি সিনট্যাক্স ট্রির পুনরাবৃত্তিমূলক ট্রাভার্সাল সম্পাদন করে। গতিশীল টাইপিংয়ের কারণে, এই কোডটি বোঝা কঠিন হয়ে পড়ে, তাই আমরা একটি মৃত ইউটিলিটির জন্য প্যাচ লেখার সময় নষ্ট না করার সিদ্ধান্ত নিয়েছি।
2. ওয়েবাপি-পার্সার - একই কোম্পানির একটি টুল যা দাবি করে যে কিছু এবং সবকিছু রূপান্তর করতে প্রস্তুত, এবং যে কোনো দিকে। আজ পর্যন্ত, RAML 0.8, RAML 1.0 এবং Swagger 2.0-এর জন্য সমর্থন ঘোষণা করা হয়েছে। যাইহোক, আমাদের গবেষণার সময়, উপযোগিতা এখনও ছিল অত্যন্ত স্যাঁতসেঁতে এবং অব্যবহৃত। বিকাশকারীরা এক ধরণের তৈরি করে IR, ভবিষ্যতে তাদের দ্রুত নতুন মান যোগ করার অনুমতি দেয়। কিন্তু এখন পর্যন্ত এটি কাজ করে না।

এবং যে সব অসুবিধা আমরা সম্মুখীন না. আমাদের পাইপলাইনের একটি ধাপ হল স্পেসিফিকেশনের সাপেক্ষে রিপোজিটরি থেকে RAML সঠিক কিনা তা যাচাই করা। আমরা বেশ কয়েকটি ইউটিলিটি চেষ্টা করেছি। আশ্চর্যজনকভাবে, তারা সবাই বিভিন্ন জায়গায় এবং সম্পূর্ণ ভিন্ন খারাপ শব্দ দিয়ে আমাদের টীকাগুলিতে শপথ করেছিল। এবং সর্বদা বিন্দুতে নয় :)।

শেষ পর্যন্ত, আমরা একটি এখন পুরানো প্রকল্পে স্থির হয়েছি, যার অনেকগুলি সমস্যাও রয়েছে (কখনও কখনও এটি নীল থেকে ক্র্যাশ হয়ে যায়, রেগুলার এক্সপ্রেশনের সাথে কাজ করার সময় সমস্যা হয়)। এইভাবে, আমরা বিনামূল্যে সরঞ্জামগুলির উপর ভিত্তি করে বৈধতা এবং রূপান্তরের সমস্যাগুলি সমাধান করার একটি উপায় খুঁজে পাইনি এবং একটি বাণিজ্যিক ইউটিলিটি ব্যবহার করার সিদ্ধান্ত নিয়েছি। ভবিষ্যতে, ওপেনসোর্স সরঞ্জামগুলি আরও পরিপক্ক হওয়ার সাথে সাথে এই সমস্যাটি সমাধান করা আরও সহজ হতে পারে। ইতিমধ্যে, "ফিনিশিং" এর জন্য শ্রম এবং সময় ব্যয় আমাদের কাছে একটি বাণিজ্যিক পরিষেবার ব্যয়ের চেয়ে বেশি তাৎপর্যপূর্ণ বলে মনে হয়েছিল।

উপসংহার

এত কিছুর পরে, আমরা আমাদের অভিজ্ঞতা শেয়ার করতে চাই এবং নোট করতে চাই যে চুক্তি বর্ণনা করার জন্য একটি টুল বেছে নেওয়ার আগে, আপনাকে স্পষ্টভাবে সংজ্ঞায়িত করতে হবে যে আপনি এটি থেকে কী চান এবং আপনি কোন বাজেটে বিনিয়োগ করতে ইচ্ছুক। আমরা যদি OpenSource এর কথা ভুলে যাই, সেখানে ইতিমধ্যেই প্রচুর পরিসেবা এবং পণ্য রয়েছে যা আপনাকে চেক করতে, রূপান্তর করতে এবং যাচাই করতে সাহায্য করবে৷ কিন্তু তারা ব্যয়বহুল, এবং কখনও কখনও খুব ব্যয়বহুল। একটি বড় কোম্পানির জন্য, এই ধরনের খরচ সহনীয়, কিন্তু একটি স্টার্টআপের জন্য তারা একটি বড় বোঝা হয়ে উঠতে পারে।

আপনি পরে ব্যবহার করবেন এমন সরঞ্জামগুলির সেট নির্ধারণ করুন। উদাহরণস্বরূপ, যদি আপনাকে শুধুমাত্র একটি চুক্তি প্রদর্শন করতে হয়, তাহলে Swagger 2 ব্যবহার করা সহজ হবে, যার একটি সুন্দর API রয়েছে, কারণ RAML-এ আপনাকে নিজেই পরিষেবাটি তৈরি এবং বজায় রাখতে হবে।
আপনার কাছে যত বেশি কাজ থাকবে, টুলগুলির প্রয়োজনীয়তা তত বেশি হবে এবং সেগুলি বিভিন্ন প্ল্যাটফর্মের জন্য আলাদা, এবং ভবিষ্যতে আপনার খরচ কম করে এমন একটি পছন্দ করার জন্য উপলব্ধ সংস্করণগুলির সাথে অবিলম্বে নিজেকে পরিচিত করা ভাল।

কিন্তু এটা স্বীকার করা মূল্যবান যে বর্তমানে বিদ্যমান সমস্ত বাস্তুতন্ত্রই অসিদ্ধ। অতএব, যদি কোম্পানিতে এমন ভক্ত থাকে যারা RAML-এ কাজ করতে পছন্দ করে কারণ "এটি আপনাকে আরও নমনীয়ভাবে চিন্তাভাবনা প্রকাশ করতে দেয়" অথবা, বিপরীতে, Swagger পছন্দ করে কারণ "এটি পরিষ্কার", তাদের কাজ করতে ছেড়ে দেওয়াই ভাল। তারা এটিতে অভ্যস্ত এবং এটি চায়, কারণ যে কোনও ফর্ম্যাটের সরঞ্জামগুলির একটি ফাইলের সাথে পরিবর্তনের প্রয়োজন হয়।

আমাদের অভিজ্ঞতার জন্য, নিম্নলিখিত পোস্টগুলিতে আমরা আমাদের RAML-Swagger আর্কিটেকচারের উপর ভিত্তি করে আমরা কী স্থিতিশীল এবং গতিশীল চেক পরিচালনা করি, সেইসাথে আমরা চুক্তি থেকে কোন ডকুমেন্টেশন তৈরি করি এবং এটি কীভাবে কাজ করে সে সম্পর্কে কথা বলব।

শুধুমাত্র নিবন্ধিত ব্যবহারকারীরা জরিপে অংশগ্রহণ করতে পারবেন। সাইন ইন করুনকরুন।

মাইক্রোসার্ভিস চুক্তিগুলি টীকা করতে আপনি কোন ভাষা ব্যবহার করেন?

• RAML 0.8

• RAML 1.0

• সোয়াগার 2

• OAS3 (ওরফে)

• প্রতিচিত্র

• অন্যান্য

• ব্যবহার করছে না

100 ব্যবহারকারী ভোট দিয়েছেন। 24 জন ব্যবহারকারী বিরত ছিলেন।

উত্স: www.habr.com