GraphQL یا REST؟ مقایسه معماری، امنیت و عملکرد API

GraphQL یا REST؟ پاسخ درست به شکل داده، تعداد Clientها، نیاز Cache، سطح کنترل مصرف‌کننده و توان عملیاتی تیم بستگی دارد. GraphQL ذاتاً سریع‌تر و REST ذاتاً ساده‌تر نیست. هر دو می‌توانند API امن، مقیاس‌پذیر و قابل نگهداری بسازند یا با طراحی ضعیف به N+۱، قرارداد شکننده و هزینه عملیاتی بالا برسند.

REST معمولاً منابع را با URL و معنای HTTP مدل می‌کند. GraphQL یک Schema تایپ‌شده و زبان Query می‌دهد تا Client فیلدهای موردنیاز را انتخاب کند. تفاوت فقط تعداد Endpoint نیست؛ مالکیت Shape پاسخ، روش Cache، Evolution و کنترل هزینه Query تغییر می‌کند.

این راهنما معماری، عملکرد، امنیت، Versioning، Caching و سناریوهای انتخاب GraphQL، REST یا مدل ترکیبی را با مثال عملی مقایسه می‌کند.

REST API چیست؟

REST یک سبک معماری برای سیستم‌های توزیع‌شده است، نه یک Protocol یا فرمت اجباری. APIهای وب که «REST API» نامیده می‌شوند معمولاً از Resource، URI، Methodهای HTTP، Status Code، Header و Representation مانند JSON استفاده می‌کنند.

نمونه:

GET /v1/products/42
GET /v1/products/42/reviews?limit=10
POST /v1/orders
PATCH /v1/orders/981

یک REST API خوب معنای Method را رعایت می‌کند، Cache را آگاهانه تنظیم می‌کند و Resource را از عملیات داخلی Database جدا نگه می‌دارد. داشتن URLهای متعدد به‌تنهایی RESTful بودن را ثابت نمی‌کند.

GraphQL چیست؟

GraphQL یک زبان Query و Execution System برای قابلیت‌هایی است که در Schema تعریف می‌شوند. مرجع نسخه‌های GraphQL Specification انتشار پایدار سپتامبر ۲۰۲۵ و Working Draftهای بعدی را فهرست می‌کند.

GraphQL Database، ORM یا Transport نیست. می‌تواند روی SQL، NoSQL، REST Service، Queue یا چند منبع داده Resolver اجرا کند. HTTP رایج‌ترین Transport است، اما Specification اصلی GraphQL جزئیات HTTP را الزام نمی‌کند.

query ProductPage($id: ID!) {
  product(id: $id) {
    id
    name
    price
    inventoryStatus
    reviews(first: 10) {
      nodes {
        rating
        summary
      }
    }
  }
}

Client Shape پاسخ را از مجموعه فیلدهای مجاز Schema انتخاب می‌کند. این اختیار باید با Authorization، Pagination و Query Cost کنترل شود.

مقایسه سریع GraphQL و REST

GraphQL چگونه Over-fetching را کم می‌کند؟

Client می‌تواند فقط فیلدهای لازم را بخواهد. صفحه فهرست شاید id، name و thumbnail بخواهد، درحالی‌که صفحه جزئیات مشخصات و Review را اضافه می‌کند. این ویژگی برای چند Client با Viewهای متفاوت مفید است.

اما GraphQL تضمین نمی‌کند Backend کمتر داده بخواند. Resolver ممکن است SELECT * اجرا کند، درخواست چند سرویس را Fan-out دهد یا N+۱ بسازد. Payload کوچک با هزینه Server زیاد همچنان ممکن است.

آیا REST همیشه Over-fetching دارد؟

خیر. REST می‌تواند Representationهای مختلف، Sparse Fieldsets، پارامتر fields، Endpoint مخصوص View، Include کنترل‌شده یا Backend for Frontend داشته باشد. هزینه آن، افزایش طراحی و نگهداری قراردادهاست.

تصمیم بگیرید انعطاف Shape در Client ارزش Complexity اجرایی GraphQL را دارد یا چند Representation پایدار کافی است.

Under-fetching و تعداد Round Trip

در REST، صفحه‌ای که Product، Review و Seller را می‌خواهد ممکن است چند Request انجام دهد. این درخواست‌ها می‌توانند موازی یا توسط BFF تجمیع شوند. GraphQL اجازه می‌دهد Client یک Operation سلسله‌مراتبی بفرستد، اما Server همچنان باید منابع زیرین را هماهنگ کند.

یک Request GraphQL لزوماً یک Database Query نیست. تعداد Round Trip Client کاهش می‌یابد، ولی Fan-out در Backend ممکن است افزایش یابد. Trace انتهابه‌انتها لازم است.

مشکل N+۱ در GraphQL

فرض کنید Query صد Order و Customer هر Order را می‌خواهد. Resolver ساده ممکن است یک Query برای Orderها و صد Query برای Customer اجرا کند. این الگو N+۱ است.

Batching

شناسه‌های Customer در یک بازه Execution جمع و با Query گروهی خوانده می‌شوند. Batch باید ترتیب نتیجه، Missing ID و Authorization را درست مدیریت کند.

Request-scoped caching

اگر چند Resolver همان Entity را بخواهند، Cache در محدوده Request از بار تکراری جلوگیری می‌کند. Cache بین Userها بدون Key مناسب می‌تواند داده خصوصی را نشت دهد.

DataLoader الگوست، نه درمان خودکار

Loader باید در Scope صحیح ساخته شود و Key شامل Tenant/Permission لازم باشد. Cache طولانی یا Singleton برای داده مجوزدار خطرناک است. Query Plan و Trace را پس از پیاده‌سازی اندازه بگیرید.

Caching در REST

REST می‌تواند مستقیماً از معنای GET، URI، Cache-Control، ETag و Vary استفاده کند. RFC ۹۱۱۱ درباره HTTP Caching Freshness، Validation، Shared و Private Cache را تعریف می‌کند.

برای محتوای عمومی و خواندنی، CDN Cache با URL پایدار مزیت مهمی است. اما وجود GET به‌تنهایی Cache امن نمی‌سازد؛ Authorization، Cookie، Vary و Purge باید درست باشند.

Caching در GraphQL

بسیاری از Operationها با POST به یک URL می‌روند، بنابراین Cache عمومی HTTP به‌صورت پیش‌فرض سخت‌تر است. راهکارها:

• Normalized Client Cache با Entity ID؛
• Resolver/Entity Cache در Server؛
• Persisted Query با Hash پایدار؛
• GET برای Query امن و محدود؛
• CDN GraphQL-aware؛
• Response Cache بر اساس Operation، Variable، User و Scope؛
• Cache Hint و Invalidation آگاهانه.

Cache Key باید Tenant، Locale، Authorization و Variable را درست پوشش دهد. Response شخصی را در Shared Cache عمومی ذخیره نکنید.

GraphQL over HTTP هنوز چه وضعیتی دارد؟

تا اوت ۲۰۲۶، GraphQL over HTTP در Stage ۲ Draft است و خود سند هشدار می‌دهد برای Production نباید بدون توجه به تغییرات Draft به آن تکیه کرد. Specification اصلی GraphQL Transport-agnostic است.

نتیجه عملی:

• رفتار Media Type و Status Code را با Framework و Client خود Contract Test کنید.
• Query امن را می‌توان با GET و Mutation را با POST اجرا کرد، اما جزئیات پیاده‌سازی فرق دارد.
• Partial Data و Errors باید در Client مدیریت شوند.
• Subscription Transport را از Library و Gateway انتخابی مستند کنید.

مدیریت خطا در REST

REST معمولاً Status Code HTTP را برای طبقه خطا استفاده می‌کند و Body جزئیات Domain را می‌دهد:

• 400 درخواست نامعتبر؛
• 401 نیاز به احراز هویت؛
• 403 عدم مجوز؛
• 404 Resource پیدا نشد؛
• 409 تعارض؛
• 422 ورودی از نظر Domain نامعتبر؛
• 429 Rate Limit؛
• 5xx خطای Server/Dependency.

Code دقیق باید Contract باشد. پیام داخلی، Stack Trace و Query Database را در پاسخ عمومی ندهید.

مدیریت خطا در GraphQL

GraphQL می‌تواند پاسخ شامل data و errors برگرداند. یک Field ممکن است خطا دهد و بقیه داده قابل استفاده بمانند. Client نباید صرفاً HTTP ۲۰۰ را موفقیت کامل بداند.

Error Extension می‌تواند Code قابل ماشین، Correlation ID و Field Path داشته باشد. جزئیات داخلی را Mask کنید. برای خطای Domain قابل انتظار، گاهی Union/Result Type در Schema تجربه Client بهتری از Error عمومی می‌دهد.

Versioning در REST

روش‌های رایج:

• نسخه در URL مانند /v1؛
• Header یا Media Type؛
• Evolution سازگار و Deprecation بدون نسخه صریح؛
• BFF جدا برای Consumer خاص.

نسخه جدید هزینه نگهداری دو Contract و مهاجرت Client دارد. هر تغییر کوچک را نسخه بزرگ نکنید؛ تغییر سازگار را اضافه و چرخه Sunset را مستند کنید.

Schema Evolution در GraphQL

افزودن Field یا Type معمولاً سازگار است. Field قدیمی را با @deprecated علامت بزنید، جایگزین را توضیح دهید و مصرف واقعی را قبل از حذف بسنجید.

• Field موجود را ناگهانی حذف یا Non-null نکنید.
• Enum Value جدید ممکن است Client با Exhaustive Switch را بشکند.
• تغییر Semantics بدون تغییر Type نیز Breaking است.
• Schema Check را در CI اجرا کنید.
• Operation Registry برای شناخت Consumer مفید است.
• Sunset Owner و تاریخ داشته باشد.

Type Safety و Code Generation

GraphQL Schema منبع خوبی برای Validation، IDE و تولید Type Client است. REST نیز با OpenAPI می‌تواند Codegen، Validation و Documentation قوی داشته باشد.

Type تولیدشده تضمین نمی‌کند داده Business درست است. Custom Scalar، Nullability، Error و Pagination باید دقیق طراحی شوند. Client Type را با Schema Deploy سازگار نگه دارید.

Pagination در REST

دو رویکرد رایج:

• Offset/Limit: ساده، اما در Dataset در حال تغییر ممکن است Duplicate/Skip بسازد.
• Cursor: پایدارتر برای Feed و داده بزرگ، اما طراحی و Debug پیچیده‌تر.

Limit حداکثر، Sort پایدار و Filter Indexدار لازم‌اند. Count کل می‌تواند گران باشد و همیشه لازم نیست.

Pagination در GraphQL

Connection Pattern با edges، node و pageInfo رایج است. Cursor باید Opaque، Sort پایدار و Scopeدار باشد. Query نباید اجازه first: 99999999 بدهد.

حداکثر Page Size را Server enforce کند و هزینه Nested Connection را در Complexity حساب کند.

امنیت مشترک REST و GraphQL

• احراز هویت و Session امن؛
• Authorization در سطح Resource/Action؛
• Validation ورودی؛
• Parameterized Query و جلوگیری از Injection؛
• Rate Limit و Abuse Control؛
• Timeout و Circuit Breaker؛
• Secret Management؛
• Audit Log و Correlation ID؛
• TLS و Patch Management؛
• حداقل‌سازی Error Detail.

GraphQL «خودکار امن» و REST «خودکار ساده» نیست. برای کنترل‌های Application، راهنمای مقابله با SQL Injection و XSS را ببینید.

ریسک‌های امنیتی ویژه GraphQL

GraphQL Cheat Sheet در OWASP Depth/Amount Limit، Timeout، Query Cost، Pagination، Rate Limit، Batching و Cache سمت Server را برای کاهش DoS توصیه می‌کند.

Depth و Cyclic Query

Relationهایی که به هم برمی‌گردند می‌توانند Query عمیق بسازند. Depth Limit مفید است، اما Depth کم نیز می‌تواند با Page Size بزرگ گران باشد.

Query Complexity

برای هر Field وزن و برای List ضریب تعداد در نظر بگیرید. Cost ثابت همیشه دقیق نیست؛ Resolver و Data Source واقعی را با Trace کالیبره کنید.

Batching Attack

چند Operation یا Alias می‌تواند Rate Limit سطح HTTP را دور بزند. محدودیت را بر Action حساس، User و Object نیز اعمال کنید.

Introspection

خاموش‌کردن Introspection جای Authorization نیست. برای Public API، Schema ممکن است بخشی از قرارداد باشد. در محیط حساس، دسترسی Tooling و Error Detail را محدود کنید، اما فرض نکنید پنهان‌کردن Schema امنیت می‌سازد.

Field-level authorization

مجوز را فقط در Resolver Root چک نکنید. هر Entity/Field حساس باید Context کاربر و Tenant را بررسی کند. Loader و Cache نیز نباید داده مجوزدار را بین Userها به اشتراک بگذارند.

Persisted Query و Trusted Document

Client به‌جای متن آزاد Query، Hash یا ID Operation از قبل ثبت‌شده می‌فرستد. مزایا:

• کاهش اندازه Request؛
• Allowlist برای Clientهای تحت کنترل؛
• پیش‌محاسبه Cost؛
• شناخت Consumer هر Field؛
• Cache Key پایدارتر؛
• کاهش Surface Query دلخواه.

این روش برای Public API که Developer Query جدید می‌سازد ممکن است مناسب نباشد. Registry باید با Release Client هماهنگ و Rollbackپذیر باشد.

Authorization در REST

Route و Method مرز اولیه خوبی برای Policy می‌دهند، اما Authorization فقط Middleware Route نیست. دسترسی Object-level، Field-level و Tenant-level باید در Domain enforce شود.

مثلاً کاربر مجاز به GET /orders/981 نیست مگر Order متعلق به Tenant او باشد. حدس‌ناپذیر بودن ID کنترل دسترسی نیست.

Observability در REST و GraphQL

متن کامل Query و Variable می‌تواند PII یا Secret داشته باشد. Log را Redact، Operation را Name و Hash را ثبت کنید. Anonymous Query در Production عیب‌یابی را سخت می‌کند.

عملکرد GraphQL را چگونه بسنجیم؟

• p50/p95/p99 Latency بر اساس Operation؛
• Resolver Time و تعداد فراخوانی؛
• Database Query Count؛
• Data Source Fan-out؛
• Query Complexity و Depth؛
• Response Size و Error Count؛
• Cache Hit و Loader Batch Size؛
• Timeout، Cancellation و Resource Usage؛
• Field Usage و Deprecated Usage.

میانگین Endpoint /graphql تقریباً بی‌معناست؛ Operation و Client را جدا کنید.

Subscriptions و Real-time

GraphQL Specification عملیات Subscription را تعریف می‌کند، اما Transport شبکه در Specification اصلی یکسان‌سازی نشده است. WebSocket، Server-Sent Events یا Vendor Protocol ممکن است استفاده شود. GraphQL over HTTP Draft نیز Subscription را خارج از Scope فعلی خود می‌داند.

برای Event پرتعداد، Binary Media یا ارتباط Peer-to-peer، GraphQL Subscription لزوماً بهترین گزینه نیست. Queue، Webhook، SSE، WebSocket یا WebRTC را بر اساس Delivery، Ordering، Backpressure و Scale انتخاب کنید. برای ارتباط Media بلادرنگ، راهنمای معماری WebRTC مرتبط است.

آپلود و دانلود فایل

ارسال Base64 در GraphQL Payload سربار و Memory Pressure می‌سازد. الگوی رایج:

1. Mutation برای درخواست Upload؛
2. Server مجوز، نوع و اندازه را بررسی می‌کند؛
3. URL امضاشده کوتاه‌عمر برمی‌گردد؛
4. Client مستقیم به Object Storage می‌فرستد؛
5. Finalize/Scan وضعیت را ثبت می‌کند.

دانلود نیز بهتر است از CDN/Object Storage با Authorization مناسب انجام شود. Mutation باید Ownership فایل را پس از Upload تأیید کند.

Federation و GraphQL Gateway

وقتی چند تیم یک Graph مشترک می‌سازند، Ownership Type/Field، Composition، Query Plan و Failure Domain مهم می‌شوند. Federation پیچیدگی سازمانی را حذف نمی‌کند؛ آن را در Schema و Gateway قابل مشاهده می‌کند.

• هر Field یک Owner روشن داشته باشد.
• Schema Contract در CI بررسی شود.
• Dependency Graph و Query Plan مانیتور شود.
• Timeout و Partial Failure تعریف شود.
• N+۱ بین Serviceها اندازه‌گیری شود.
• Gateway Rollback و Compatibility داشته باشد.

برای تیم کوچک، یک Graph Monolith تمیز می‌تواند بهتر از Federation زودهنگام باشد.

چه زمانی REST انتخاب مناسب‌تری است؟

• Resource و عملیات ساده و پایدارند.
• HTTP/CDN Caching اولویت بالاست.
• API عمومی با الگوی مصرف قابل پیش‌بینی دارید.
• فایل، Stream یا Webhook بخش اصلی است.
• تیم عملیات GraphQL و Query Cost ندارد.
• Endpointهای محدود تمام Clientها را پوشش می‌دهند.
• سادگی Debug و استفاده با curl مهم است.

چه زمانی GraphQL انتخاب مناسب‌تری است؟

• چند Client با نیاز داده متفاوت دارید.
• Viewهای سلسله‌مراتبی و متغیر زیادند.
• تیم Frontend نیاز به استقلال Shape دارد.
• Schema و Codegen ارزش زیادی می‌سازند.
• ترکیب چند Data Source در یک Product API لازم است.
• Field Usage و Evolution باید دقیق دیده شوند.
• توان Batching، Complexity و Observability دارید.

چه زمانی مدل ترکیبی بهتر است؟

REST و GraphQL رقیب انحصاری نیستند. معماری متداول:

• GraphQL برای Product UI و Composition؛
• REST برای Webhook، فایل و API Partner؛
• gRPC یا Queue بین Serviceها؛
• CDN REST برای محتوای عمومی؛
• BFF GraphQL روی Serviceهای موجود؛
• Endpoint تخصصی برای Batch یا Export سنگین.

مرز را بر اساس Consumer و Workload تعیین کنید، نه سلیقه تیم.

ماتریس تصمیم GraphQL یا REST

مهاجرت از REST به GraphQL

مرحله ۱: مسئله را ثابت کنید

تعداد Round Trip، تغییرات Endpoint، Payload اضافه و زمان Delivery را اندازه بگیرید. GraphQL را برای حل مشکل مشخص انتخاب کنید.

مرحله ۲: یک Read Journey

یک صفحه Read-heavy را پشت BFF GraphQL قرار دهید. Mutation مالی یا Flow حساس را در Pilot اول جابه‌جا نکنید.

مرحله ۳: Schema و Loader

Entity ID، Nullability، Pagination و Error را طراحی کنید. قبل از Scale، N+۱ و Authorization را تست کنید.

مرحله ۴: Guardrail

Operation Name، Depth/Amount، Complexity، Timeout، Rate Limit، Persisted Query و Redaction را اضافه کنید.

مرحله ۵: Canary و Contract

Client محدود، Schema Check، Load Test و Rollback داشته باشید. REST قدیمی را تا مهاجرت Consumer حفظ و Deprecation را اعلام کنید.

تست و CI/CD برای API

• Schema/OpenAPI lint؛
• Breaking Change Detection؛
• Contract Test Consumer؛
• Resolver/Handler Unit Test؛
• Authorization Matrix؛
• Query Cost و Abuse Test؛
• Load Test با Operation واقعی؛
• Migration Database Test؛
• Canary و Rollback؛
• Production Smoke Test بدون داده حساس.

برای Artifact، Migration و Rollback، راهنمای CI/CD امن را ببینید.

چک‌لیست Production برای GraphQL

• Operation در Production نام‌گذاری می‌شود.
• Pagination و Page Size حداکثر دارند.
• Depth، Amount یا Cost کنترل می‌شود.
• Timeout و Cancellation تا Data Source Propagate می‌شوند.
• N+۱ با Trace و Loader کنترل شده است.
• Authorization در Object/Field تست شده است.
• Batching Action حساس محدود است.
• Error داخلی Mask و Correlation ID ثبت می‌شود.
• Query/Variable حساس Redact می‌شود.
• Schema Change در CI بررسی می‌شود.
• Deprecated Field مصرف و Sunset دارد.
• Cache Tenant/User را جدا می‌کند.
• Fallback و Load Shedding تعریف شده‌اند.

اشتباه‌های رایج مقایسه GraphQL و REST

• GraphQL را Database می‌دانند: فقط زبان و Execution System است.
• یک Request را یک Query فرض می‌کنند: Resolver Fan-out دیده نمی‌شود.
• REST را بدون Schema می‌دانند: OpenAPI نادیده گرفته می‌شود.
• GraphQL را بدون Versioning می‌دانند: Evolution و Deprecation همچنان لازم است.
• HTTP ۲۰۰ را موفقیت کامل می‌گیرند: Field Error و Partial Data حذف می‌شود.
• Introspection Off را امنیت می‌دانند: Authorization و Cost Control وجود ندارد.
• Rate Limit فقط بر Request است: Batching و Alias دورش می‌زنند.
• Cache را غیرممکن می‌دانند: فقط نیازمند طراحی متفاوت است.
• Federation را زود اجرا می‌کنند: پیچیدگی تیم و Gateway افزایش می‌یابد.
• همه APIها را مهاجرت می‌دهند: Workload فایل و Webhook نامناسب است.

سؤالات متداول GraphQL و REST

GraphQL از REST سریع‌تر است؟

ذاتاً نه. GraphQL می‌تواند Round Trip و Payload Client را کم کند، اما Resolver و N+۱ ممکن است Server را کند کنند. Latency، Query Count، Payload و Cache را با Workload واقعی مقایسه کنید.

آیا GraphQL به API Version نیاز ندارد؟

Schema معمولاً با افزودن Field و Deprecation تکامل می‌یابد، اما Breaking Change، Sunset و Compatibility همچنان مدیریت می‌شوند. «بدون /v2» به معنی بدون Version Governance نیست.

آیا REST برای موبایل بد است؟

خیر. Sparse Fieldset، BFF، Endpoint View و HTTP/۲/۳ می‌توانند REST را برای موبایل کارآمد کنند. GraphQL زمانی ارزش دارد که Shapeهای متعدد و تغییر سریع واقعاً مسئله باشند.

آیا GraphQL امن‌تر است؟

خیر. Type و Validation مزیت‌اند، اما Query دلخواه Surface DoS و Authorization پیچیده می‌سازد. Depth/Amount/Cost، Rate Limit، Pagination و Field-level Access لازم‌اند.

می‌توان REST و GraphQL را هم‌زمان داشت؟

بله. GraphQL برای UI Composition و REST برای فایل، Webhook یا Partner API ترکیب رایجی است. قرارداد، Ownership و Observability هر مرز را روشن نگه دارید.

جمع‌بندی: Workload انتخاب می‌کند

REST با معنای HTTP، Cache و Resourceهای پایدار گزینه‌ای قدرتمند است. GraphQL برای Viewهای متغیر، چند Client و Composition داده انعطاف زیادی می‌دهد، اما Query Cost، N+۱، Authorization و Observability می‌خواهد. بهترین معماری می‌تواند ترکیبی باشد؛ مسئله واقعی، توان تیم و هزینه بلندمدت را کنار تجربه Developer بسنجید.

اگر برای انتخاب معماری API، طراحی Schema/OpenAPI، ممیزی امنیت یا Pilot مهاجرت نیاز به کمک دارید، از طریق درخواست مشاوره مایندیو Clientها، Workload و محدودیت‌های فعلی را ارسال کنید.

مطالب مرتبط

• امنیت، Rate Limit و Versioning API
• پایپ‌لاین CI/CD امن
• جلوگیری از SQL Injection و XSS
• معماری WebRTC و ارتباط بلادرنگ
• HTTP/۳ و QUIC
• آمادگی زیرساخت برای ترافیک بالا