من به سفر خود برای آشنایی بیشتر با API های HTTP با خواندن مطالب مرتبط ادامه می دهم RFC ها. این بار، به پیشنهاد فرمت پاسخ بررسی سلامت برای APIهای HTTP را خواندم استفانو فاگو. در این پست، می‌خواهم مطالبم را خلاصه کنم.
توجه داشته باشید که یک پیش نویس است. علاوه بر این، نزدیک به دو سال است که غیرفعال بوده و بنابراین، به طور خودکار منقضی شده است. با این حال، این نزدیکترین به یک مشخصات در بررسی های بهداشتی است و بنابراین سزاوار عشق است.
تجسم داده های نمونه
با وجود اینکه زیاد خوانده نشده است، اما کمی «خشک» است. خوشبختانه، مشخصات یک نمونه JSON را ارائه می دهد. من آن را در PlantUML کپی کردم، و از قبل، یک نمایش بصری از آن را نشان می دهد:
بیایید نگاهی به ساختار پیشنهادی عنصر به عنصر داشته باشیم.
شی ریشه
در ساده ترین حالت، پاسخ یک شی JSON با یک اجباری است status ویژگی:
ارزش ها می توانند:
-
passبرای وضعیت سالم مقدار نیز می تواند باشدok(برای NodeJS) وup(برای Spring Boot) برای در نظر گرفتن کتابخانه های موجود بررسی سلامت. کد وضعیت HTTP باید در محدوده 2xx تا 3xx باشد. -
warnبرای وضعیت سالم اما با نگرانی با محدوده وضعیت HTTP یکسان. -
failبرای نشان دادن وضعیت ناسالم مقادیر جایگزین ممکن عبارتند ازerror(NodeJS) وdown(چکمه بهاره). کد وضعیت HTTP باید در محدوده 4xx تا 5xx باشد.
می توان اضافه کرد اختیاری ارزش های:
-
version: عمومی نسخه سرویس -
releaseId: نسخه داخلی سرویس. به عنوان مثالversionبرای تغییرات ناسازگار افزایش می یابد، در حالی کهreleaseIdمی تواند هش commit یا یک نسخه معنایی باشد. -
serviceId: شناسه منحصر به فرد سرویس -
description: خود توضیحی -
notes: آرایه ای از یادداشت های بدون ساختار -
output: پیغام خطای ساده در صورت وجودpassیاwarn. فیلد باید خالی بماندpass.
این links اشیاء
این links شی از جفت شی تشکیل شده است. مقادیر URI هستند، در حالی که کلیدها می توانند URI یا رایج/ثبت شده باشند: برای مقادیر مشترک به RFC5988 مراجعه کنید. به عنوان مثال، self.
این checks اشیاء
کلیدهای checks اشیاء از دو عبارت تشکیل شده اند که با دو نقطه، نام جزء و نام اندازه گیری از هم جدا شده اند. مورد دوم می تواند یکی از این موارد باشد:
- یک مقدار از پیش تعریف شده:
utilization،responseTime،connections، یاuptime - یک اصطلاح استاندارد از یک منبع شناخته شده، به عنوان مثال، IANA ، microformat.org و غیره
- یک URI
مقادیر از یکی از کلیدهای زیر تشکیل شده است:
-
componentId: شناسه منحصر به فرد این کامپوننت componentType:- یک مقدار از پیش تعریف شده،
component،datastore، یاsystem - یک اصطلاح استاندارد از یک منبع شناخته شده، به عنوان مثال، IANA ، microformat.org و غیره
- یک URI
- یک مقدار از پیش تعریف شده،
observedValue: هر مقدار JSON معتبرobservedUnit: واحد اندازه گیریstatus: به عنوان وضعیت شی والد، اما فقط برای این جزءaffectedEndpoints: اگر جزء نباشدpass، تمام نقاط پایانی تحت تأثیر را فهرست می کندtime: تاریخ-زمان در قالب ISO8601 مشاهدهoutput: به عنوان خروجی شی والد، اما فقط برای این جزءlinks: بخش قبل را ببینیدهر مقدار غیر استاندارد دیگر
من سعی کردم موارد بالا را با Spring Boot با استفاده از یک سفارشی پیاده سازی کنم HealthIndicator. در اینجا بهترین چیزی است که می توانم به ذهنم برسم:
ساختار فعلی پاسخ JSON باید (به راحتی؟) قابل تنظیم باشد. شما باید نقطه پایانی خود را ایجاد کنید. امیدوارم تیم Spring Boot گزینه ای را برای ایجاد یک ساختار سازگار فراهم کند.
نتیجه
پیش نویس Healthcheck IETF یک ابتکار عالی برای استانداردسازی چک های سلامت در سراسر صنعت است. این به ابزارهای نظارتی اجازه می دهد تا بر وضعیت HTTP و بدنه پاسخ بدون پیکربندی ad-hoc در هر سرویس تکیه کنند.
متأسفانه، پیش نویس به دلیل عدم فعالیت منقضی شده است. با این حال، من دوست دارم دوباره آن را ببینم.
فراتر رفتن:
در ابتدا در A Java Geek در 28 می منتشر شدهفتم، 2023
