API و بک‌اند

• ۰۱

  وب‌سایت، اپلیکیشن و پنل مدیریتتان همه به داده‌های یکسانی نیاز دارند.

• ۰۲

  بک‌اند فعلی کند و شکننده است یا نگهداری‌اش بیش از حد گران تمام می‌شود.

• ۰۳

  به سرویس‌های بیرونی وابسته‌اید که به روش‌های خلاقانه از کار می‌افتند.

• ۰۴

  تیمتان به APIای نیاز دارد که بتواند بفهمد و گسترشش بدهد.

1. D/۰۱

   API مستند

   قرارداد را پیش از کد می‌نویسیم: هر endpoint، هر فیلد و هر خطا، با OpenAPI یا protobuf. تیم وب، اپ و شرکای شما از روز اول می‌توانند بر اساسش کار کنند، و مستندات از همان فایل ساخته می‌شود، پس همیشه با کاری که سرور واقعاً می‌کند یکی است.

   شامل

   • قرارداد کامل با OpenAPI 3 یا protobuf
   • یک نمونه‌ی کارا برای هر endpoint
   • کد خطاهایی که می‌گویند چه اشتباه شد و چه باید کرد
   • قواعد نسخه‌بندی، تا تغییرات کلاینت‌های قدیمی را از کار نیندازد

   POST /v1/orders · ثبت سفارش

   Shop API · v1.4

   درخواست

   • items: فهرستی از { sku, qty }، دست‌کم یک قلم.
   • هدر Idempotency-Key: یک کلید هرگز دو سفارش نمی‌سازد.

   پاسخ‌ها

   • 201 Created: سفارش، همراه با هدر Location.
   • 409 out_of_stock: کدام SKU، و چند عدد باقی مانده.
   • 422 invalid_items: برای هر فیلد یک خطا.

   خطاها

   • بدنه‌ی همه‌ی خطاها یک شکل دارد: { code, message, field }.

   احراز هویت

   • توکن Bearer با دسترسی orders:write.

2. D/۰۲

   داده‌ی درست

   جدول‌های PostgreSQL را بر اساس کوئری‌هایی طراحی می‌کنیم که محصول شما واقعاً اجرا می‌کند، با قیدهایی که داده‌ی نادرست را از همان ابتدا راه نمی‌دهند. هر تغییر یک مایگریشن نسخه‌دار است، پس اسکیمای محیط واقعی همیشه همانی است که در مخزن کد هست.

   شامل

   • اسکیما با کلیدها، قیدها و توضیح هر ستون
   • مایگریشن‌های نسخه‌دار که رو به جلو و عقب اجرا می‌شوند
   • ایندکس‌هایی که با پلن واقعی کوئری‌ها سنجیده شده‌اند
   • پشتیبان‌گیری، و بازیابی‌ای که آزموده شده است

3. D/۰۳

   کارهای پس‌زمینه

   هر کار زمان‌بر یا ناپایدار از مسیر درخواست بیرون می‌رود: فرستادن رسید، همگام‌سازی موجودی، ساختن گزارش. کارها از یک صف می‌گذرند، کار ناموفق با فاصله‌ی فزاینده دوباره اجرا می‌شود، و کاری که مدام شکست می‌خورد جایی می‌ماند که حتماً به چشم کسی بیاید.

   شامل

   • صف و workerهایی به اندازه‌ی بار شما
   • کارهای زمان‌بندی‌شده در خود کد، نه پنهان در یک crontab
   • تلاش مجدد با فاصله‌ی فزاینده، و کارهایی که تکرارشان بی‌خطر است
   • صف پیام‌های ناموفق، با هشدار وقتی پر می‌شود

4. D/۰۴

   یکپارچه‌سازی

   دور هر سرویس بیرونی یک لایه‌ی نازک می‌کشیم، با مهلت، تلاش مجدد و راه جایگزین مخصوص خودش. روزی که درگاه پرداخت یا سامانه‌ی پیامک به مشکل می‌خورد، سفارش‌هایتان به‌جای از دست رفتن منتظر می‌مانند یا از مسیر دیگری می‌روند؛ و می‌توانید سرویس‌دهنده را عوض کنید بی‌آن‌که به بقیه‌ی کد دست بزنید.

   شامل

   • یک آداپتور کوچک برای هر سرویس‌دهنده، پشت یک رابط واحد
   • مهلت، تلاش مجدد و راه جایگزین برای هر کدام
   • پردازش وب‌هوک با بررسی امضا و نادیده گرفتن تکراری‌ها
   • سرویس‌دهنده‌های ساختگی برای تست، تا هیچ تستی تصادفی سراغ سرویس واقعی نرود

   سرویس	مهلت	تلاش مجدد	وقتی از کار بیفتد
   پرداخت	۵ ثانیه	۳ بار، با فاصله	سفارش در انتظار می‌ماند و یک کار پس‌زمینه دوباره بررسی‌اش می‌کند
   پیامک	۳ ثانیه	۵ بار، با فاصله	به سرویس‌دهنده‌ی دوم می‌رود
   ایمیل	۱۰ ثانیه	۵ بار، با فاصله	در صف می‌ماند و سفارش معطل نمی‌شود
   نقشه	۲ ثانیه	۱ بار	نتیجه‌ی ذخیره‌شده، وگرنه فقط کد پستی
   ارسال	۸ ثانیه	۳ بار	برچسب بعداً صادر می‌شود و به مشتری خبر می‌دهیم

5. D/۰۵

   مشاهده‌پذیری

   هر درخواست لاگ ساخت‌یافته، متریک و یک trace به جا می‌گذارد که می‌شود آن را میان سرویس‌ها دنبال کرد. داشبوردها همان چند عددی را نشان می‌دهند که مهم است، و هشدارها روی چیزی به صدا درمی‌آیند که کاربر حس می‌کند، مثل کند شدن پرداخت یا طولانی شدن صف.

   شامل

   • لاگ JSON ساخت‌یافته با شناسه‌ی درخواست
   • متریک و trace با OpenTelemetry
   • داشبورد تأخیر، خطا، ترافیک و صف‌ها
   • هشدارهایی با یک یادداشت کوتاه درباره‌ی اولین چیزی که باید بررسی شود

   تأخیر p95

   ۴۲ ms

   هدف: زیر ۱۵۰ میلی‌ثانیه

   نرخ خطا

   ۰٫۰۳٪

   خطاهای 5xx، ۲۴ ساعت گذشته

   درخواست در ثانیه

   ۲۸۰

   اوج، عصر جمعه

   تأخیر صف

   ۱٫۸ s

   هشدار بالای ۳۰ ثانیه

6. D/۰۶

   تست و CI

   تست‌های واحد منطق برنامه را پوشش می‌دهند، تست‌های یکپارچگی روی یک PostgreSQL واقعی داخل کانتینر اجرا می‌شوند، و هر دو با هر push اجرا می‌شوند. تغییری که تستی را بشکند، از linter رد نشود یا مایگریشنی را جا بیندازد، ادغام نمی‌شود.

   شامل

   • تست واحد برای قواعد کسب‌وکار و حالت‌های مرزی
   • تست یکپارچگی روی پایگاه داده و صف واقعی
   • پایپ‌لاینی که lint، تست و ساخت کانتینر را انجام می‌دهد
   • تشخیص race و گزارش پوشش در هر اجرا

   $ go vet ./... && staticcheck ./...

   ✓ no issues

   $ go test -race -cover ./...

   ✓ 412 passed · coverage 81%

   $ go test -tags=integration ./internal/store

   × TestReserveStock: stock went below zero

   ! merge blocked until the pipeline is green

1. ۰۱

   اول قرارداد

   پیش از نوشتن کد، API را همراه با کسانی طراحی می‌کنیم که قرار است از آن استفاده کنند.

2. ۰۲

   ساخت برش‌به‌برش

   هر برش از پایگاه داده تا endpoint کامل کار می‌کند و زود مستقر می‌شود.

3. ۰۳

   تست بار و خرابی

   آن را از ترافیک مورد انتظار فراتر می‌بریم و وابستگی‌هایش را از زیر پایش می‌کشیم.

4. ۰۴

   تحویل

   راهنمای اجرا، داشبوردها و یک جلسه‌ی مرور، تا تیمتان با خیال راحت آن را در دست بگیرد.

ساخت یک بک‌اند تازه معمولاً هشت تا دوازده هفته طول می‌کشد و اولین برش کارا ظرف سه هفته بالا می‌آید. هر هفته آن را روی سرور آزمایشی در حال کار می‌بینید، پس پیشرفت واقعی را خودتان می‌سنجید، نه از روی یک گزارش وضعیت.

1. هفته‌ی ۱

   قرارداد API، نوشته‌شده همراه با کسانی که از آن استفاده می‌کنند، و مدل داده‌ی پشتش.

2. هفته‌ی ۲ و ۳

   اولین برش از پایگاه داده تا endpoint، مستقر روی سرور آزمایشی، همراه با CI.

3. هفته‌ی ۴ تا ۸

   باقی برش‌ها، یکپارچه‌سازی‌ها و کارهای پس‌زمینه، هر کدام همان وقت که کار کرد تحویل می‌شود.

4. هفته‌ی ۹ و ۱۰

   تست بار و خرابی، و بعد تنظیم داشبوردها و هشدارها بر اساس آنچه یاد گرفتیم.

5. هفته‌ی ۱۱ و ۱۲

   راه‌اندازی، راهنمای اجرا و یک جلسه‌ی مرور با تیم شما.

• کد

  کل مخزن کد، با تاریخچه‌اش، در حساب Git خود شما.

• قرارداد API

  فایل‌های OpenAPI یا protobuf، با مستندات و کتابخانه‌های کلاینتی که از آن‌ها ساخته می‌شود.

• مایگریشن‌های پایگاه داده

  هر تغییر اسکیما به شکل یک فایل نسخه‌دار که می‌تواند پایگاه داده را از صفر بسازد.

• داشبوردها و هشدارها

  به شکل کد، تا همراه سرویس به هر محیطی منتقل شوند.

• راهنماهای اجرا

  این‌که با هر هشدار چه باید کرد، و روش استقرار، بازگشت به نسخه‌ی قبل و بازیابی.

• یک ماه پشتیبانی پس از راه‌اندازی

  تا تیمتان جا بیفتد، برای سؤال‌ها و اصلاح‌ها در دسترسیم.

• Go
• PostgreSQL
• Redis
• NATS
• gRPC
• OpenAPI
• OpenTelemetry
• Docker

• معماری سیستم

  تصمیم‌هایی که تکلیف بقیه‌ی کارها را روشن می‌کنند.

  بیشتر بخوانید →

• پلتفرم‌های وب

  سریع برای همه، به هر زبانی.

  بیشتر بخوانید →

• زیرساخت و DevOps

  سرپا می‌ماند، حتی وقتی چیزی از کار می‌افتد.

  بیشتر بخوانید →