spring-cloud__spring-cloud-gateway_CVE-2022-22947_3-0-6

//// لا تقم بتحرير هذا الملف. لقد تم إنشاؤه آلياً. سيتم فقدان التغييرات اليدوية لهذا الملف عند إعادة إنشائه. قم بتحرير الملفات الموجودة في مجلد src/main/asciidoc/ بدلاً من ذلك. ////

image::https://circleci.com/gh/spring-cloud/spring-cloud-gateway/tree/master.svg?style=svg["CircleCI", link="https://circleci.com/gh/spring-cloud/spring-cloud-gateway/tree/master"] image::https://codecov.io/gh/spring-cloud/spring-cloud-gateway/branch/master/graph/badge.svg["Codecov", link="https://codecov.io/gh/spring-cloud/spring-cloud-gateway/branch/master"] image::https://api.codacy.com/project/badge/Grade/a6885a06921e4f72a0df0b7aabd6d118["Codacy code quality", link="https://www.codacy.com/app/spring-cloud/spring-cloud-gateway?utm_source=github.com&utm_medium=referral&utm_content=spring-cloud/spring-cloud-gateway&utm_campaign=Badge_Grade"]

هذا المشروع يوفر بوابة API (API Gateway) مبنية فوق نظام Spring البيئي، وتشمل: Spring 5 وSpring Boot 2 وProject Reactor. تهدف Spring Cloud Gateway إلى توفير طريقة بسيطة وفعالة لتوجيه الطلبات إلى واجهات برمجة التطبيقات (APIs) وتقديم خدمات عرضية لها مثل: الأمان والمراقبة/المقاييس والمرونة.

== الميزات

• Java 8
• Spring Framework 5
• Spring Boot 2
• توجيه ديناميكي
• مطابقة المسار مدمجة في Spring Handler Mapping
• مطابقة المسار على أساس طلب HTTP (المسار، الطريقة، الرأس، المضيف، إلخ)
• عوامل تصفية (Filters) مقيدة بالمسار المطابق
• يمكن لعوامل التصفية تعديل طلب HTTP الوارد واستجابة HTTP الصادرة (إضافة/إزالة الرؤوس، إضافة/إزالة المعاملات، إعادة كتابة المسار، تعيين المسار، Hystrix، إلخ)
• يعمل بواجهة برمجة تطبيقات (API) أو عن طريق التهيئة
• يدعم DiscoveryClient من Spring Cloud لتكوين المسارات

== البناء

:jdkversion: 1.8

=== التجميع الأساسي والاختبار

لبناء المصدر، ستحتاج إلى تثبيت JDK {jdkversion}.

يستخدم Spring Cloud أداة Maven لمعظم أنشطة البناء، ويجب أن تكون قادراً على البدء بسرعة عن طريق استنساخ المشروع الذي تهتم به وكتابة:

$ ./mvnw install

ملاحظة: يمكنك أيضاً تثبيت Maven (>=3.3.3) بنفسك وتشغيل الأمر mvn بدلاً من ./mvnw في الأمثلة أدناه. إذا قمت بذلك، فقد تحتاج أيضاً إلى إضافة -P spring إذا كانت إعدادات Maven المحلية لديك لا تحتوي على تعريفات المستودعات للقطع الأثرية ما قبل الإصدار من Spring.

ملاحظة: كن على علم أنك قد تحتاج إلى زيادة مقدار الذاكرة المتاحة لـ Maven عن طريق تعيين متغير بيئة MAVEN_OPTS بقيمة مثل -Xmx512m -XX:MaxPermSize=128m. نحاول تغطية ذلك في إعدادات .mvn، لذا إذا وجدت أنك مضطر للقيام بذلك لنجاح البناء، فيرجى رفع تذكرة لإضافة الإعدادات إلى التحكم في المصدر.

المشاريع التي تتطلب برمجيات وسيطة (مثل Redis) للاختبار تتطلب عموماً تثبيت وتشغيل نسخة محلية من Docker.

=== التوثيق

وحدة spring-cloud-build تحتوي على ملف تعريف "docs"، وإذا قمت بتفعيله، سيحاول بناء مصادر asciidoc من src/main/asciidoc. كجزء من هذه العملية، سيبحث عن ملف README.adoc ويعالجه عن طريق تحميل جميع التضمينات، ولكن دون تحليله أو عرضه، فقط نسخه إلى ${main.basedir} (الافتراضي هو ${basedir}، أي جذر المشروع). إذا حدثت أي تغييرات في README، فستظهر بعد بناء Maven كملف معدّل في المكان الصحيح. فقط قم بتنفيذ الالتزام (commit) وادفع التغيير.

=== العمل مع الكود إذا لم تكن لديك تفضيلات لبيئة تطوير متكاملة (IDE)، نوصي باستخدام https://www.springsource.com/developer/sts[Spring Tools Suite] أو https://eclipse.org[Eclipse] عند العمل مع الكود. نستخدم إضافة https://eclipse.org/m2e/[m2eclipse] في Eclipse لدعم Maven. يجب أن تعمل بيئات التطوير والأدوات الأخرى أيضاً دون مشاكل طالما تستخدم Maven 3.3.3 أو أفضل.

==== تفعيل ملف تعريف Maven الخاص بـ Spring تتطلب مشاريع Spring Cloud تفعيل ملف تعريف Maven "spring" لحل مستودعات الإصدارات التجريبية والإصدارات اللحظية من Spring. استخدم بيئة التطوير المفضلة لديك لتعيين هذا الملف التعريفي كفعال، وإلا قد تواجه أخطاء في البناء.

==== الاستيراد إلى Eclipse باستخدام m2eclipse نوصي بإضافة https://eclipse.org/m2e/[m2eclipse] في Eclipse عند العمل مع Eclipse. إذا لم يكن m2eclipse مثبتاً لديك بالفعل، فهو متاح من "سوق Eclipse".

ملاحظة: الإصدارات القديمة من m2e لا تدعم Maven 3.3، لذا بمجرد استيراد المشاريع إلى Eclipse، ستحتاج أيضاً إلى إخبار m2eclipse باستخدام الملف التعريفي الصحيح للمشاريع. إذا رأيت العديد من الأخطاء المختلفة المتعلقة بملفات POM في المشاريع، تحقق من أن لديك تثبيتاً محدّثاً. إذا لم تتمكن من ترقية m2e، أضف ملف التعريف "spring" إلى ملف settings.xml الخاص بك. بدلاً من ذلك، يمكنك نسخ إعدادات المستودع من ملف التعريف "spring" في ملف pom الرئيسي إلى ملف settings.xml الخاص بك.

==== الاستيراد إلى Eclipse بدون m2eclipse إذا كنت تفضل عدم استخدام m2eclipse، يمكنك إنشاء بيانات تعريف مشروع Eclipse باستخدام الأمر التالي:

[indent=0]

$ ./mvnw eclipse:eclipse

يمكن استيراد مشاريع Eclipse المُنشأة عن طريق اختيار import existing projects من قائمة file.

== المساهمة

:spring-cloud-build-branch: master

تم إصدار Spring Cloud بموجب ترخيص Apache 2.0 غير المقيد، ويتبع عملية تطوير قياسية على Github، باستخدام متتبع Github للمشكلات ودمج طلبات السحب (pull requests) إلى master. إذا كنت ترغب في المساهمة حتى بأمر بسيط، فلا تتردد، ولكن اتبع الإرشادات أدناه.

=== توقيع اتفاقية المساهمة (Contributor License Agreement) قبل قبول أي تصحيح أو طلب سحب غير بسيط، سنحتاج منك توقيع https://cla.pivotal.io/sign/spring[اتفاقية المساهمة (CLA)]. توقيع اتفاقية المساهم لا يمنح أي شخص حقوق الالتزام (commit) في المستودع الرئيسي، ولكنه يعني أنه يمكننا قبول مساهماتك، وستحصل على سمة المؤلف إذا فعلنا ذلك. قد يُطلب من المساهمين النشطين الانضمام إلى الفريق الأساسي، ومنحهم القدرة على دمج طلبات السحب.

=== مدونة السلوك يلتزم هذا المشروع بـ https://github.com/spring-cloud/spring-cloud-build/blob/master/docs/src/main/asciidoc/code-of-conduct.adoc[مدونة السلوك] الخاصة بـ Contributor Covenant. من خلال المشاركة، يُتوقع منك الالتزام بهذه المدونة. يرجى الإبلاغ عن السلوك غير المقبول إلى [email protected].

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

• استخدم اصطلاحات تنسيق كود Spring Framework. إذا كنت تستخدم Eclipse، يمكنك استيراد إعدادات المنسق باستخدام ملف eclipse-code-formatter.xml من مشروع https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/master/spring-cloud-dependencies-parent/eclipse-code-formatter.xml[Spring Cloud Build]. إذا كنت تستخدم IntelliJ، يمكنك استخدام https://plugins.jetbrains.com/plugin/6546[إضافة Eclipse Code Formatter] لاستيراد نفس الملف.
• تأكد من أن جميع ملفات .java الجديدة تحتوي على تعليق Javadoc بسيط للفئة مع علامة @author على الأقل تحدد هويتك، ويفضل أن يكون هناك فقرة واحدة على الأقل حول الغرض من الفئة.
• أضف تعليق رأس ترخيص ASF إلى جميع ملفات .java الجديدة (انسخ من الملفات الموجودة في المشروع).
• أضف نفسك كـ @author في ملفات .java التي تعدلها بشكل جوهري (أكثر من تغييرات تجميلية).
• أضف بعض Javadocs، وإذا قمت بتغيير مساحة الاسم، أضف بعض عناصر توثيق XSD.
• بضع اختبارات وحدة ستساعد كثيراً أيضاً – يجب على شخص ما القيام بها.
• إذا لم يكن أي شخص آخر يستخدم فرعك، فيرجى إعادة تأسيسه (rebase) على أساس master الحالي (أو فرع هدف آخر في المشروع الرئيسي).
• عند كتابة رسالة الالتزام (commit message)، يرجى اتباع https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html[هذه الاصطلاحات]، إذا كنت تصلح مشكلة موجودة، يرجى إضافة Fixes gh-XXXX في نهاية رسالة الالتزام (حيث XXXX هو رقم المشكلة).

=== Checkstyle

يأتي Spring Cloud Build مع مجموعة من قواعد checkstyle. يمكنك العثور عليها في وحدة spring-cloud-build-tools. الملفات الأكثر بروزاً تحت الوحدة هي:

.spring-cloud-build-tools/

└── src    ├── checkstyle    │   └── checkstyle-suppressions.xml <3>    └── main    └── resources    ├── checkstyle-header.txt <2>    └── checkstyle.xml <1>

<1> قواعد Checkstyle الافتراضية <2> إعداد رأس الملف <3> قواعد الإلغاء الافتراضية

==== تهيئة Checkstyle

قواعد Checkstyle معطلة افتراضياً. لإضافة checkstyle إلى مشروعك، فقط حدد الخصائص والإضافات التالية.

.pom.xml

<reporting>
    <plugins>
        <plugin> <5>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-checkstyle-plugin</artifactId>
        </plugin>
    </plugins>
</reporting>

إذا كنت بحاجة إلى إلغاء بعض القواعد (مثل طول السطر يحتاج إلى أن يكون أطول)، فما عليك سوى تعريف ملف تحت ${project.root}/src/checkstyle/checkstyle-suppressions.xml مع عمليات الإلغاء الخاصة بك. مثال:

.projectRoot/src/checkstyle/checkstyle-suppresions.xml

يُنصح بنسخ ${spring-cloud-build.rootFolder}/.editorconfig و ${spring-cloud-build.rootFolder}/.springformat إلى مشروعك. بهذه الطريقة، سيتم تطبيق بعض قواعد التنسيق الافتراضية. يمكنك القيام بذلك عن طريق تشغيل هذا السكريبت:

$ curl https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/master/.editorconfig -o .editorconfig
$ touch .springformat

=== إعداد بيئة التطوير (IDE)

==== Intellij IDEA

من أجل إعداد Intellij، يجب عليك استيراد اصطلاحات الترميز الخاصة بنا، وملفات تعريف الفحص (inspection profiles)، وإعداد إضافة checkstyle. يمكن العثور على الملفات التالية في مشروع https://github.com/spring-cloud/spring-cloud-build/tree/master/spring-cloud-build-tools[Spring Cloud Build].

.spring-cloud-build-tools/

└── src    ├── checkstyle    │   └── checkstyle-suppressions.xml <3>    └── main    └── resources    ├── checkstyle-header.txt <2>    ├── checkstyle.xml <1>    └── intellij       ├── Intellij_Project_Defaults.xml <4>       └── Intellij_Spring_Boot_Java_Conventions.xml <5>

<1> قواعد Checkstyle الافتراضية <2> إعداد رأس الملف <3> قواعد الإلغاء الافتراضية <4> الإعدادات الافتراضية للمشروع في Intellij والتي تطبق معظم قواعد Checkstyle <5> اصطلاحات نمط المشروع في Intellij والتي تطبق معظم قواعد Checkstyle

.نمط الكود

image::https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/{spring-cloud-build-branch}/docs/src/main/asciidoc/images/intellij-code-style.png[نمط الكود]

اذهب إلى File -> Settings -> Editor -> Code style. هناك انقر على الأيقونة بجانب قسم Scheme. هناك، انقر على قيمة Import Scheme واختر خيار Intellij IDEA code style XML. استورد ملف spring-cloud-build-tools/src/main/resources/intellij/Intellij_Spring_Boot_Java_Conventions.xml.

.ملفات تعريف الفحص

image::https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/{spring-cloud-build-branch}/docs/src/main/asciidoc/images/intellij-inspections.png[نمط الكود]

اذهب إلى File -> Settings -> Editor -> Inspections. هناك انقر على الأيقونة بجانب قسم Profile. هناك، انقر على Import Profile واستورد ملف spring-cloud-build-tools/src/main/resources/intellij/Intellij_Project_Defaults.xml.

.Checkstyle

لكي يعمل Intellij مع Checkstyle، يجب عليك تثبيت إضافة Checkstyle. يُنصح أيضاً بتثبيت Assertions2Assertj لتحويل تأكيدات JUnit تلقائياً.

image::https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/{spring-cloud-build-branch}/docs/src/main/asciidoc/images/intellij-checkstyle.png[Checkstyle]

اذهب إلى File -> Settings -> Other settings -> Checkstyle. هناك انقر على أيقونة + في قسم Configuration file. هناك، ستحتاج إلى تحديد من أين يتم جلب قواعد checkstyle. في الصورة أعلاه، اخترنا القواعد من مستودع Spring Cloud Build المُستنسخ. ومع ذلك، يمكنك الإشارة إلى مستودع Spring Cloud Build على GitHub (على سبيل المثال، لملف checkstyle.xml: https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/master/spring-cloud-build-tools/src/main/resources/checkstyle.xml). نحتاج إلى توفير المتغيرات التالية:

• checkstyle.header.file - يرجى الإشارة إلى ملف spring-cloud-build-tools/src/main/resources/checkstyle-header.txt الخاص بـ Spring Cloud Build، سواء في مستودعك المُستنسخ أو عبر رابط URL https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/master/spring-cloud-build-tools/src/main/resources/checkstyle-header.txt.
• checkstyle.suppressions.file - عمليات الإلغاء الافتراضية. يرجى الإشارة إلى ملف spring-cloud-build-tools/src/checkstyle/checkstyle-suppressions.xml الخاص بـ Spring Cloud Build، سواء في مستودعك المُستنسخ أو عبر رابط URL https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/master/spring-cloud-build-tools/src/checkstyle/checkstyle-suppressions.xml.
• checkstyle.additional.suppressions.file - هذا المتغير يتوافق مع عمليات الإلغاء في مشروعك المحلي. على سبيل المثال، تعمل على spring-cloud-contract. ثم أشر إلى مجلد project-root/src/checkstyle/checkstyle-suppressions.xml. مثال لـ سيكون: .

هام: تذكر تعيين Scan Scope إلى All sources لأننا نطبق قواعد checkstyle على مصادر الإنتاج والاختبار.

=== مكتشف التكرارات (Duplicate Finder)

يجلب Spring Cloud Build إضافة basepom:duplicate-finder-maven-plugin، التي تتيح الكشف عن الفئات والموارد المكررة والمتضاربة في مسار فئة Java.

==== تهيئة مكتشف التكرارات

مكتشف التكرارات مفعل افتراضياً وسيعمل في مرحلة verify من بناء Maven الخاص بك، ولكنه لن يؤثر إلا في مشروعك إذا أضفت duplicate-finder-maven-plugin إلى قسم build في ملف pom.xml الخاص بالمشروع.

.pom.xml [source,xml]

بالنسبة للخصائص الأخرى، قمنا بتعيين القيم الافتراضية كما هو مدرج في https://github.com/basepom/duplicate-finder-maven-plugin/wiki[توثيق الإضافة].

يمكنك بسهولة تجاوزها عن طريق تعيين قيمة الخاصية المحددة مسبوقة بـ duplicate-finder-maven-plugin. على سبيل المثال، قم بتعيين duplicate-finder-maven-plugin.skip إلى true لتخطي فحص التكرارات في البناء الخاص بك.

إذا كنت بحاجة إلى إضافة ignoredClassPatterns أو ignoredResourcePatterns إلى إعداداتك، تأكد من إضافتها في قسم تكوين الإضافة في مشروعك:

[source,xml]