https://virgool.io/feed/@m_36024583 fa 2026-06-14 08:37:05 https://static.virgool.io/images/default-avatar.jpg https://virgool.io/@m_36024583 https://virgool.io/@m_36024583/%D8%A7%DB%8C%D8%AC%D8%A7%D8%AF-%D9%BE%D8%A7%D8%B3%D8%AE-%D8%A7%D8%B3%D8%AA%D8%A7%D9%86%D8%AF%D8%A7%D8%B1%D8%AF-%D8%A8%D8%B1%D8%A7%DB%8C-api-gb6mnefo60qe ساختن API کار سختی به نظر نمی‌آید، تا اینکه شروع به فکرکردن در مورد برگرداند ریسپاسن ها یا خطا ها میکنی.ما در HTTP یک سری status code داریم که بخشی از آن‌ها نشان‌دهنده‌ی خطاهای عمومی هستند. امّا مشکل اینجا است که برای کاربردهای واقعی، این چندتا شناسه‌ی خطای محدود و کلّی کافی نیستند. از طرفی اگر مجبور به استفاده از API های دیگران بشوید، می‌بینید که اکثر اوقات پیام خطایی که برمی‌گردد هیچ کمکی به شما برای فهمیدن اینکه چطوری می‌توان مشکل را حل کرد نمی‌کند.در این نوشته می‌خواهیم راه حل استانداردی که از سال ۲۰۱۶ معرّفی شده ولی هنوز خیلی‌ها ازش استفاده نمی‌کننند را یادبگیریم.در حال حاضر هرکسی برای خودش روشی را پیش‌گرفته و خطاها را به همان روش برمی‌گرداند. شاید با خودتان فکرکنید که همین که یک مدل انتخاب شود و به همان پایبند بمانیم همه‌چیز خوب خواهد بود و مشکلی پیش نخواهد آمد. امّا زندگی به همین سادگی‌ها نیست.اگر همان یک روش، روش ناکارامدی باشد، پایبندی به آن تنها زجرکشیدن ما را طولانی‌تر می‌کند. به علاوه ما خیلی وقت‌ها مجبوریم که از API های مختلف استفاده کنیم. حالا اگر هرکدام از این‌ها برای خودشان یک ساختار را در پیش بگیرند، حتّی اگر آن ساختار خوب هم باشد، باز مصرف‌کننده باید برای میلیاردها استاندارد مختلف کد مجزا تولید کند. بیایید قبل از اینکه سراغ روش استاندارد برویم، در اینجا دو مشکل اساسی نبود استاندارد برای توصیف خطا در API ها را ببینیم.این ساختار پیام خطای استاندارد گوگل است:{ &quoterror&quot: { &quoterrors&quot: [ { &quotdomain&quot: &quotglobal&quot, &quotreason&quot: &quotinvalidParameter&quot, &quotmessage&quot: &quotInvalid string value: 'asdf'. Allowed values: [mostpopular]&quot, &quotlocationType&quot: &quotparameter&quot, &quotlocation&quot: &quotchart&quot } ], &quotcode&quot: 400, &quotmessage&quot: &quotInvalid string value: 'asdf'. Allowed values: [mostpopular]&quot } }و این هم ساختار پیام خطای استاندارد فیسبوک:{ &quoterror&quot: { &quotmessage&quot: &quotInvalid OAuth access token.&quot, &quottype&quot: &quotOAuthException&quot, &quotcode&quot: 190, &quoterror_subcode&quot: 1234567, &quotfbtrace_id&quot: &quotBLBz/WZt8dN&quot } }همانطوری که می‌بینید حتّی در یک فیلد هم با هم اشتراک ندارند. این تفاوت زیاد در روش‌های مختلف، توسعه‌ی نرم‌افزارهایی را که به API های مختلف وابسته‌اند را به شدّت سخت می‌کند.توصیف استاندارد مشکلات با RFC 7807خبر خوش این است که در سال ۲۰۱۶ سازمان فخیمه‌ی Internet Engineering Task Force منّت بر دیدگان توسعه‌دهندگان سراسر جهان گذاشت و با انتشار RFC 7807 یک روش استاندارد و خیلی مناسب را برای توضیح مشکل در API های HTTP ارائه کرد. با استفاده از این استاندارد، می‌توان مشکلات و خطاها را به شکلی در API مشخّص کرد که هم انسان‌ها که کاربر نهایی هستند بتوانند به بهترین شکل متوجّه دلیل خطا بشوند و هم نرم‌افزارها بتوانند به راحتی خطاها را مدیریت کنند. حالا بیایید با هم ببینم که این استاندارد چه می‌گوید.پاسخ خطا باید با چه فرمتی ساخته شود؟طبق این استاندارد ما می‌توانیم خطاها را به شکل یک شئ JSON یا یک مستند XML توصیف کنیم. هرچند که استفاده از JSON ترجیح بیشتری دارد و در این نوشته هم ما تنها به آن می‌پردازیم. پیام‌های HTTP که حامل توصیف مشکل هستند و از این استاندارد پیروی می‌کنند، باید Content-Type شان یکی از مقادیر: application/problem+json یا application/problem+xml باشد.اینطوری از همان ابتدای پیام مشخّص است که قرار است با یک خطا که طبق این استاندارد ساخته شده است کار کنیم. مثلاً فرض‌کنید که ما یک وبسایت مدیریت دروس برای دانشگاه داریم. در این وبسایت یک API وجود دارد که می‌توان با فرستادن متد GET به آن لیست تکالیف هفته‌ی بعد را گرفت.بگذارید بگوییم آدرس این API این است: https://university.xyz/api/2/course/<id>/assignmentsخب حالا فرض‌کنید که این API به افرادی که در این درس ثبت نام نکرده‌اند خطا برمی گرداند. از اینجا به بعد بخش‌های مختلف استاندارد توصیف خطا را روی همین مثال جلو می‌بریم. خب حالا ما می‌خواهیم به کاربری که در درس مهندسی اینترنت ثبت نام نکرده ولی درخواست گرفتن لیست تکالیف آن را دارد خطا نشان بدهیم (فرض‌کنید که id این درس عدد ۱ است). پاسخی که کاربر به عنوان یک پیام HTTP می‌گیرد چیزی شبیه به این است (بخش header می‌تواند خیلی بیشتر باشد ولی چون اکثر بخش‌هایش به این نوشته مربوط نیستند، آن‌ها را نادیده می‌گیریم):HTTP/1.1 403 Forbidden Content-Type: application/problem+json; charset=UTF-8 Content-Language: faخب حالا ببینیم که چطوری محتوای مرتبط با این پیام را می‌توانیم بسازیم.نوع خطاهر خطا می‌تواند بخش‌های مختلفی داشته باشد که وجود هیچ‌کدام از آن‌ها اجباری نیست. امّا چند بخش آن به صورت صریح درون استاندارد مشخّص شده اند. یکی از بخش‌های خیلی مهم یک پیام خطا، نوع خطا است. نوع خطا با کلید type در شئ json ما قرار می‌گیرد. در استانداردی که درون این RFC مشخّص شده است، ما نوع خطا را به جای استفاده از مقادیر عددی یا رشته‌ها، با یک URI مشخّص می‌کنیم. این آدرس باید به یک صفحه‌ی HTML ختم بشود که درون آن توضیحات کامل درمورد این خطا و روش حل آن نوشته شده باشد. ما header پاسخ HTTP را در بخش قبل دیدیم و از اینجا به بعد دیگر آن را تکرار نمی‌کنیم. حالا محتوایی که آن پاسخ HTTP با خودش حمل می‌کند چیزی شبیه به این می‌شود:{ &quottype&quot: &quothttps://university.xyz/api/2/errors/course-not-accessible&quot }خب پیام خطای ما تا اینجا این شکلی است.حالا اگر کاربر آدرسی که برای type وارد کرده‌ایم را درون مرورگرش وارد کند، باید به صفحه‌ای برسد که به صورت کامل توضیح داده که این خطا برای چه به وجود می‌آید و برای حل آن چه کاری می‌توان کرد.مثلاً در این مورد باید توضیح بدهد که کاربران تنها به لیست تکالیف دروسی که در آن شرکت می‌کنند دسترسی دارند و بگوید که برای ثبت نام در درس، کاربر باید چه کاری انجام بدهد.عنوان خطایکی دیگر از بخش‌های خطا، عنوان آن است. عنوان با کلمه‌ی کلیدی title درون شئ خطا مشخّص می‌شود. عنوان خطا یک متن کوتاه و قابل فهم برای انسان‌ها است که باید برای تمام خطاهایی که نوع یکسانی دارند، مشابه باشد. مگر اینکه سایت شما کاربرانی با زبان‌های مختلف داشته باشد و بخواهید عنوان خطا را برای زبان‌های مختلف ترجمه کنید.{ &quottype&quot: &quothttps://university.xyz/api/2/errors/course-not-accessible&quot, &quottitle&quot: &quotشما اجازه‌ی دسترسی به این درس را ندارید.&quot }شناسه‌ی خطاشناسه‌ی خطا همان status code پیام‌های HTTP است. یعنی چیزی نیست که درون شئ json ما قرار بگیرد. هدف از اشاره به آن صرفاً این است که حواستان باشد که باید مرتبط‌ترین status code را به خطایی که رخ داده به عنوان http status code انتخاب کنید. مثلاً در مثالی که ما در این نوشته داریم روی آن کار می‌کنیم، status را برابر ۴۰۳ گذاشته‌ایم. چون کاربر اجازه‌ی دسترسی به این بخش را ندارد. یک چیز دیگری که باید حواستان به آن باشد این است که اگر در پاسخی که دارید برمی‌گردانید به بیش از یک مشکل اشاره شده است (در بخش‌های بعدی می‌بینیم که چطوری می‌توان این کار را کرد) باید از شناسه‌ی 207 استفاده کنید.توضیحات خطابخش دیگری که می‌تواند درون شئ خطا قرار بگیرد مقدار detail است. در این بخش ما باید یک توضیح درمورد مشکلی خاصی که الان پیش آمده است بدهیم. مثلاً در مثال ما، باید توضیح بدهیم که چرا کاربر نمی‌تواند لیست تکالیف را ببیند:{ &quottype&quot: &quothttps://university.xyz/api/2/errors/course-not-accessible&quot, &quottitle&quot: &quotشما اجازه‌ی دسترسی به این درس را ندارید.&quot, &quotdetail&quot: &quotشما امکان دریافت لیست تکالیف درس مهندسی اینترنت را ندارید. چون این درس در لیست دروس ثبت نامی شما قرار ندارد.&quot }استاد : دکتر مریم حاجی اسمعیلی. دکترای علوم کامپیوتر از دانشگاه کینگستون لندنDr.Maryam HajiesmaeiliPhD of computer science from Kingston university of London رامبد سواحلی مقدم رامبد سواحلی مقدم Fri, 10 Jun 2022 23:13:04 +0430 https://virgool.io/@m_36024583/grpc-%DA%86%DB%8C%D8%B3%D8%AA-ssmseku84i5n بهتره قبل از اینکه بدونیم gRPC چیه بهتره اول راجب RPC صحبت کنیم.RPC مخفف Remote Procedure Call هست و از سال ۱۹۷۰ به وجود آمده است. یه پروتکل واسه فراخوانی یک سرویس از یک برنامه داخل یک برنامه دیگر است. مثلا اگر ۲تا برنامه به نام A و B داشته باشیم, برنامه A می تواند یک متد(فانکشن) از برنامه B را فراخوانی کند و بلعکس.اگر تاریخچه Distributed APIs را بررسی کنیم تکنولوژی های مختلفی را می بینیم که هر کدام در دوره خود محبوب بودند و در حال حاضر API نویسی را می توانیم به ۳ نوع تقسیم کنیم:1-SOAP2-REST3-RPCپروژه gRPC درواقع یک فریم ورک RPC است که بسیار سریع و قدرتمند است که توسط گوگل و همکاری چندتا کمپانی دیگر توسعه داده شده است( حرف g اول کلمه gRPC مخفف Google است).پروژه gRPC برای سریالیز کردن پیام ها و رد و بدل کردن آنها از ProtocolBufferاستفاده میکند. فرمت دیتاها در ProtocolBuffer به صورت باینری می باشد که باعث می شود حجم دیتاها کاهش یابد و در نتیجه ترافیک کمتری مصرف شود.ویژگی های کلیدی gRPC :-ارتباط باینری-ارتباط بر پایه قرارداد-امن بودن به صورت پیش فرض(الزام به استفاده از HTTP/2)- امکان استریم کردن در Client و Serverآیا با به وجود آمدن gRPC به این معنی است که REST دیگر استفاده نخواهد شد؟با وجود ویژگی های خیلی خوب gRPC نظیر سرعت-امنیت-استریم و... نقاط ضعفی هم دارد مانند اینکه به علت استفاده پیش فرض از HTTP/2 خیلی از مرورگر ها به علت قدیمی بودن امکان ارتباط بر قرار کردن در این پروتکل را ندارند و همچنین به علت اینکه contract-based می باشد برای هر تغییر کوچکی باید هم client و هم server آپدیت شوند تا همچنان ارتباط برقرار بماند.پس به این معنیه که جایگزین روش های دیگر API نویسی نمی شود.می توانیم نتیجه بگیریم برای کاری که می خواهیم انجام بدهیم باید ابزار مناسب خود را پیدا کنیم.مثلا می توان API نویسی را به این صورت دسته بندی کرد:1-RESTمناسب عملیات های ساده CRUD و به طور کل وب اپ ها.2-GraphQLمناسب پروژه هایی که کوئری و دیتاست های زیادی دارد.3-gRPCمناسب پروژه هایی که منابع کم دارند یا نیاز به استریم کردن دارند و یا نیاز به سرعت و امنیت بیشتری دارند.این پروتکل شما را به طول کامل از زبان مستقل میکند به عنوان مثال ارتباط برنامه ای به زبان c# را با برنامه ای به زبان Java به سادگی مهیا می کند.از این رو بسیار مناسب معماری Microservice می باشد.منابع:-Pluralsight-Microsoftاستاد : دکتر مریم حاجی اسمعیلی. دکترای علوم کامپیوتر از دانشگاه کینگستون لندنDr.Maryam HajiesmaeiliPhD of computer science from Kingston university of London رامبد سواحلی مقدم رامبد سواحلی مقدم Mon, 18 Apr 2022 23:28:08 +0430