HTTP، Health و OpenAPI زیرساخت Backend
مرز HTTP با net/http و http.ServeMux پیادهسازی میشود. OpenAPI 3.1 قرارداد عمومی و Reviewشدنی API است، اما Route، DTO، Decode، Validation و Encode بهصورت دستی و Testشده نوشته میشوند.
مالکیت
internal/platform/httpserver مالک Server، Middleware Chain، پاسخ عمومی 404 و 405 و Routeهای سیستمی است. internal/platform/httpx Primitiveهای مشترک Transport مانند JSON، Problem Details و Client IP تاییدشده را نگه میدارد. Feature فقط Handler استاندارد و Route Registrar خود را ارائه میکند.
Concernهای سراسری
- Request ID تولیدشده یا اعتبارسنجیشده سمت Server؛
- Panic Recovery بدون افشای Stack؛
- Security Header و
Cache-Controlمناسب؛ - محدودیت Body و Timeout؛
- Structured Logging با Route Template کمCardinality؛
- Problem Details امن و یکسان برای خطاهای عمومی.
Concern بالا نباید در Feature دوباره پیادهسازی شود. Domain Error در HTTP Adapter همان Feature به Status و Code پایدار Map میشود.
مهلت درخواست بهصورت مرکزی اعمال میشود. Composition میتواند برای یک Route ثبتشده در همان http.ServeMux مهلت اختصاصی بدهد؛ تنظیم فعلی فقط برای Import Excel است. این مهلت شامل انتظار در صف و پردازش است، Context والد و لغو Client را حفظ میکند و deadline خواندن و نوشتن همان درخواست را هماهنگ میکند. مهلت سایر Routeها تغییر نمیکند.
Routeهای سیستمی
| Method | Path | معنا | Dependency |
|---|---|---|---|
GET |
/ |
Metadata Build | ندارد |
GET |
/health |
سازگاری و توان پاسخ HTTP | ندارد |
GET |
/livez |
زندهبودن Process | ندارد |
GET |
/readyz |
آمادگی سرویس | PostgreSQL |
GET |
/openapi.yaml |
قرارداد OpenAPI | ندارد |
GET |
/docs/ |
Swagger UI با Asset داخلی | OpenAPI Embedded |
/health و /livez جای /readyz را نمیگیرند. قطع PostgreSQL باید Readiness را با 503 ناموفق کند ولی Liveness را از کار نیندازد.
قرارداد و Swagger
فایلهای backend/api/openapi/*.yaml منبع حقیقت Schema هستند. Swagger UI از Asset Embedشده استفاده میکند تا Client در شبکه ضعیف برای نمایش Contract به CDN وابسته نباشد. تغییر Contract و Behavior باید در یک Change Set و با Contract Test انجام شود.
آزمون لازم
- مسیر موفق، Method نامعتبر، Path ناموجود و Panic؛
- Headerهای امنیتی و Request ID روی موفق و خطا؛
- رد Body بزرگ، JSON نامعتبر و Media Type نامعتبر؛
- تفاوت Liveness و Readiness در قطع Database؛
- نمایش Swagger و دریافت OpenAPI بدون Network بیرونی.
قواعد کامل در قرارداد API و اتصال ضعیف قرار دارد.