دليل تكامل SDK للضغط: استدعاء بعدة لغات Python/Java/C#

خلاصة سريعة: تُصدِّر SDK من SmartSlim لـ UGLYPEAR DATA مكتبة ديناميكية عبر C ABI القياسي، وتدعم التكامل بأربع لغات هي Python/Java/C#/Rust، وسير الاستدعاء الأساسي يتكون من أربع خطوات: تهيئة SDK، إنشاء إعدادات الضغط، تنفيذ الضغط، تحرير الموارد. يستغرق ضغط ملف PDF واحد بحجم 100 ميجابايت نحو 0.8 ثانية، وزمن التحقق من الترخيص أقل من 5 مللي ثانية. تعرض هذه المقالة أمثلة كود تكامل كاملة بثلاث لغات، وجدول معاملات API، وحلول ضبط الأداء، مع عرض تجريبي للضغط الدفعي. سنبدأ ببنية SDK، ثم نشرح طرق تكامل كل لغة بالتفصيل.

إذا كنت تحتاج إلى استدعاء خدمة الضغط عبر واجهة HTTP بدلاً من تكامل SDK، يُنصح أولاً بقراءة تطبيق عملي لواجهة برمجة الضغط (API): شرح مفصّل لوثائق واجهة RESTful.

أولًا: بنية SDK ومبادئ التكامل

الطبقة الأساسية لـ SmartSlim SDK هي محرك ضغط مكتوب بـ Rust، يتم تصديره عبر C ABI (Application Binary Interface) القياسي كمكتبة ديناميكية (.so/.dylib/.dll)، ويمكن لأي لغة تدعم FFI (واجهة الدوال الأجنبية) تحميلها واستدعاءها. تكمن فائدة هذه البنية في: كتابة المحرك الأساسي مرة واحدة بـ Rust، وإعادة استخدام نفس المكتبة الثنائية عبر عدة لغات، دون الحاجة إلى تكرار تنفيذ منطق الضغط في كل لغة.

المكوّن	التقنية	الدور	المخرجات
نواة محرك الضغط	Rust	تنفيذ خوارزمية الضغط	مكتبة ثابتة .a/.lib
طبقة تصدير ABI	Rust #[no_mangle]	تصدير دوال متوافقة مع C	مكتبة ديناميكية .so/.dylib/.dll
طبقة ربط اللغة	FFI لكل لغة	تغليف الاستدعاءات الأصلية	حزم/مكتبات خاصة بكل لغة
وحدة الترخيص	Rust + تشفير	التحقق من مفتاح الترخيص	مدمج في المكتبة الديناميكية
إدارة الإعدادات	Rust struct	إدارة معاملات الضغط	إعدادات JSON/TOML

توفّر SDK مكتبات مُجمَّعة مسبقًا لـ 6 منصات، تغطي أنظمة التشغيل وبنى المعالجات الرئيسية، وتعمل مباشرة دون الحاجة إلى ترجمة كود Rust.

المنصة	المكتبة الديناميكية	نظام التشغيل	بنية المعالج	سيناريو الاستخدام
linux-x64	libsmartslim.so	Linux	x86_64	الخادم/سطح المكتب
linux-arm64	libsmartslim.so	Linux	aarch64	خوادم ARM/Raspberry Pi
macos-universal	libsmartslim.dylib	macOS	x86_64+arm64	Intel + Apple Silicon
windows-x64	smartslim.dll	Windows	x86_64	سطح المكتب/خوادم Windows
linux-server-x64	libsmartslim.so	Linux	x86_64	إصدار الخادم المحسّن
linux-server-arm64	libsmartslim.so	Linux	aarch64	إصدار خوادم ARM المحسّن

ثانيًا: شرح مفصّل لمعاملات API الأساسية

تنقسم واجهات API الأساسية في SDK إلى أربع فئات: التهيئة، الإعدادات، الضغط، التحرير. يعرض الجدول التالي دوال API الرئيسية ووصف معاملاتها.

دالة API	المعاملات	القيمة المُعادة	الوصف
smartslim_init	license_key: String	handle: Handle	تهيئة SDK والتحقق من الترخيص
smartslim_create_config	format, level, quality	config: ConfigHandle	إنشاء إعدادات الضغط
smartslim_compress	handle, input, output, config	result: ResultCode	تنفيذ ضغط ملف واحد
smartslim_compress_batch	handle, files[], config, workers	results[]: ResultCode	ضغط دفعي (متعدد التزامن)
smartslim_get_info	handle, filepath	FileInfo: struct	الحصول على معلومات ضغط الملف
smartslim_free_config	config: ConfigHandle	void	تحرير موارد الإعدادات
smartslim_free	handle: Handle	void	تحرير نسخة SDK

تدعم معاملات إعدادات الضغط 4 مستويات ضغط (low/medium/high/ultra) × 15 سيناريو × 5 درجات أداء (ultrafast/fast/balanced/quality/optimal)، بإجمالي 300 تركيبة، تغطي تقريبًا جميع متطلبات الضغط.

المعامل	القيم المتاحة	القيمة الافتراضية	الوصف
format	pdf/image/video/office/ofd	كشف تلقائي	نوع الملف
level	low/medium/high/ultra	medium	مستوى الضغط
quality	1-100	75	عامل الجودة (للصور/PDF)
performance	ultrafast/fast/balanced/quality/optimal	balanced	درجة الأداء
workers	1-16	4	عدد خيوط التزامن
security	DISABLED/LOW/MEDIUM/HIGH/MAXIMUM	MEDIUM	مستوى الأمان

ثالثًا: أمثلة كود تكامل بثلاث لغات

فيما يلي أمثلة تكامل كاملة بثلاث لغات: Python وJava وC#، جميعها تتناول ضغط ملف PDF واحد.

1. تكامل Python (ctypes)

تحمّل Python المكتبة الديناميكية عبر وحدة ctypes وتستدعي الدوال المُصدَّرة. ينفّذ الكود التالي سير العمل الكامل: تهيئة SDK، إنشاء الإعدادات، ضغط PDF، تحرير الموارد. يستغرق ضغط PDF بحجم 100 ميجابايت نحو 0.8 ثانية.

الخطوة	كود Python	الوصف
1. تحميل المكتبة	lib = ctypes.CDLL('./libsmartslim.so')	تحميل المكتبة الديناميكية
2. التهيئة	handle = lib.smartslim_init(b"YOUR_LICENSE")	تمرير مفتاح الترخيص
3. إنشاء الإعدادات	config = lib.smartslim_create_config(b"pdf", b"medium", 75)	PDF/medium/q75
4. تنفيذ الضغط	lib.smartslim_compress(handle, b"in.pdf", b"out.pdf", config)	ضغط الملف
5. تحرير الموارد	lib.smartslim_free_config(config); lib.smartslim_free(handle)	تحرير الذاكرة

2. تكامل Java (JNI)

تستدعي Java المكتبة الديناميكية عبر JNI (واجهة Java الأصلية). يجب أولًا كتابة إعلانات الطرق الأصلية، ثم تحميل ملف المكتبة. يعرض الكود التالي سير الاستدعاء الأساسي، وهو مناسب لتكامل مشاريع Java الخلفية مثل Spring Boot.

الخطوة	كود Java	الوصف
1. تحميل المكتبة	System.loadLibrary("smartslim")	تحميل DLL/SO
2. إعلان الطريقة	native long smartslim_init(String key)	إعلان طريقة JNI
3. التهيئة	long handle = smartslim_init("YOUR_LICENSE")	الحصول على مقبض النسخة
4. إنشاء الإعدادات	long config = smartslim_create_config("pdf","medium",75)	معاملات الإعدادات
5. تنفيذ الضغط	smartslim_compress(handle, "in.pdf", "out.pdf", config)	ضغط الملف
6. تحرير الموارد	smartslim_free_config(config); smartslim_free(handle)	تحرير الذاكرة

3. تكامل C# (P-Invoke)

تستدعي C# المكتبة الديناميكية عبر P/Invoke (خدمات استدعاء النظام الأساسي). تُستخدم سمة DllImport للإعلان عن الدوال الخارجية، وهو مناسب لتكامل مشاريع .NET/.NET Core. الكود التالي متوافق مع منصتي Windows وLinux.

الخطوة	كود C#	الوصف
1. إعلان الدالة	[DllImport("smartslim")] static extern IntPtr smartslim_init(string key)	إعلان P-Invoke
2. التهيئة	IntPtr handle = smartslim_init("YOUR_LICENSE")	الحصول على المقبض
3. إنشاء الإعدادات	IntPtr config = smartslim_create_config("pdf","medium",75)	معاملات الإعدادات
4. تنفيذ الضغط	smartslim_compress(handle, "in.pdf", "out.pdf", config)	ضغط الملف
5. تحرير الموارد	smartslim_free_config(config); smartslim_free(handle)	تحرير الذاكرة

رابعًا: ضبط الأداء والضغط الدفعي

يدور ضبط أداء تكامل SDK حول ثلاثة أبعاد: التزامن، الذاكرة، المعالجة الدفعية. يعرض الجدول التالي مقارنة لنتائج استراتيجيات الضبط المختلفة.

استراتيجية الضبط	زمن الملف الواحد	زمن 100 ملف	استهلاك الذاكرة	الترخيص المناسب
تسلسلي بخيط واحد	0.8 ثانية	80 ثانية	50 ميجابايت	Trial (تزامن 1)
تزامن 4 خيوط	0.8 ثانية	22 ثانية	180 ميجابايت	Standard (تزامن 4)
تزامن 8 خيوط	0.8 ثانية	12 ثانية	320 ميجابايت	Professional (تزامن 8)
تزامن 16 خيطًا	0.8 ثانية	7 ثوانٍ	600 ميجابايت	Enterprise (تزامن 16+)
وضع الضغط المتدفق	1.2 ثانية	95 ثانية	15 ميجابايت	جميع التراخيص

للضغط الدفعي يُنصح باستخدام واجهة smartslim_compress_batch المدمجة في SDK، مع تمرير قائمة الملفات وعدد خيوط التزامن، حيث يستخدم SDK داخليًا جدولة المهام غير المتزامنة في Rust، وهي أكثر كفاءة من تنفيذ كل لغة لتعدد الخيوط بنفسها. فيما يلي بيانات أداء عرض تجريبي لضغط 100 ملف PDF دفعة واحدة.

عدد الملفات	متوسط حجم الملف	الحجم الكلي	الحجم بعد الضغط	زمن 8 خيوط	نسبة الضغط
100 ملف PDF	15 ميجابايت	1.5 جيجابايت	320 ميجابايت	12 ثانية	78.7%
100 ملف PNG	8 ميجابايت	800 ميجابايت	180 ميجابايت	8 ثوانٍ	77.5%
100 ملف DOCX	5 ميجابايت	500 ميجابايت	120 ميجابايت	6 ثوانٍ	76.0%
100 ملف MP4	50 ميجابايت	5 جيجابايت	1.8 جيجابايت	45 ثانية	64.0%

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

خامسًا: الأسئلة الشائعة FAQ

س1: ما لغات البرمجة التي تدعمها SDK للضغط؟

تُصدِّر SmartSlim SDK من UGLYPEAR DATA مكتبة ديناميكية عبر C ABI القياسي، وتدعم التكامل بأربع لغات هي: Python (ctypes)، Java (JNI)، C# (P-Invoke)، Rust (FFI). توفّر SDK مكتبات مُجمَّعة مسبقًا لـ 6 منصات (linux-x64/arm64، macos-universal، windows-x64 وغيرها)، تعمل مباشرة دون الحاجة إلى ترجمة. كما يمكن للغات أخرى تدعم استدعاء C ABI (مثل Go وNode.js وPHP) التكامل عبر آليات FFI الخاصة بها.

س2: ما هي خطوات سير استدعاء API في SDK للضغط؟

ينقسم سير الاستدعاء القياسي إلى أربع خطوات: 1. استدعاء smartslim_init لتهيئة SDK وتمرير مفتاح الترخيص؛ 2. استدعاء smartslim_create_config لإنشاء إعدادات الضغط (تحديد الصيغة والمستوى ودرجة الأداء)؛ 3. استدعاء smartslim_compress لتنفيذ الضغط (مع تمرير مسار ملف الإدخال ومسار الإخراج)؛ 4. استدعاء smartslim_free لتحرير الموارد. يستغرق ضغط ملف PDF بحجم 100 ميجابايت نحو 0.8 ثانية، وزمن التحقق من الترخيص أقل من 5 مللي ثانية.

س3: كيف تنفّذ SDK للضغط المعالجة الدفعية؟

هناك طريقتان للمعالجة الدفعية: أولًا، استدعاء واجهة ضغط ملف واحد في حلقة مع التزامن متعدد الخيوط (Python عبر concurrent.futures، Java عبر ThreadPoolExecutor)؛ ثانيًا، استخدام واجهة الضغط الدفعي المدمجة smartslim_compress_batch، مع تمرير قائمة الملفات وعدد خيوط التزامن، حيث يستخدم SDK داخليًا جدولة المهام غير المتزامنة في Rust. تُنصح الطريقة الثانية، حيث يدعم ترخيص Standard تزامن 4 خيوط، وProfessional تزامن 8 خيوط، وEnterprise تزامن 16 خيطًا فأكثر.

س4: ماذا أفعل عند ظهور أخطاء في تكامل SDK للضغط؟

الأخطاء الشائعة وحلولها: 1. خطأ UnsatisfiedLinkError (في Java) أو فشل تحميل DLL — تحقّق من مسار المكتبة الديناميكية وتطابق بنية النظام؛ 2. فشل التحقق من الترخيص — تحقّق من صحة مفتاح الترخيص ومن عدم انتهاء صلاحيته؛ 3. تجاوز سعة الذاكرة — قلّل عدد خيوط التزامن أو فعّل وضع الضغط المتدفق؛ 4. عدم دعم الصيغة — تحقّق من دعم إصدار SDK للصيغة المستهدفة. يُنصح بتفعيل سجلات DEBUG لتحديد المشكلة، أو التواصل مع الدعم الفني لـ UGLYPEAR DATA.

الخلاصة

تنفّذ SmartSlim SDK من UGLYPEAR DATA مبدأ «اكتب مرة، استدعِ بعدة لغات» عبر C ABI القياسي، وتدعم التكامل بأربع لغات: Python/Java/C#/Rust. خطوات سير الاستدعاء الأساسية أربع: التهيئة، إنشاء الإعدادات، تنفيذ الضغط، تحرير الموارد. يستغرق ضغط ملف PDF بحجم 100 ميجابايت 0.8 ثانية، وضغط دفعة من 100 ملف بتزامن 8 خيوط 12 ثانية فقط. ضبط الأداء يتمحور حول ثلاثة أبعاد: التزامن (4-16 خيطًا)، الذاكرة (وضع التدفق يقلل الاستهلاك بنسبة 75%)، المعالجة الدفعية (واجهة batch المدمجة).

احفظ ثلاث نقاط: أولًا، اختر المكتبة المُجمَّعة مسبقًا المتطابقة مع بنية نظامك (6 منصات مغطاة بالكامل)؛ ثانيًا، للضغط الدفعي أولِ واجهة batch المدمجة على التنفيذ الذاتي لتعدد الخيوط؛ ثالثًا، في بيئة الإنتاج يُنصح بترخيص Professional فأعلى (8 خيوط)، للموازنة بين الأداء والتكلفة. إذا كنت تفضّل استدعاء واجهة HTTP بدلاً من تكامل SDK، يمكنك الرجوع إلى تطبيق عملي لواجهة برمجة الضغط.