كيفية تثبيت واستخدام PostgREST API: دليل المبتدئين

هل فكرت يومًا في مقدار الوقت الذي يقضيه المطورون في بناء واجهات برمجة تطبيقات RESTful فوق قواعد بيانات PostgreSQL؟ غالبًا ما يتضمن ذلك كتابة تعليمات برمجية متكررة لعمليات CRUD، والتعامل مع الاستعلامات، وضمان الأمان - وهي مهام يمكن أن تبطئ زخم مشروعك. هنا يأتي دور واجهة برمجة تطبيقات PostgREST، حيث تقدم بديلاً مبسطًا يحول قاعدة بياناتك إلى واجهة برمجة تطبيقات جاهزة للاستخدام بأقل جهد. في هذا الدليل الشامل، سنستكشف واجهة برمجة تطبيقات PostgREST بعمق، من مفاهيمها الأساسية إلى التنفيذ العملي. سواء كنت مهندسًا خلفيًا تتطلع إلى تسريع التطوير أو مطورًا متكاملًا يسعى إلى الكفاءة، فإن إتقان واجهة برمجة تطبيقات PostgREST يمكن أن يحول سير عملك.

بينما نتنقل في هذا الموضوع معًا، سأشارك رؤى مستمدة من الخبرة العملية، مع ضمان أن كل قسم يبني منطقيًا على سابقه. بحلول النهاية، ستشعر أنك مجهز لدمج واجهة برمجة تطبيقات PostgREST في مشروعك التالي. دعنا نبدأ بالأساسيات.

ما هي واجهة برمجة تطبيقات PostgREST؟ نظرة عامة

واجهة برمجة تطبيقات PostgREST هي أداة مستقلة تعرض قاعدة بيانات PostgreSQL الخاصة بك تلقائيًا كخدمة ويب RESTful كاملة الوظائف. تم تطويرها بواسطة Beowulf، وهي تستفيد من قوة لغة استعلام PostgreSQL (SQL) لتوليد نقاط نهاية HTTP ديناميكيًا، مما يلغي الحاجة إلى منطق مخصص من جانب الخادم في العديد من الحالات. في جوهرها، تفسر واجهة برمجة تطبيقات PostgREST مخططات قواعد البيانات والجداول وطرق العرض والإجراءات المخزنة كموارد API، مما يتيح لك إجراء عمليات الإنشاء والقراءة والتحديث والحذف (CRUD) عبر طرق HTTP القياسية مثل GET و POST و PUT و DELETE.

ما يجعل واجهة برمجة تطبيقات PostgREST جذابة بشكل خاص هو التزامها بمبادئ REST مع دمج ميزات PostgreSQL المتقدمة مثل أمان مستوى الصف (RLS) للتحكم الدقيق في الوصول. على سبيل المثال، يمكنك استعلام البيانات باستخدام عوامل التصفية والفرز والترقيم باستخدام معلمات URL - لا يلزم وجود وسيط إضافي. لا يقلل هذا النهج من تعقيد التعليمات البرمجية فحسب، بل يضمن أيضًا بقاء واجهة برمجة تطبيقاتك متزامنة مع تغييرات قاعدة البيانات تلقائيًا.

في بيئة تهيمن عليها ORMs وأطر عمل API، تبرز واجهة برمجة تطبيقات PostgREST لفلسفتها "قاعدة البيانات أولاً". وهي تدعم وثائق OpenAPI (Swagger) جاهزة للاستخدام، مما يجعلها صديقة للمطورين للدمج مع أدوات مثل Apidog أو Swagger UI. إذا كنت تدير تطبيقات كثيفة البيانات - مثل لوحات معلومات التحليلات أو الواجهات الخلفية للهواتف المحمولة أو الخدمات المصغرة - توفر واجهة برمجة تطبيقات PostgREST حلاً خفيف الوزن وعالي الأداء يتوسع مع قوة PostgreSQL. بينما نواصل، سترى كيف تسد واجهة برمجة التطبيقات هذه الفجوة بين طبقة البيانات وتطبيقات العميل بسلاسة.

البدء باستخدام واجهة برمجة تطبيقات PostgREST: التثبيت والإعداد

يتطلب بدء عملك مع واجهة برمجة تطبيقات PostgREST وجود نسخة PostgreSQL، حيث إنها تعمل كأساس. لحسن الحظ، الإعداد مباشر، خاصة عند استخدام أدوات الحاويات مثل Docker، التي تعزل التبعيات وتبسط النشر. ابدأ بالتأكد من تثبيت Docker Desktop على جهازك - قم بتنزيله من الموقع الرسمي لنظام التشغيل الخاص بك (macOS أو Windows أو Linux).

بمجرد أن يصبح Docker جاهزًا، اسحب الصور الضرورية. افتح Docker Desktop، وانتقل إلى شريط البحث، وقم بتثبيت صورة "postgrest/postgrest" لخادم API نفسه. وبالمثل،

ابحث عن "dpage/pgadmin4" وقم بتثبيته لإدارة قاعدة بيانات PostgreSQL الخاصة بك بصريًا.

و "postgres:alpine" لحاوية PostgreSQL خفيفة الوزن. تشكل هذه المكونات النظام البيئي حول واجهة برمجة تطبيقات PostgREST.

لإعداد PostgreSQL يدويًا عبر الطرفية (موصى به)، قم بتنفيذ الأمر التالي لتشغيل حاوية:

docker run --name postgres-1 -e POSTGRES_PASSWORD=password -d -p 5431:5432 postgres:alpine

هنا، استبدل "password" بقيمة آمنة. يقوم الأمر بتشغيل PostgreSQL على المنفذ 5431، مع تعيينه داخليًا إلى 5432. عند النجاح، يعيد Docker معرف الحاوية (سلسلة أبجدية رقمية طويلة) - لاحظها للتحقق. قم بتشغيل docker ps لتأكيد حالة الحاوية.

للتحقق من أدوار المستخدمين، وهي ضرورية لتكوين واجهة برمجة تطبيقات PostgREST، ادخل إلى shell الحاوية:

docker exec -it <container_id> sh

استبدل <container_id> بمعرفك أو اسم الحاوية. داخل shell، اتصل بـ PostgreSQL:

psql -U postgres -d postgres

(بافتراض أن "postgres" هو المستخدم الافتراضي؛ قم بالتعديل إذا تم تخصيصه. مثل حالتي التي تم تغييرها إلى username) ثم، قم بسرد الأدوار باستخدام \du. سيتم الإشارة إلى هذا الإخراج، بما في ذلك أسماء الأدوار مثل "postgres" أو الأدوار المخصصة، لاحقًا. يمكنك إنشاء مستخدمين إضافيين هنا وتعيين أذونات، مثل منح SELECT أو INSERT أو UPDATE أو DELETE على المخططات.

مع هذه المتطلبات المسبقة، أنت جاهز لتنسيق بيئتك باستخدام Docker Compose - وهو ملف YAML يحدد تطبيقات متعددة الحاويات. أنشئ ملف docker-compose.yaml في دليل مشروعك:

version: "3.9"
services:
  postgres_host:
    image: postgres:alpine
    environment:
      POSTGRES_USER: username
      POSTGRES_PASSWORD: password
      POSTGRES_DB: postgres
    volumes:
      - pgdata:/var/lib/postgresql/data
    ports:
      - "5431:5432"
  pgadmin:
    image: dpage/pgadmin4
    ports:
      - "5050:80"
    depends_on:
      - postgres_host
    environment:
      PGADMIN_DEFAULT_EMAIL: postgres@pgadmin.com
      PGADMIN_DEFAULT_PASSWORD: postgres
  postgrest:
    image: postgrest/postgrest
    depends_on:
      - postgres_host
    ports:
      - "3000:3000"
    environment:
      PGRST_DB_URI: "postgres://username:password@postgres_host:5432/postgres"
      PGRST_DB_SCHEMA: "public"
      PGRST_DB_ANON_ROLE: "username"
volumes:
  pgdata:

خصص "username" و "password" لتطابق إعداداتك، واضبط PGRST_DB_ANON_ROLE على دور من إخراج \du الخاص بك للوصول المجهول. يربط هذا التكوين PostgreSQL و pgAdmin وخادم PostgREST API. احفظ الملف، ثم في الطرفية (مثل الطرفية المدمجة في VS Code، بعد تثبيت إضافة Docker)، قم بتشغيل:

docker compose up --build

يقوم هذا ببناء وتشغيل الخدمات. قم بالوصول إلى pgAdmin على http://localhost:5050 باستخدام بيانات الاعتماد الموجودة في ملف YAML، وأضف خادمًا باسم "postgres_host" مع تفاصيل الاتصال (اسم المضيف: postgres_host، المنفذ: 5432، اسم المستخدم: username، كلمة المرور: password)، ثم احفظ. لديك الآن واجهة برمجة تطبيقات PostgREST تعمل على http://localhost:3000، جاهزة لتفاعلات قاعدة البيانات.

بناء مشروع نموذجي: اختبار واجهة برمجة تطبيقات PostgREST خطوة بخطوة

لتقدير قوة واجهة برمجة تطبيقات PostgREST حقًا، دعنا ننشئ مشروعًا عمليًا: واجهة برمجة تطبيقات بسيطة لقاعدة بيانات الموارد البشرية لإدارة سجلات الموظفين. يوضح هذا المثال عمليات CRUD على جدول "humans"، باستخدام Docker للتنسيق و Apidog لاختبار API.

الخطوة 1: إعداد بيئتك

مع تثبيت Docker Desktop وسحب الصور (PostgREST، pgAdmin4، postgres:alpine)، قم بتشغيل حاوية PostgreSQL الأولية كما هو موضح سابقًا. تحقق باستخدام docker ps ولاحظ أدوار المستخدمين عبر \du.

الخطوة 2: تجميع مكدسك

في محرر التعليمات البرمجية مثل VS Code (معززًا بإضافة Docker لإدارة الحاويات بسلاسة)، قم بإنشاء ملف docker-compose.yaml أعلاه. تأكد من تطابق أسماء الصور بدقة - يمكن أن يؤدي عدم التطابق إلى توقف التشغيل. اضبط المنافذ إذا لزم الأمر، ولكن حافظ على اتساق منفذ PostgreSQL الخارجي (5431) مع إعدادك اليدوي. قم بالتشغيل باستخدام docker compose up --build. راقب السجلات بحثًا عن الأخطاء؛ يشير التشغيل الناجح إلى ربط الخدمات بالمنافذ 5431 (قاعدة البيانات)، 5050 (pgAdmin)، و 3000 (PostgREST).

الخطوة 3: تكوين pgAdmin وإنشاء الجدول

انتقل إلى http://localhost:5050، وقم بتسجيل الدخول باستخدام PGADMIN_DEFAULT_EMAIL و PASSWORD من ملف YAML.

تحت لوحة التحكم،

أضف خادمًا جديدًا: سمّه "postgres_host"،

ثم في علامة التبويب Connection، أدخل اسم المضيف: postgres_host، المنفذ: 5432، اسم المستخدم: username، كلمة المرور: password. احفظ للوصول إلى الواجهة.

إنشاء جدول: اذهب إلى Databases > postgres > Schemas > public > Tables، انقر بزر الماوس الأيمن على Tables، واختر Create > Table. سمّه "humans". في Columns، أضف:

• id: INTEGER, ليس فارغًا, مفتاح أساسي
• name: VARCHAR(50), ليس فارغًا
• job: VARCHAR(50)

انقر فوق حفظ. لإدراج البيانات، انقر بزر الماوس الأيمن على جدول "humans" > Scripts > INSERT Script. قم بالتعديل باستخدام SQL نموذجي، على سبيل المثال:

INSERT INTO public.humans (id, name, job) VALUES (1, 'Steph Curry', 'Pro Basketball Player');

نفذ لحفظ السجل.

الخطوة 4: التحقق من توفر واجهة برمجة تطبيقات PostgREST

افتح http://localhost:3000 في متصفحك. يجب أن ترى وثيقة مواصفات Swagger 2.0 تسرد الموارد مثل /humans - تأكيدًا على أن واجهة برمجة تطبيقات PostgREST تعمل وتدرك المخطط.

الخطوة 5: الاختبار باستخدام Apidog

شغل Apidog، أنشئ مشروعًا جديدًا، وأضف طلب GET إلى http://localhost:3000/humans (استبدل "humans" باسم جدولك). أرسل الطلب؛ سيعيد JSON مثل:

[
  {
    "id": 1,
    "name": "Steph Curry",
    "job": "Pro Basketball Player"
  }
]

للاستعلام، أضف معلمة استعلام: المفتاح "name"، القيمة "eq.Steph Curry" (حيث تشير "eq" إلى المساواة). يقوم هذا بتصفية السجلات المطابقة؛ تؤدي عدم المطابقة إلى مصفوفات فارغة.

الخطوة 6: استكشاف عمليات CRUD

تتألق واجهة برمجة تطبيقات PostgREST في عمليات CRUD الكاملة. لـ POST (إنشاء)، استخدم نص Apidog كـ JSON: {"name": "New Employee", "job": "Developer"} إلى http://localhost:3000/humans. يقوم PUT بالتحديث عبر http://localhost:3000/humans?id=eq.1 ببيانات مُحدّثة. يستخدم DELETE http://localhost:3000/humans?id=eq.1. تعمل الفلاتر المتقدمة مثل الفرز (order=name.asc) أو الحدود (limit=5) على تحسين قابلية الاستخدام. للحصول على أمثلة شاملة، راجع الوثائق الرسمية على https://docs.postgrest.org/en/v14/references/api/tables_views.html.

يوضح هذا المشروع، الذي يستغرق أقل من ساعة، براعة واجهة برمجة تطبيقات PostgREST في النماذج الأولية السريعة. قم بتوسيع نطاقه عن طريق إضافة سياسات RLS في PostgreSQL للوصول الآمن والقائم على الأدوار.

الأسئلة المتكررة

س1. ما هي متطلبات النظام لتشغيل واجهة برمجة تطبيقات PostgREST؟

ج: تتطلب واجهة برمجة تطبيقات PostgREST إصدار PostgreSQL 9.4 أو أحدث، مع توصية بـ Docker للإعدادات المعبأة في حاويات. تعمل بكفاءة على أجهزة متواضعة، وتحتاج إلى 512 ميجابايت على الأقل من ذاكرة الوصول العشوائي للعمليات الأساسية.

س2. هل يمكن لواجهة برمجة تطبيقات PostgREST التعامل مع الاستعلامات المعقدة التي تتجاوز عمليات CRUD الأساسية؟

ج: نعم، إنها تدعم قدرات SQL الكاملة لـ PostgreSQL عبر استدعاءات RPC المضمنة وطرق العرض، مما يسمح بالربط والتجميع والوظائف المخصصة التي يتم عرضها كنقاط نهاية.

س3. كيف تضمن واجهة برمجة تطبيقات PostgREST أمان البيانات؟

ج: تتكامل بشكل طبيعي مع أمان مستوى الصف (Row-Level Security) والأذونات القائمة على الأدوار في PostgreSQL، وتفرض ضوابط الوصول على مستوى قاعدة البيانات دون نقاط ضعف من جانب API.

س4. هل واجهة برمجة تطبيقات PostgREST مناسبة لبيئات الإنتاج؟

ج: بالتأكيد، مع ميزات مثل مصادقة JWT، وعزل المخطط، والتوسع الأفقي عبر مثيلات متعددة. راقب الأداء وطبق RLS للامتثال.

س5. كيف أدمج واجهة برمجة تطبيقات PostgREST مع أطر عمل الواجهة الأمامية؟

ج: استخدم عملاء HTTP مثل Axios أو Fetch؛ قم بإنشاء أنواع TypeScript من مواصفات OpenAPI لسلامة النوع في تطبيقات React أو Vue أو Angular.

الخاتمة

في ختام استكشافنا، تظهر واجهة برمجة تطبيقات PostgREST كحل أنيق لتطوير يعتمد على قواعد البيانات، وتحويل نقاط قوة PostgreSQL إلى خدمات ويب سهلة الوصول. من الإعداد السهل إلى الاستعلامات المتطورة، تمكنك من تقديم واجهات برمجة تطبيقات قوية بأقل تكلفة. أشجعك على تكرار المشروع النموذجي وتجربة المزيد - ربما توسيعه بالمصادقة. مع تطور تطبيقاتك، ستثبت واجهة برمجة تطبيقات PostgREST أنها حليف لا غنى عنه في الحفاظ على المرونة والموثوقية.