hypersistence utils

الهجرة إلى الإصدار 3

تم تغيير اسم المشروع من Hibernate Types إلى Hypersistence Utils لأن نطاق المشروع أصبح أوسع بكثير الآن، ويقدم أدوات مساعدة Spring أيضًا.

لهذا السبب، عند الترحيل من Hibernate Types 2.x إلى Hypersistence Utils 3.x، ستحتاج إلى اتباع الخطوات التالية:

1. أولاً، ستحتاج إلى تغيير تبعية Maven أو Gradle، كما هو موضح في دليل التثبيت.
2. ثانيًا، ستحتاج إلى تغيير اسم الحزمة من com.vladmihalcea.hibernate إلى io.hypersistence.utils.hibernate .
3. ثالثًا، ستحتاج إلى تغيير اسم الحزمة من com.vladmihalcea.spring إلى io.hypersistence.utils.spring .

هذا كل شيء!

مقدمة

يمنحك مشروع Hypersistence Utils أدوات مساعدة للأغراض العامة لكل من Spring وHibernate.

الميزة الرئيسية لهذا المشروع هي أنه يدعم مجموعة واسعة من إصدارات Hibernate، بدءًا من Hibernate ORM 6.6 و 6.5 و 6.4 و 6.3 إلى 6.2 و 6.1 و 6.0 و 5.6 و Hibernate 5.5 .

دليل التثبيت

اعتمادا على إصدار السبات الذي تستخدمه، تحتاج إلى إضافة التبعية التالية:

السبات 6.6، 6.5، 6.4، و 6.3

 <dependency>
    <groupId>io.hypersistence</groupId>
    <artifactId>hypersistence-utils-hibernate-63</artifactId>
    <version>3.9.0</version>
</dependency>

السبات 6.2

 <dependency>
    <groupId>io.hypersistence</groupId>
    <artifactId>hypersistence-utils-hibernate-62</artifactId>
    <version>3.9.0</version>
</dependency>

السبات 6.1 و 6.0

 <dependency>
    <groupId>io.hypersistence</groupId>
    <artifactId>hypersistence-utils-hibernate-60</artifactId>
    <version>3.9.0</version>
</dependency>

السبات 5.6 و 5.5

 <dependency>
    <groupId>io.hypersistence</groupId>
    <artifactId>hypersistence-utils-hibernate-55</artifactId>
    <version>3.9.0</version>
</dependency>

تبعيات Maven الاختيارية

يحدد مشروع Hypersistence Utils قائمة بالتبعيات الاختيارية التي سيتعين عليك الإعلان عنها صراحةً في مشروعك حتى تتمكن من استخدامها.

السبب وراء كون كل هذه التبعيات اختيارية، مثل Guava أو Jackson أو PostgreSQL JDBC Driver، هو أنه ليست كل المشاريع قد تحتاج إليها.

علاوة على ذلك، فإن الإصدار التابع مهم للغاية لأنه، من وقت لآخر، قد يتم اكتشاف مشكلات أمنية يتم إصلاحها في الإصدارات الأحدث.

لذا، فإن الاعتماد على هذه المكتبة لتزويدك بالإصدارات التابعة يعد أمرًا خطيرًا للغاية.

على سبيل المثال، تم اكتشاف 65 مشكلة أمنية في مكتبة Jackson Data Bind التي يعتمد عليها هذا المشروع بشكل كبير.

لتجنب المخاطرة بمشكلات أمنية، يتعين عليك تحمل مسؤولية الترقية المستمرة لجميع التبعيات التي تستخدمها إلى جانب مكتبة Hypersistence Utils.

JSON تبعيات Maven الاختيارية

إذا كنت تستخدم أنواع JSON، فقد تكون مهتمًا بتعيين التبعيات التالية بناءً على إصدار السبات الخاص بك:

السبات 6

< dependency >
    < groupId >com.fasterxml.jackson.module</ groupId >
    < artifactId >jackson-module-jakarta-xmlbind-annotations</ artifactId >
    < version >${jackson-module-jakarta-xmlbind-annotation}</ version >
</ dependency >

السبات 5

< dependency >
    < groupId >com.fasterxml.jackson.core</ groupId >
    < artifactId >jackson-databind</ artifactId >
    < version >${jackson-databind.version}</ version >
</ dependency >

< dependency >
    < groupId >com.fasterxml.jackson.module</ groupId >
    < artifactId >jackson-module-jaxb-annotations</ artifactId >
    < version >${jackson-module-jaxb-annotation}</ version >
</ dependency >

الجوافة التبعية الاختيارية Maven

إذا كنت تقوم بتعيين Range باستخدام Guava، فيجب عليك توفير تبعية Guava بشكل صريح:

< dependency >
    < groupId >com.google.guava</ groupId >
    < artifactId >guava</ artifactId >
    < version >${guava.version}</ version >
</ dependency >

جافا المال والعملة API التبعية الاختيارية Maven

إذا كنت تقوم بتعيين MonetaryAmount ، فيجب عليك توفير تبعية Moneta بشكل صريح:

< dependency >
    < groupId >org.javamoney</ groupId >
    < artifactId >moneta</ artifactId >
    < version >${moneta.version}</ version >
    < type >pom</ type >
</ dependency >

PostgreSQL تبعية Maven الاختيارية

إذا كنت تقوم بتعيين نوع عمود خاص بـ PostgreSQL (على سبيل المثال، inet ، hstore ، array ، interval ) ، فيجب عليك توفير تبعية PostgreSQL بشكل صريح:

< dependency >
    < groupId >org.postgresql</ groupId >
    < artifactId >postgresql</ artifactId >
    < version >${postgresql.version}</ version >
</ dependency >

سمات

JSON

نوع JSON عام

يسمح لك JsonType بتعيين أنواع أعمدة JSON، بغض النظر عما إذا كنت تستخدم Oracle أو SQL Server أو PostgreSQL أو MySQL.

السبات 6

إذا كنت تستخدم Hibernate 6، فيمكنك تعيين أي عمود JSON إلى خاصية كيان Map أو List أو POJO أو String أو JsonNode :

 @ Type ( JsonType . class )
private Map < String , String > properties = new HashMap <>();

السبات 5

إذا كنت تستخدم Hibernate 5، فيمكنك إما تقديم الاسم المؤهل بالكامل لنوع Hibernate:

 @Type(type = "io.hypersistence.utils.hibernate.type.json.JsonType")

أو يمكنك إضافة التعيين التالي إلى فئة package-info.java الخاصة بك في نفس الحزمة التي توجد بها كيانات JPA الخاصة بك:

 @ TypeDef (
    name = "json" , typeClass = JsonType . class
)
package io . hypersistence . optimizer ;

import io . hypersistence . utils . hibernate . type . json . JsonType ;
import org . hibernate . annotations . TypeDef ;

لاحقًا، يمكنك تعيين خصائص الكيان Map أو List أو POJO أو String أو JsonNode إلى أعمدة JSON مثل هذا:

 @ Type ( type = "json" )
private Map < String , String > properties = new HashMap <>();

لمزيد من التفاصيل، راجع هذه المقالة.

أفضل الممارسات

عند تعيين نوع عمود JSON إلى POJO أو List<POJO> أو Map<String, POJO> ، فإنك تحتاج إلى التأكد من أن نوع POJO يتجاوز أساليب equals الافتراضية و hashCode وينفذها وفقًا لمحتوى كائن JSON.

وإلا، فقد تؤدي آلية التحقق من الإسبات إلى تشغيل عبارات UPDATE غير متوقعة. راجع العدد رقم 134 للمزيد من التفاصيل.

أنواع JSON الخاصة بقاعدة البيانات

أوراكل

عند استخدام Oracle، لديك عدة خيارات:

• يمكنك استخدام JsonType العام الذي يمكنه العمل مع أنواع الأعمدة JSON أو VARCHAR أو BLOB ، طالما أنك تلمح إلى نوع العمود باستخدام سمة columnDefinition الخاصة بالتعليق التوضيحي JPA @Column .
• يمكنك استخدام JsonStringType لتعيين نوع عمود VARCHAR2 لتخزين JSON.
• يمكنك استخدام JsonBlobType لتعيين نوع عمود BLOB لتخزين JSON.

لمزيد من التفاصيل، راجع هذه المقالة.

خادم SQL

عند استخدام SQL Server، يمكنك استخدام JsonType العام أو JsonStringType لتعيين نوع عمود NVARCHAR الذي يخزن JSON.

لمزيد من التفاصيل، راجع هذه المقالة.

PostgreSQL

عند استخدام PostgreSQL، يمكنك استخدام JsonType العام أو JsonBinaryType لتعيين نوعي الأعمدة jsonb و json .

لمزيد من التفاصيل، راجع هذه المقالة.

ماي إس كيو إل

عند استخدام MySQL، يمكنك استخدام JsonType العام أو JsonStringType لتعيين نوع العمود json .

لمزيد من التفاصيل، راجع هذه المقالة.

أمثلة لرسم خرائط JSON

• كيفية تعيين POJO إلى عمود JSON باستخدام JPA وHbernate
• كيفية تعيين خاصية String JPA إلى عمود JSON باستخدام Hibernate
• كيفية تعيين Jackson JsonNode إلى عمود JSON
• كيفية تعيين مجموعات JSON باستخدام JPA وHbernate
• كيفية تعيين خاصية كيان Java Map كعمود JSON باستخدام JPA وHibernate
• كيفية تعيين سجلات Java إلى أعمدة JSON باستخدام Hibernate
• كيفية تعيين كائنات JSON متعددة الأشكال باستخدام JPA وHbernate
• كيفية تشفير وفك تشفير خصائص JSON باستخدام JPA وHbernate
• لماذا يجب عليك استخدام Hibernate Dynamic Update لخصائص JSON
• كيفية تعيين أعمدة Oracle JSON باستخدام JPA وHbernate
• كيفية تعيين أعمدة SQL Server JSON باستخدام JPA وHbernate
• كيفية تخصيص Jackson ObjectMapper الذي تستخدمه Hypersistence Utils
• كيفية تخصيص JSON Serializer الذي تستخدمه Hypersistence Utils
• كيفية إصلاح No Dialect mapping for JDBC type: 1111 عند خلط أنواع JSON مع استعلامات SQL الأصلية
• كيفية إصلاح column is of type jsonb but expression is of type record أو مشكلة bytea

صفيف

• كيفية تعيين PostgreSQL ARRAY إلى List Java باستخدام JPA وHbernate
• كيفية تعيين PostgreSQL ARRAY إلى Java Arrays باستخدام JPA وHbernate
• رسم خرائط مصفوفة متعددة الأبعاد باستخدام JPA وHbernate
• كيفية تعيين نوع HSQLDB ARRAY باستخدام JPA وHbernate

أنواع PostgreSQL (مثل ENUM وINET وHSTORE وRANGE)

• Java Enum إلى نوع PostgreSQL Enum
• كيفية تعيين نوع PostgreSQL Inet باستخدام JPA وHbernate
• كيفية تعيين خاصية كيان PostgreSQL HStore باستخدام JPA وHbernate
• كيفية تعيين PostgreSQL Enum ARRAY إلى خاصية كيان JPA باستخدام Hibernate
• كيفية تعيين نوع عمود نطاق PostgreSQL باستخدام JPA وHbernate
• كيفية تعيين الفاصل الزمني لـ PostgreSQL إلى Duration Java باستخدام السبات

أنواع عامة

• أفضل طريقة لتعيين MonetaryAmount باستخدام JPA وHbernate
• كيفية تعيين java.time.YearMonth إلى عمود DATE أو INTEGER
• كيفية تعيين java.time.Year و java.time.Month باستخدام JPA وHbernate
• Character إلى عمود CHAR لاغٍ
• الأداة المساعدة ImmutableType لتبسيط عمليات تنفيذ UserType

المرافق

ربيع

• مستودع BaseJpa الرائع
• أفضل مستودع بيانات الربيع Jpa
• findAll بيانات الربيع جميع الأنماط المضادة
• التعليق التوضيحي @Retry لإعادة المحاولة تلقائيًا عند الفشل

BaseJpaRepository

يعد BaseJpaRepository بديلاً أفضل بكثير لـ Spring Data JpaRepository الافتراضي لأنه لا يوفر طريقة findAll أو طريقة save لا معنى لها في مصطلحات JPA.

لاستخدام الأداة المساعدة BaseJpaRepository ، تأكد من توفير سمة repositoryBaseClass في تكوين @EnableJpaRepositories للإشارة إلى BaseJpaRepositoryImpl من مشروع Hypersistence Utils:

 @ Configuration
@ EnableJpaRepositories (
    value = "your.repository.package" ,
    repositoryBaseClass = BaseJpaRepositoryImpl . class
)
public class JpaConfiguration {
    ...
}

your.repository.package هي حزمة Java لمستودعات Spring الخاصة بك.

HibernateRepository

على الرغم من تفضيل BaseJpaRepository ، إذا كنت بحاجة إلى استخدام JpaRepository الافتراضي، فيمكنك على الأقل توسيع HibernateRepository أيضًا لإهمال الأساليب التي قد تسبب مشاكل.

لاستخدام HibernateRepository ، تأكد من تضمين الحزمة io.hypersistence.utils.spring.repository في تكوين @EnableJpaRepositories الخاص بك:

 @ Configuration
@ EnableJpaRepositories (
    value = {
        "io.hypersistence.utils.spring.repository" ,
        "your.repository.package" ,
        ...
    }
)
public class JpaConfiguration {
    ...
}

your.repository.package هي حزمة Java لمستودعات Spring الخاصة بك.

مولدات الهوية

• BatchSequenceGenerator - مولد تسلسل الدفعات السبات

استراتيجية التسمية

• CamelCaseToSnakeCaseNamingStrategy - كيفية تعيين خصائص CamelCase لأسماء أعمدة Snake_case باستخدام Hibernate

إسقاط DTO ومحول النتائج

• ClassImportIntegrator - كيفية كتابة استعلام إسقاط DTO مضغوط باستخدام JPA
• ListResultTransformer - أفضل طريقة لاستخدام Hibernate ResultTransformer
• MapResultTransformer - كيفية إرجاع نتيجة الخريطة من استعلام JPA أو Hibernate

مدقق عدد بيان SQL

• SQLStatementCountValidator - كيفية اكتشاف مشكلة استعلام Hibernate N+1 أثناء الاختبار

أدوات الاستعلام

• SQLExtract - كيفية الحصول على استعلام SQL من معايير JPQL أو JPA
• QueryStackTraceLogger - كيفية العثور على مصدر استعلام SQL الذي تم إنشاؤه بواسطة Hibernate

متطلبات

• إصدار Java مدعوم بإصدار Hibernate ORM الذي تستخدمه.
• SLF4J
• جاكسون Databind

إصلاحات الشوائب والتحسينات

هذا المشروع مجاني، كما هو الحال في Libre، وليس مجانيًا.

لا يوجد دعم مجاني. فقط الكود المصدري والثنائيات متاحة مجانًا.

إذا كنت بحاجة إلى مساعدة بشأن مشكلة معينة، فستحتاج إلى شراء برنامج Coaching Basic أو برنامج Coaching Pro.

توفير الإصلاح الخاص بك

إلى جانب خيارات الدعم المدفوعة، لديك خيار توفير الإصلاح الخاص بك. ومن أجل ذلك، إليك ما عليك القيام به:

1. قم بتوفير حالة اختبار متكررة باستخدام حالات الاختبار الموجودة كقالب
2. تقديم اقتراح الإصلاح
3. أرسل طلب سحب مع اقتراح الإصلاح وحالة الاختبار

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

هل تعاني من مشاكل في أداء التطبيق؟

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

تخيل أنك اكتشفت مبكرًا أثناء دورة التطوير أنك تستخدم تعيينات وعلاقات كيانات دون المستوى الأمثل أو أنك تفتقد الإعدادات المتعلقة بالأداء.

علاوة على ذلك، باستخدام Hypersistence Optimizer، يمكنك اكتشاف كل هذه المشكلات أثناء الاختبار والتأكد من عدم نشر تغيير في الإنتاج من شأنه أن يؤثر على أداء طبقة الوصول إلى البيانات.

Hypersistence Optimizer هي الأداة التي طالما انتظرتها!

تمرين

إذا كنت مهتمًا بالتدريب في الموقع، فيمكنني أن أقدم لك تدريب Java Persistence عالي الأداء، والذي يمكن تكييفه لمدة يوم أو يومين أو ثلاثة أيام من الجلسات. لمزيد من التفاصيل، راجع موقع الويب الخاص بي.

استشارات

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

دورات فيديو عالية الأداء لثبات Java

إذا كنت تريد أسرع طريقة لتعلم كيفية تسريع تطبيق قاعدة بيانات Java، فيجب عليك بالتأكيد التسجيل في دورات الفيديو الخاصة بـ Java Persistence عالية الأداء.

كتاب ثبات جافا عالي الأداء

أو، إذا كنت تفضل قراءة الكتب، فسوف تحب كتابي High-Performance Java Persistence أيضًا.

دليل المساهمة

يستخدم المشروع Maven Toolchains حيث يتم تجميع وحدات مختلفة واختبارها باستخدام إصدارات Java مختلفة.

يتطلب Hypersistence Utils 6 وجود Java 11 بينما يتم تجميع الوحدات الأخرى باستخدام Java 8.

لمعرفة كيفية تكوين Maven Toolchains، راجع هذه المقالة.

يستخدم المشروع أنظمة قواعد بيانات مختلفة لاختبار التكامل، ويمكنك تكوين إعدادات اتصال JDBC باستخدام مثيلات DatasourceProvider (على سبيل المثال، PostgreSQLDataSourceProvider )، ويستخدم المشروع Testcontainers لتشغيل حاوية Docker باستخدام Oracle أو SQL Server أو PostgreSQL أو MySQL المطلوبة. المثال عند الطلب.

إذا كنت مساهمًا منتظمًا، فمن المستحسن إعداد قاعدة البيانات المطلوبة محليًا أو استخدام تكوين Docker Compose المتوفر في مجلد docker ، حيث أن تمهيد الحاويات عند الطلب يكون أبطأ، وستستغرق اختباراتك وقتًا أطول للتشغيل.

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