💎 معرفی GraphQL و استفاده ازش 💎

اگه تا حالا اسم GraphQL به گوشتون خورده ولی نمی‌دونستید دقیقاً چیه و چه کاربردی داره، امروز قراره باهم برسیش کنیم و بفهمیم چرا این روزها انقدر محبوب شده🌟

حالا GraphQL چیه؟ 🤔

خب GraphQL یه زبان کوئری برای API هاست که توسط فیسبوک توی سال ۲۰۱۵ معرفی شد. این تکنولوژی به شما اجازه می‌ده که دقیقاً همون داده‌هایی که نیاز دارین رو از سرور درخواست کنین. مهم‌ترین ویژگی GraphQL اینه که به جای دریافت یه ساختار ثابت از اطلاعات، می‌تونین مشخص کنین چه داده‌هایی رو دقیقاً می‌خواین و چه داده‌هایی رو نمی‌خواین.

به زبان ساده، GraphQL به شما کنترل بیشتری روی داده‌هایی که از API می‌گیرین می‌ده. 🌍

چرا از GraphQL استفاده کنیم؟ 🤷‍♂️

1⃣ دریافت داده‌های دقیق 🎯

یکی از بزرگ‌ترین مشکلاتی که معماری‌های سنتی API دارن اینه که گاهی داده‌هایی که لازم نداریم رو هم به ما برمی‌گردونن. GraphQL این مشکل رو حل کرده. شما توی GraphQL می‌تونین کاملاً مشخص کنین که چه فیلدهایی از داده‌ها رو نیاز دارین و فقط همون‌ها رو از سرور بگیرین.

مثال: فرض کنین می‌خواین فقط اسم و ایمیل کاربر رو از API بگیرین. کوئری GraphQL می‌تونه این‌طوری باشه:

{
  user(id: 1) {
    name
    email
  }
}

و پاسخ هم دقیقاً همون چیزی خواهد بود که درخواست کردین:

{
  "data": {
    "user": {
      "name": "Ali",
      "email": "[email protected]"
    }
  }
}

این یعنی فقط همون داده‌هایی که خواستین برمی‌گرده و هیچ اطلاعات اضافه‌ای به شما داده نمی‌شه.

2⃣ بهینه‌سازی درخواست‌ها 🚀

یکی از مشکلات رایج توی APIهای سنتی، تعداد زیاد درخواست‌ها (requests) برای گرفتن اطلاعات مختلفه. GraphQL به شما این امکان رو می‌ده که با یک درخواست همه داده‌های مورد نیازتون رو بگیرین. شما می‌تونین توی یه کوئری، اطلاعات از چندین منبع مختلف رو دریافت کنین و نیازی به ارسال چندین درخواست نیست.

مثال: فرض کنین می‌خواین اطلاعات کاربر، لیست سفارش‌ها و محصولاتی که خریده رو بگیرین. کوئری GraphQL به‌راحتی این اطلاعات رو توی یک درخواست برمی‌گردونه:

{
  user(id: 1) {
    name
    orders {
      id
      product {
        name
        price
      }
    }
  }
}

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

3⃣ پشتیبانی از تکامل تدریجی 💻

یکی از ویژگی‌های مهم GraphQL اینه که به‌راحتی می‌تونین API خودتون رو بدون اینکه تغییرات بزرگی به وجود بیارین، توسعه بدین. این یعنی می‌تونین فیلدهای جدیدی به داده‌هاتون اضافه کنین بدون اینکه نیاز به تغییر توی کل API داشته باشین. این قابلیت، انعطاف‌پذیری زیادی توی توسعه و نگهداری API داره.

4⃣ مستندات خودکار 📚

یکی دیگه از ویژگی‌های عالی GraphQL، مستندسازی خودکارشه. از اونجایی که GraphQL یک سیستم تایپینگ قوی داره، می‌تونه به‌صورت خودکار مستندات API رو بسازه و شما همیشه مستندات به‌روز و کاملی دارین. این خیلی به درد تیم‌های توسعه‌ای می‌خوره که از پروژه‌های مختلف استفاده می‌کنن و همیشه باید به مستندات دقیق دسترسی داشته باشن.

کاربردهای واقعی GraphQL 📈

1⃣ فیسبوک: همونطور که گفته شد، GraphQL توسط فیسبوک ایجاد شد و فیسبوک همچنان از اون توی بسیاری از محصولات خودش استفاده می‌کنه، مثل اپلیکیشن فیسبوک و اینستاگرام.

2⃣ گیت هاب: GraphQL به عنوان یک API اصلی توی GitHub استفاده می‌شه و شما می‌تونین از طریق GraphQL به اطلاعات پروژه‌ها و کاربران GitHub دسترسی داشته باشین.

3⃣ شاپیفای (Shopify): توی پلتفرم Shopify، از GraphQL برای بهینه‌سازی و سرعت بخشیدن به APIها استفاده می‌شه.

حچطور از GraphQL استفاده کنیم؟ 🛠️

راه‌اندازی GraphQL توی پروژه‌های مختلف واقعاً ساده‌ست. توی پلتفرم‌هایی مثل Django یا Node.js، پکیج‌ها و کتابخونه‌های آماده‌ای وجود دارن که شما می‌تونین سریعاً ازشون استفاده کنین.

برای مثال، در Django، شما می‌تونین با استفاده از Graphene-Django خیلی راحت یه API GraphQL بسازین.

توجه ⚠️:
این فقط یه مثال ساده برای شروع هستش:

pip install graphene-django

و بعد توی پروژه‌تون:

import graphene

class Query(graphene.ObjectType):
    hello = graphene.String()

    def resolve_hello(self, info):
        return "Hello, world!"

schema = graphene.Schema(query=Query)

این کد یه کوئری ساده به اسم hello می‌سازه که وقتی از GraphQL درخواست بشه، مقدار "Hello, world!" رو برمی‌گردونه.

جمع‌بندی 🎯 
فهمیدیم GraphQL با انعطاف‌پذیری و سرعت بالا، باعث می‌شه که APIهای بهتری طراحی کنین و تجربه کاربری بهتری ارائه بدین.

امید وارم مفید بوده باشه :)

#django #api #graphql

@ninja_learn_ir

چرا نباید لاجیک پروژه رو تو سریالایزرهای DRF پیاده‌سازی کنیم؟ 🚫

یه موضوع مهم هست که چرا نباید لاجیک پروژه‌مون رو تو سریالایزرها پیاده‌سازی کنیم؟ خیلی از افرادی که میشناسم متاسفانه اینکارو میکنن (پیاده سازی لاجیک توی سریالایزر ها) اگه شماهم حزو این دسته افراد هستید این پست براتون مناسبه

اول از همه سریالایزر تو DRF چیه؟

سریالایزرها تو DRF مسئول تبدیل داده‌ها بین فرمت‌های مختلف (مثل JSON و مدل‌های Django) هستن. کارشون اینه که داده‌ها رو بگیرن، اعتبارسنجی (validation) کنن و به شکل مناسب تحویل بدن. مثلاً یه مدل User رو به JSON تبدیل می‌کنن یا برعکس. تا اینجا همه‌چیز اوکیه، ولی مشکل از جایی شروع می‌شه که بخوایم لاجیک اصلی پروژه رو تو همین سریالایزرها پیاده سازی کنیم.

🚫 چرا این کار بده؟
بعضی‌ها عادت دارن تو متدهای سریالایزر (مثل to_representation یا validate) لاجیک‌های پیچیده بنویسن، مثلاً محاسبات، فیلتر کردن داده‌ها یا حتی آپدیت دیتابیس. اما این کارا چندتا مشکل بزرگ به وجود میاره

1⃣ نقض اصل Single Responsibility:
سریالایزرها برای تبدیل و اعتبارسنجی داده‌ها طراحی شدن، نه برای مدیریت لاجیک پروژه.
وقتی لاجیک رو اونجا می‌نویسین، کدتون از یه سریالایزر ساده تبدیل میشه به سریالایزر خیلی گنده که بعداً نگهداریش سخت می‌شه.

2⃣ کاهش Readability و Testability:
اگه لاجیک تو سریالایزر باشه، پیدا کردنش تو پروژه سخت‌تره و تست کردنش هم پیچیده می‌شه. مثلاً برای تست یه محاسبه، باید کل سریالایزر رو تست کنین، نه فقط اون لاجیک خاص.

3⃣ مشکلات Scalability:
تو پروژه‌های بزرگ، وقتی لاجیک‌ها تو سریالایزرها پخش بشن، دیگه نمی‌تونین به راحتی تغییرشون بدین یا جابه‌جاشون کنین. یه تغییر کوچیک تو لاجیک ممکنه کل API رو به هم بریزه.

4⃣ وابستگی بیش از حد:
سریالایزرها به مدل‌ها و داده‌ها وابسته‌ ان. اگه لاجیک پروژه رو اونجا بذارین، هر تغییری تو مدل‌ها یا ساختار داده‌ها می‌تونه لاجیک‌تون رو خراب کنه.

5⃣ سخت شدن دیباگ:
وقتی یه باگ پیش میاد، نمی‌دونین مشکل از تبدیل داده‌ست یا از لاجیک پروژه، چون همه‌چیز قاطی شده.

سخن اخر 🗣
پیاده‌سازی لاجیک پروژه تو سریالایزرهای DRF مثل اینه که بخوای با چاقو سوپ بخوری؛ می‌شه، ولی چرا؟! سریالایزرها برای تبدیل و اعتبارسنجی داده‌ها طراحی شدن، نه برای نگه داشتن لاجیک پیچیده. با انتقال لاجیک به مدل‌ها یا سرویس‌ها، کدتون تمیزتر، قابل‌نگهداری‌تر و حرفه‌ای‌تر می‌شه. دفعه بعد که خواستین تو سریالایزر لاجیک بنویسین، یه لحظه وایسید و بگین: اینجا جای این کارا نیست 😊

#️⃣ #backend #drf #django #api

➖➖➖➖➖➖➖➖➖

🥷 CHANNEL | GROUP

مدیریت خطا و پیام‌ها

تو هر پروژه‌ای خطا اجتناب‌ناپذیره، مهم اینه چطور باهاش برخورد کنیم. اگه پیام‌ها درست مدیریت نشن، هم کاربر گیج میشه، هم فرانت سخت‌تر می‌تونه هندل کنه.

چند تا نکته به عنوان best practice:

- برای خطاها یه ساختار مشخص داشته باش تا فرانت بتونه راحت تشخیص بده با چه شرایطی طرفه.
- پیام برای کاربر باید ساده و قابل فهم باشه، نه پر از اصطلاحات فنی.
- جزئیات فنی و لاگ‌ها رو نگه دار برای بک‌اند و تیم فنی، نه برای کاربر.
- همیشه از پیام‌های عمومی برای خطاهای پیش‌بینی‌نشده استفاده کن (مثل "مشکلی پیش اومده، دوباره امتحان کن").
- خطاها رو دسته‌بندی کن (مثلاً خطای کاربر، خطای سرور، خطای دسترسی) تا بتونی راحت‌تر مدیریت کنی.

از مهمترین شرایطی که باید یک توسعه دهنده بک اند در API لحاظ کنه Custom Exception Handler هستش تا بتونه خطا ها رو با یک فرمت مناسب و یک دست پاسخ بده و این موضوع بر اساس کمپانی های مختلف متفاوت هستش ولی می تونین الگوی مناسبی رو از درونشون پیدا کنین.

مثلا داشتن کلید error در پیام و همچنین در ادامه status کد خطای اتفاق افتاده و همچنین جدا سازی detail و message که در یکی خطای توسعه و دیگری پیام قابل نمایش به کاربر قرار میگیره. در بعضی شرایط ممکنه حتی timestamp و اطلاعات بیشتری هم درج بشه مثلا code یا type که ممکنه شماره خطای خاص و یا کلید واژه مربوطه برای ردگیری خطای سریعتر باشه.

دیده میشه گاهی وقتا آدرس و یا حتی ورودی ها رو هم در بعضی سرویس ها نشون میدن که به نظرم جاش توی ریسپانس نیست و باید توی لاگ ها باشه و با این حال بعضی سرویس ها ارائه میدن.


نمونه Response مناسب برای خطا ها

{
  "error": {
    "status": 404,
    "code": "OBJECT_NOT_FOUND",
    "message": "آبجکت مورد نظر یافت نشد",
    "detail": "Object matching query does not exist.",
    "timestamp": "2025-10-03T12:30:45Z"
  }
}

رفرنس ها:
- https://zuplo.com/learning-center/best-practices-for-api-error-handling
- https://api7.ai/learning-center/api-101/error-handling-apis
- https://nordicapis.com/5-real-world-examples-of-great-api-error-messages/
- https://www.baeldung.com/rest-api-error-handling-best-practices


📢 @thealibigdeli_channel

#api_design
#api

🔵 عنوان مقاله
JWT Authentication in Go with Gin

🟢 خلاصه مقاله:
این مقاله با رویکردی عملی نشان می‌دهد چگونه احراز هویت مبتنی بر JWT را در یک سرویس Go با فریم‌ورک Gin پیاده‌سازی کنیم؛ هدف نمونه، کار با Vonage است اما الگوها در هر پروژه API‌محور قابل استفاده‌اند. نویسنده، Benjamin Aronov (Vonage)، ابتدا مزایای JWT و مفاهیم ادعاها، الگوریتم‌های امضا و تفکیک توکن‌های دسترسی و نوسازی را توضیح می‌دهد. سپس ساختار پیاده‌سازی را تشریح می‌کند: صدور توکن امن پس از تأیید اعتبار، میان‌افزار Gin برای اعتبارسنجی و تزریق کانتکست کاربر، محافظت از مسیرها، مدیریت خطاها و نگهداری کلیدها در متغیرهای محیطی. بخش امنیت بر انقضای کوتاه توکن دسترسی، چرخش Refresh Token، جلوگیری از سوءاستفاده، استفاده از HTTPS، ملاحظات CORS و محدودسازی نرخ و نیز لاگ‌گذاری و چرخش کلیدها در محیط تولید تأکید دارد. در نهایت نشان می‌دهد چگونه با توکن‌های کوتاه‌عمر و محدود به سطح دسترسی، تعاملات با Vonage (مانند پیام، صوت یا ویدئو) را ایمن کنیم. نتیجه، لایه احراز هویت منعطفی در Go و Gin است که فراتر از Vonage هم قابل استفاده است.

#Go #Gin #JWT #Authentication #Security #Golang #API #Vonage

🟣لینک مقاله:
https://golangweekly.com/link/175981/web

➖➖➖➖➖➖➖➖
👑 @gopher_academy

🔵 عنوان مقاله
go-rest-api-example: Template for an Enterprise-Ready REST API Microservice

🟢 خلاصه مقاله:
پروژه go-rest-api-example یک قالب آماده برای ساخت Microserviceهای REST API در سطح Enterprise است. این Boilerplate با هدف راه‌اندازی سریع و استاندارد یک سرویس تولیدی ارائه شده و با نگه‌داری منظم به‌روز می‌شود. نسخه این هفته با Go 1 یکپارچه شده تا با ابزارها و جریان‌های کاری فعلی سازگار باشد و پایه‌ای پایدار برای توسعه فراهم کند.

#Go #Golang #RESTAPI #Microservices #Boilerplate #Backend #API #SoftwareEngineering

🟣لینک مقاله:
https://golangweekly.com/link/176914/web

➖➖➖➖➖➖➖➖
👑 @gopher_academy