kararas_iris/README_AR.md

أعزائي أعضاء مجتمع Iris،

قد تكون قد لاحظتم مؤخرًا تراجعًا في مستوى النشاط على مستودع Iris، ولكن هذا الهدوء له غاية مقصودة. طوال هذه الفترة كنت أعمل على الإصدار الرئيسي الجديد، Iris v14، الذي يعتمد بشكل كامل على الأنواع العامة (Generics)، إلى جانب مجموعة من الميزات الجديدة والتحسينات والابتكارات. هذا التطوير يستند إلى خبرتي الممتدة على مدى سنوات في لغة Go، لضمان أن يستمر تطور Iris بما يتماشى مع احتياجاتكم المتنامية.

مع أطيب التحيات،
Gerasimos (Makis) Maropoulos

الأخبار

🚀 Iris v14 في الطريق. الإصدار الرئيسي القادم هو الأكبر في تاريخ المشروع: إطار عمل أُعيد بناؤه على الأنواع العامة في Go، وباني تطبيقات يتحقق منه المُصرِّف، ودوال مساعدة للطلبات تتولى التحقق نيابةً عنك، وخريطة أخطاء مركزية واحدة، وثلاثون برمجية وسيطة مدمجة، وكتاب يُنشر داخل المستودع نفسه. اطّلع أدناه على ما الذي يأتي في Iris v14.

النسخة الموصوفة هنا، v12، ما زالت تعمل وما زالت تتلقى الإصلاحات. سيصدر v14 على مسار استيراد جديد، لذلك لن يتعطل شيء لديك يوم صدوره.

Iris Web Framework إطار العمل إريس English

⚡ Iris هو إطار عمل ويب سريع، بسيط، ومع ذلك غني بالميزات وفعّال للغاية بلغة Go.

✨ يوفّر أساسًا مرنًا، سهل الاستخدام، وذا تعبيرية رائعة لبناء موقعك الإلكتروني أو واجهة برمجة التطبيقات (API) القادمة.

🌟 تعرّف على آراء الآخرين حول Iris و**امنح المشروع نجمة** لدعم هذا المشروع مفتوح المصدر.

package main

import "github.com/kataras/iris/v12"

func main() {
  app := iris.New()
  app.Use(iris.Compression)

  app.Get("/", func(ctx iris.Context) {
    ctx.HTML("Hello <strong>%s</strong>!", "World")
  })

  app.Listen(":8080")
}

كما قال أحد مطوري Go ذات مرة: Iris يغطي جميع الجوانب، وظل صامدًا وقويًا على مدار السنوات.

بعض الميزات التي يقدّمها Iris:

• دعم كامل لبروتوكول HTTP/2 (يشمل Push وبيانات مضمّنة)
• البرمجيات الوسيطة (Middleware): Accesslog، Basicauth، CORS، gRPC، Anti-Bot hCaptcha، JWT، MethodOverride، ModRevision، Monitor، PPROF، Ratelimit، Anti-Bot reCaptcha، Recovery، RequestID، Rewrite
• إصدار واجهات برمجة التطبيقات (API Versioning)
• نموذج-عرض-تحكم (Model-View-Controller)
• دعم كامل لبروتوكول WebSockets
• دعم gRPC
• دعم تلقائي لـ HTTPS
• دعم مدمج لـ ngrok لعرض تطبيقك على الإنترنت بأسرع طريقة
• موجّه (Router) فريد يدعم المسارات الديناميكية مع أنواع قياسية مثل ‎:uuid‎ و‎:string‎ و‎:int‎، وإمكانية إنشاء أنواعك الخاصة
• ضغط البيانات
• محركات العرض: HTML، Django، Handlebars، Pug/Jade وغيرها
• إنشاء خادم ملفات خاص بك واستضافة خادم WebDAV
• التخزين المؤقت
• التوطين (i18n، sitemap)
• الجلسات
• استجابات غنية تشمل: HTML، نص، Markdown، XML، YAML، ثنائي، JSON، JSONP، Protocol Buffers، MessagePack، Content Negotiation، البث المتدفق، والأحداث المرسلة من الخادم والمزيد
• ضغط الاستجابات (gzip، deflate، brotli، snappy، s2)
• طلبات غنية تدعم: ربط استعلامات URL، الرؤوس، النماذج، النصوص، XML، YAML، ثنائي، JSON، التحقق، Protocol Buffers، MessagePack والمزيد
• الحقن التلقائي للاعتماديات: لمعماريات MVC، المعالجات، وموجّهات واجهات برمجة التطبيقات
• مجموعة اختبارات
• والأهم... تحصل على إجابات سريعة ودعم، منذ اليوم الأول وحتى الآن

🚀 ما الذي يأتي في Iris v14

Iris v14 هو الإصدار الأكبر في تاريخ المشروع. يعيد بناء الإطار على الأنواع العامة في Go، ويغيّر طريقة تجميع التطبيق: توصيلات أقل داخل main، ومعالجات أقصر، ومكان واحد للقرارات التي كانت موزّعة سابقًا على كل مسار.

لا شيء من هذا يتطلب انتباهك اليوم. v12 ما زال يعمل، وما زال يتلقى الإصلاحات، وسيأتي v14 مع دليل ترحيل يغطي كل واجهة برمجية جرى تغيير اسمها أو حذفها.

التطبيق بأكمله في سلسلة واحدة يتحقق منها المُصرِّف

يقوم iris.NewBuilder بربط CORS، والضغط، وسجل الوصول، ونقطة فحص السلامة، وخريطة الأخطاء، وخدماتك ومجموعات واجهاتك البرمجية في تعبير واحد. المُصرِّف هو من يفرض ترتيب الخطوات، لذا فإن التطبيق إما يُبنى بشكل صحيح أو لا يُبنى إطلاقًا.

iris.NewBuilder().
    Prefix("/api").
    AllowOrigin("*").
    Compression(true).
    LogRequests(true).
    Health(true, "production", "kataras").
    Errors(errors.NewOptions().
        MapErrors(errors.NotFound, catalog.ErrNotFound)).
    Services(catalog.NewRepository, catalog.NewService).
    API("/products", api.NewProductsAPI).
    Build().
    Listen(":8080")

المعالجات تتوقف عن تكرار نفسها

يخرج فك الترميز والتحقق وعرض الأخطاء من جسم المعالج. تقوم rest.ReadJSON[T] بفك ترميز الطلب، وتشغيل الدالة Validate() error الخاصة بنوعك إن وُجدت، وكتابة استجابة 400 بنفسها. أما دوال الاستجابة المساعدة فتكتب رمز حالة النجاح، أو ما تحدده خريطتك المركزية لذلك الخطأ.

func (api *ProductsAPI) create(ctx iris.Context) {
    input, ok := rest.ReadJSON[catalog.ProductInput](ctx)
    if !ok {
        return // كُتبت 400 بالفعل: JSON غير صالح أو فشل Validate.
    }

    id, err := api.svc.Create(ctx, input)
    rest.Created(ctx, id, err) // 201، أو الخطأ المرتبط مركزيًا.
}

وتغطي rest.OK وrest.NoContent وrest.Count وrest.Paginated بقية الأشكال التي ترجعها واجهة برمجية.

الأخطاء تُعلَن مرة واحدة

تحتفظ الحزمة الجديدة rest/errors بالربط بين أخطاء مجالك واستجابات HTTP. يحصل العملاء على حمولات قياسية قابلة للقراءة آليًا. وتبقى الرسائل الداخلية داخلية. سجّل مُجمِّعًا (collector) وسيصل كل إخفاق إلى سجلّك أو قاعدة بياناتك من مكان واحد. ويمكن عرض الخطأ بصيغة JSON أو كواجهة عرض، حسب ما طلبه العميل.

حقن الاعتماديات في كل مكان، لا في MVC فقط

تعلن الدوال البانية عمّا تحتاجه ويوفّره الحاوي: للمعالجات، ولمجموعات واجهات برمجة التطبيقات، وللمتحكمات. والخدمة التي تنفّذ Init(ctx context.Context) error تعمل مرة واحدة داخل Build(). وكل ما يمكن إغلاقه يُغلق عند إيقاف التشغيل. أما الحزمة hero فقد اختفت، واستُبدلت بـ dep وrest اللتين تنجزان أكثر بأسطر أقل. ومتحكمات MVC مبنية على الأنواع العامة.

الحزم في المكان الذي تتوقعه

أصبحت sessions وcache وwebsocket وi18n وview وversioning برمجيات وسيطة. وانتقلت mvc إلى داخل controller، إلى جانب المتحكمات الجديدة fileserver وsitemap وapigraph. ويرسم apigraph شجرة مساراتك على هيئة رسم بياني تفاعلي بـ D3.

وتأتي ثلاثون برمجية وسيطة جاهزة، من بينها الجديد: httpcost (الزمن والذاكرة والمعالج لكل طلب، لتحليل الأداء أو للفوترة)، وbodylimit، وcompress، وcounter، وreferrer، وgeolocation، وipaccess، وservertiming. وانتقلت تطبيقات محركات العرض إلى iris-contrib/views.

الإعدادات صارت قيمة جزئية

استُبدلت iris.Configuration ومهيّئات With* بـ iris.Options. اضبط الحقول التي تهمّك فقط، ويأتي الباقي من القيم الافتراضية. وتقوم Bind بتحميل YAML من متغير البيئة SERVER_CONFIG أولًا، ثم من ملف.

app := iris.New(iris.Options{Name: "myapp", LogLevel: "debug"})

أسماء تقول ما تفعله

لم تعد قراءة ترويسة الطلب وضبط ترويسة الاستجابة تتشاركان بادئة ينقلب معناها بصمت: ctx.Header تقرأ الطلب، بينما ctx.SetHeader وctx.ResponseHeader تعملان على الاستجابة. وParty صارت Router. وctx.URLParam صارت ctx.Query().Get. كل تغيير في التسمية مذكور في دليل الترحيل مع بديله، ومعظمها يحتاج عملية بحث واستبدال واحدة.

آمن افتراضيًا

تُرسل ملفات تعريف ارتباط الجلسات مع Secure وSameSite=Lax. ويُطبَّق حد حجم جسم الطلب على كل مسارات القراءة. ومع إعادة البناء سقطت أخطاء قديمة، من بينها محدِّد معدّل كان يسجّل الحدود دون أن يطبّقها أبدًا، واستدعاء Logout كان قادرًا على إسقاط العملية بأكملها.

توثيق يمكن قراءته من أوله إلى آخره

يأتي v14 مع كتاب من 23 فصلًا داخل المستودع، ودليل بدء عملي يبني واجهة REST مختبَرة في مستند واحد، ودليل ترحيل لتطبيقات v12، وويكي حيّ يعمل بالذكاء الاصطناعي مُولَّد من الشيفرة المصدرية يجيب عن أسئلتك حول قاعدة الشيفرة.

ماذا يعني هذا لشيفرتك على v12

يصبح مسار الاستيراد github.com/kataras/iris/v14، لذا يمكن لـ v12 و v14 التعايش جنبًا إلى جنب دون أن يتعطل شيء يوم الإصدار. رقِّ متى ما ناسبك. ويغطي دليل الترحيل مسار الاستيراد، وانتقال الحزم، وكل واجهة برمجية محذوفة وبديلها، والتغيّرات في السلوك، مع أوامر جاهزة للأجزاء الميكانيكية.

لا يوجد تاريخ إصدار معلن حتى الآن. تابع الإصدارات أو @iris_framework لتكون أول من يعرف.

👑 الداعمون

بدعمكم، سنتمكن معًا من الارتقاء بتطوير الويب مفتوح المصدر وجعله أفضل للجميع!

📖 تعلّم Iris

التثبيت

المتطلب الوحيد هو لغة البرمجة Go.

إنشاء مشروع جديد

$ mkdir myapp
$ cd myapp
$ go mod init myapp
$ go get github.com/kataras/iris/v12@latest # أو @v12.2.11

التثبيت على مشروع قائم

$ cd myapp
$ go get github.com/kataras/iris/v12@latest

$ go mod tidy -compat=1.23 # -compat="1.23" على ويندوز.
$ go run .

يحتوي Iris على وثائق شاملة ومفصّلة تسهّل عليك البدء باستخدام الإطار.

للاطلاع على توثيق تقني أكثر تفصيلًا، يمكنك زيارة godocs الخاص بنا. وللاطلاع على أمثلة قابلة للتنفيذ، يمكنك دائمًا زيارة المجلد الفرعي ./_examples في المستودع.

التطوير مع Plexon AI

Plexon AI مساعد برمجة يعمل بالذكاء الاصطناعي ومتعدد المنصّات من Hellenic Development، ويأتي مع مهارة (skill) مخصصة لـ Iris: دليل تطوير لـ v14 كتبه مؤلف الإطار نفسه، ويضم تسعة عشر مستند مرجع تغطي التوجيه والماكروات، وواجهة السياق (context API)، ودوال rest المساعدة، ومعالجة الأخطاء، والبرمجيات الوسيطة الثلاثين كلها، والمتحكمات المدمجة، وحزمة تطوير المصادقة، وتقوية الأمان، وتخزين البيانات، والتخزين المؤقت، والتوطين، وقابلية الملاحظة، والأداء، والاختبار، والنشر، والترحيل من v12 إلى v14.

ثبّت شخصية Software Developer فتأتي معها مهارة Iris، إلى جانب وكلاء الهندسة الذين تفعّلهم. عندها يكتب مساعدك شيفرة Iris بالطريقة التي صُمم الإطار ليُستخدم بها، بدلًا من التخمين اعتمادًا على ما صادفه أثناء التدريب.

هل تحب القراءة أثناء السفر؟

يمكنك طلب نسخة PDF والوصول عبر الإنترنت إلى الكتاب الإلكتروني لـ Iris (الإصدار الجديد) اليوم، والمساهمة في تطوير Iris.

🙌 المساهمة

نسعد برؤية مساهمتك في تطوير إطار عمل Iris! لمزيد من التفاصيل حول كيفية المساهمة، يُرجى الاطلاع على ملف CONTRIBUTING.md.

قائمة جميع المساهمين

🛡 الثغرات الأمنية

إذا اكتشفت ثغرة أمنية في Iris، يُرجى إرسال بريد إلكتروني إلى iris-go@outlook.com. سيتم التعامل مع جميع الثغرات الأمنية بسرعة.

📝 الرخصة

هذا المشروع مرخّص بموجب رخصة BSD بثلاثة بنود، تمامًا كحال مشروع Go نفسه.

اسم المشروع "Iris" مستوحى من الأساطير اليونانية.