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

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

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