تقدير المشروع
← كل المقالات

البحث عن قالب مثالي لخدمة Rust مصغّرة

نقطة انطلاق بسيطة لخدمة Rust مصغّرة، مهيأة للتوسع مع مشروعك.

11 دقائق قراءة
RustRedisUtoipaSqlxAxum

رغم أن شعبية Rust تواصل الارتفاع وقد تصدّرت مؤخرًا استطلاع Stack Overflow للمطورين، لا يزال كثيرون يرونها في المقام الأول لغة أنظمة. أنا شخصيًا من محبي أسلوب Rust وإيجازها، وأنا مقتنع بأن لديها الكثير لتقدمه خارج برمجة الأنظمة الكلاسيكية – خاصة في تطوير الويب، حيث تشكل خدمات الويب RESTful جزءًا كبيرًا مما نفعله كل يوم. ومن أسباب عدم لجوء كثير من شركات البرمجيات وأقسام تقنية المعلومات في الشركات إلى Rust افتراضيًا شدة انحدار منحنى التعلم فيها. في البداية قد تبدو Rust مرهِبة، خاصة للمطورين الذين لم يصادفوا نهجها المميز من قبل. ومع ذلك، لا أرى سببًا يمنع استخدامها استخدامًا جيدًا حيثما تحتاج البرمجة إلى الكفاءة والموثوقية.

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

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

مثل كثير من المبرمجين الذين يتعلمون Rust الآن، أنا مبتدئ في كتابة خدمات ويب جاهزة للإنتاج بها، رغم أن لدي خبرة واسعة في بناء الخدمات المصغّرة عمومًا. لهذا القالب اخترت مكتبات تحقق، في رأيي، توازنًا جيدًا بين الوظائف والبساطة؛ لكنني أدرك أن اختياراتي لن تعجب الجميع. تعامل معه كنقطة انطلاق – قد أحسّن القالب مع الوقت أو أبني نسخًا أخرى بمكتبات مختلفة مع تغير المتطلبات. الملاحظات والأفكار وطلبات السحب (pull requests)، بل وحتى القوالب الجديدة كليًا، موضع ترحيب دائمًا.

قائمة ذاتية بالخصائص التي نريدها من قالب الخدمة المصغّرة

لم أجرِ أي بحث رسمي، لكن من المعقول افتراض أن معظم الخدمات المصغّرة التي تُبنى اليوم تعمل على عناقيد Kubernetes، وغالبًا ما تُستضاف لدى مزوّدي سحابة معروفين مثل Google أو Amazon أو Azure. ومع ذلك، ينبغي أن يلائم القالب الذي نُنشئه بيئات متنوعة، والشرط الصارم الوحيد هو إمكانية وضعه في حاوية بـ Docker دون عناء.

وضع الخدمة المصغّرة في حاوية Docker مجرد مثال، لكن كما سترى، فإن الخصائص الرئيسية التي اخترتها لهذا القالب – المدرجة أدناه – ذاتية إلى حد كبير.

  1. سهولة البناء: ينبغي أن يكون بناء الخدمة المصغّرة بسيطًا، ويُفضَّل بأداة بناء ناضجة تتيح الاختبار والإصدار السريعين وتكاملًا سلسًا مع CI/CD. في رأيي، يلبي cargo هذه الحاجة جيدًا، رغم أن قواعد الكود الكبيرة قد تؤدي إلى أزمنة بناء أطول. ولحسن الحظ يمكن تخفيف ذلك بعدة طرق، قد أصفها في مقال مستقبلي.
  2. إطار ويب قابل للضبط: ينبغي أن يكون إطار العمل الذي يخدم HTTP سهل الضبط. ومعظم أطر ويب Rust المتوفرة اليوم في السوق ربما تلبي ذلك.
  3. تكامل المكتبات: ينبغي أن يكون دمج المكتبات الأخرى مع إطار الويب سهلًا، خاصة تلك المسؤولة عن الحفظ الدائم (persistence).
  4. الحفظ الدائم مع دعم الترحيل: ينبغي أن تجعل مكتبة الحفظ الدائم التي نختارها ترحيلات مخطط قاعدة البيانات بسيطة، بما في ذلك إمكانية التراجع عنها.
  5. التسجيل والتتبع: ينبغي أن توفر الخدمة تسجيلًا (logging) وتتبعًا (tracing) سهلي الاستخدام وموثوقين.
  6. قابلية التوسع: ينبغي أن يتعامل إطار العمل جيدًا مع الأحمال المتغيرة، ملبيًا متطلبات قابلية التوسع في تطبيقنا.
  7. التوثيق ودعم المجتمع: لا بد من توثيق شامل سهل المنال وأمثلة ومجتمع نشط يمكن اللجوء إليه طلبًا للمساعدة.

وهكذا انتهى بنا الأمر إلى اختيار Axum كإطار عمل لنا!

لماذا Axum؟

باختصار: إنه حديث وفعّال. قد يفضل بعض الناس أطرًا مثل Actix أو Rocket، أو يرون وعودًا في أطر الويب الكثيرة التي تظهر في مجتمع Rust كل عام (علامة جيدة على النمو!)، لكن بالنسبة إلي، يستوفي Axum كل المعايير – على الأقل في الوقت الحالي.

  1. غير متزامن بالتصميم:
    بُني Axum فوق Tokio، وهو بيئة تشغيل غير متزامنة شائعة لـ Rust. ونتيجة لذلك، فإن Axum غير حاجب بطبيعته ومضبوط لإنتاجية عالية وزمن استجابة منخفض، مما يجعله مناسبًا جدًا للتطبيقات كثيفة الإدخال/الإخراج.
  2. معالجة أخطاء آمنة من حيث الأنواع:
    يستفيد Axum من نظام الأنواع القوي في Rust لاكتشاف الأخطاء وقت الترجمة، مما يقلل مشكلات وقت التشغيل ويجعله أكثر موثوقية في الإنتاج.
  3. دعم الوسيط البرمجي (middleware) عبر Tower:
    يدعم Axum الوسيط البرمجي عبر Tower، وهي مكتبة قوية لبناء خدمات شبكية متينة. وهذا يسهّل إضافة الاهتمامات المشتركة مثل التسجيل والمصادقة والمقاييس.
  4. مجتمع ونظام بيئي قويان:
    بما أنه مبني على Tokio، يستفيد Axum من نظام بيئي نابض بالحياة ويتكامل بسلاسة مع مكتبات أخرى من نظام Tokio البيئي، مع دعم المجتمع وتحسينات مستمرة خلفه.

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

اختيار مكتبة الحفظ الدائم

من القرارات الأساسية تحديد مكتبة الحفظ الدائم المستخدمة للتكامل مع قاعدة البيانات. ومن بين عدة خيارات متاحة في النظام البيئي لـ Rust، اخترت sqlx، لأنها بسيطة أساسًا وتأتي مع واجهة سطر أوامر تجعل إدارة قاعدة البيانات أكثر راحة.

إعداد الأساس

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

  1. إعداد المشروع

نبدأ بإنشاء مشروع Rust عادي. استخدم cargo لوضع أساس قالبنا:

cargo new your-project-name

  1. إضافة axum واعتماديات أخرى

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

  1. إنشاء أساس طبقة قاعدة البيانات

يحتاج الحفظ الدائم عبر Sqlx إلى قاعدة بيانات وجداول. بالنسبة إلى خادم قاعدة البيانات، سنستخدم سكربت docker compose (المزيد عنه لاحقًا) مع postgres، وبالنسبة إلى الجداول نحتاج إلى إنشاء ترحيلات في مجلد مشروعنا.

…sql up/down scripts

أضف قاعدة بيانات باستخدام docker-compose. يعرّف ملف docker compose لدينا خدمتين: خادم قاعدة البيانات وخادم redis لتخزيننا المؤقت.

docker-compose -f docker-compose.yaml up -d

  1. إضافة dotenvy وإنشاء ملف .env

للتعامل مع متغيرات البيئة، سنستخدم المكتبة dotenvy واسعة الاستخدام. أنشئ ملف .env في المجلد الجذري للمشروع وضع فيه مدخلاتك للتطوير المحلي. وفي الإنتاج، ستُقرأ هذه بالطبع من الأسرار/القيم العامة أو القيم الافتراضية التي يوفرها عنقودك.

محتوى ملف Env مع عنواني db والتخزين المؤقت

  1. ترحيل البيانات

مع تشغيل خادم قاعدة البيانات، يمكنك ترحيل بياناتك باستخدام sqlx cli، أو الأفضل من ذلك، جعل الترحيل يعمل برمجيًا في كل مرة يبدأ فيها تطبيقك

pub async fn run_migrations(config: &Config) {
   let db_pool = Arc::new(postgres::db_connect(config).await);
   if let Err(e) = sqlx::migrate!().run(&*db_pool).await {
       panic!("Failed to run database migrations: {:?}", e);
   }
}

حتى الآن لدينا تطبيق ويب بسيط فارغ إلى حد كبير، لكن قاعدة بياناتنا على الأقل تعمل. ولتحويله إلى خدمة مصغّرة عاملة، نحتاج إلى إضافة بعض الوظائف الأساسية. أولًا، سننظم بنية التطبيق بحيث يسهل توسيعه وصيانته عندما تصل الميزات الحقيقية. وبعد جاهزية البنية، سنضيف بعض نقاط النهاية وندخل Swagger لتبسيط توثيق واجهتنا البرمجية.

بنية المشروع

هذا ليس الدليل النهائي لهيكلة خدمة ويب، لكن النهج خدمني جيدًا (حتى الآن على الأقل) وما زال يتطور. يُقسَّم الكود إلى وحدات، تضع مسارًا واضحًا لمعالجة الطلبات في التطبيق، كما هو موضح أدناه:

(Routes) -> controllers -> services -> repositories

  • وحدة router: هنا يُدمج Utoipa (لـ Swagger) مع مسارات تطبيقنا.
  • وحدة app: هنا يُربط كل شيء معًا عبر آلية الطبقات/الامتدادات في Axum، موصلةً المسارات بمنطق الأعمال الكامن تحتها.

الامتدادات (Extensions)

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

pub async fn create_app(config: &Config) -> Router {
   let _ = run_migrations(config).await;
   let car_repository = Arc::new(create_car_repository(config).await);
   let part_repository = Arc::new(create_part_repository(config).await);
   let cache = Arc::new(create_cache(config).await);
   router()
       .layer(
           TraceLayer::new_for_http()
               // Create our own span for the request and include the matched path. The matched
               // path is useful for figuring out which handler the request was routed to.
               .make_span_with(|req: &Request| {
                   let method = req.method();
                   let uri = req.uri();

                   // axum automatically adds this extension.
                   let matched_path = req
                       .extensions()
                       .get::<MatchedPath>()
                       .map(|matched_path| matched_path.as_str());

                   info_span!("request: ", %method, %uri, matched_path)
               })
               // By default `TraceLayer` will log 5xx responses but we're doing our specific
               // logging of errors so disable that
               .on_failure(()),
       )
       .layer(Extension(car_repository))
       .layer(Extension(part_repository))
       .layer(Extension(cache))
}

هنا نسجّل امتدادات لـ car_repository وpart_repository وتخزين Redis المؤقت cache. ويمكن عندئذ لدوال مسارات وحدات التحكم لدينا استقبالها كوسائط، على سبيل المثال:

pub async fn view(Path(car_id): Path<i32>, Extension(repo): CarRepoExt, Extension(cache): CacheExt) -> Result<AppJson<Car>, AppError>

يمكن تمرير الامتدادات إلى طبقة الخدمة لتنفيذ منطق الأعمال، مما يجعل مشاركة الحالة فعّالة.

OpenAPI وSwagger

نعرّف نقاط النهاية لدينا بمكتبة Utoipa. ولربط Utoipa بتوجيه Axum، نستخدم وحدة مخصصة مع دالة بناء router():

pub fn router() -> Router {
   let app = OpenApiRouter::new()
       .routes(routes!(utils::healthcheck))
       .nest("/cars", car_routes())
       .nest("/parts", part_routes());

   let (router, api) = OpenApiRouter::with_openapi(ApiDoc::openapi())
       .nest("/api", app)
       .split_for_parts();
   let router = router
       .merge(SwaggerUi::new("/swagger-ui").url("/api-docs/openapi.json", api.clone()))
       .merge(Redoc::with_url("/redoc", api.clone()))
       // There is no need to create `RapiDoc::with_openapi` because the OpenApi is served
       // via SwaggerUi instead we only make rapidoc to point to the existing doc.
       .merge(RapiDoc::new("/api-docs/openapi.json").path("/rapidoc"))
       // Alternative to above
       // .merge(RapiDoc::with_openapi("/api-docs/openapi2.json", api).path("/rapidoc"))
       .merge(Scalar::with_url("/scalar", api));

   Router::new().nest("/", router)
}

إلى جانب Swagger-UI، ضبطنا Redoc وRapiDoc وScalar. احتفظ بأي واجهة OpenAPI تناسبك أكثر.

تُعلن نقاط النهاية بماكروهات Utoipa، ويكتشف المترجم كثيرًا من الأخطاء المحتملة:

/// Search all cars
///
/// Tries to get list of cars by query from the database
#[utoipa::path(
   get,
   path = "/search",
   params(("name" = String, Query, description="Car Name")),
   responses((status = OK, body = [Car])),
   tag = CARS_TAG
)]
pub async fn search(Query(params): Query<CarQuery>, Extension(repo): CarRepoExt) -> Result<AppJson<CarList>, AppError> {
   let cars = services::cars::search(repo.clone(), &params).await?;
   Ok(AppJson(cars))
}

عندما يكون التطبيق قيد التشغيل، تظهر كل نقطة نهاية في Swagger-UI، حيث يمكنك اختبارها تفاعليًا.

مثال على واجهة Scalar:

معالجة الأخطاء

يدعم Axum عددًا من استراتيجيات معالجة الأخطاء. ولإبقاء هذا القالب بسيطًا، قررت استخدام anyhow::Error وتحويل أي خطأ داخل التطبيق إلى زوج (tuple) يحمل رمز حالة HTTP ورسالة عامة. وتُحفظ سجلات مفصلة داخليًا لأغراض التشخيص، بينما لا يحصل العملاء إلا على رسائل خطأ عامة. ويحقق هذا النهج توازنًا بين الأمان والبساطة.

فيما يلي تنفيذنا المخصص لـ IntoResponse للنوع AppError:

impl IntoResponse for AppError {
   fn into_response(self) -> Response {
       // How we want errors responses to be serialized
       #[derive(Serialize)]
       struct ErrorResponse {
           message: String,
       }
       let err = self;
       let (status, message) = {
           // Because `TraceLayer` wraps each request in a span that contains the request
           // method, uri, etc we don't need to include those details here
           tracing::error!(%err);

           // Don't expose any details about the error to the client
           (
               StatusCode::INTERNAL_SERVER_ERROR,
               "Something went wrong".to_owned(),
           )
       };

       (status, AppJson(ErrorResponse { message })).into_response()
   }
}

إضافة إلى مقطع يحوّل أي anyhow::Error إلى AppError لدينا عند الحاجة:

impl<E> From<E> for AppError
where
   E: Into<anyhow::Error>,
{
   fn from(err: E) -> Self {
       Self(err.into())
   }
}

الخاتمة

وهذا كل شيء – نقطة انطلاق بسيطة لخدمة Rust مصغّرة، مهيأة للتوسع مع مشروعك. ليس هو القالب النهائي، لكنه بداية، وآمل أن يكون خطوة نحو جعل Rust أسهل منالًا وأكثر عملية لخدمات الويب. ويمنحنا Axum، مقترنًا بمكتبات مفيدة مثل Utoipa لتكامل OpenAPI، أساسًا متينًا ومرنًا نبني عليه.

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

وكما هو الحال مع أي أداة جيدة، يمكنك تشكيل هذا الإعداد وتطويره مع تطور احتياجاتك. وسواء نشرت على عنقود Kubernetes ضخم أو جربت على جهازك الخاص، آمل أن يُريك هذا القالب ما تستطيع Rust فعله خارج سمعتها كلغة أنظمة. لا يزال أمام تطوير الويب بـ Rust طريق طويل، لكن كل مشروع جديد وكل تجربة فرصة لتوسيع ما هو ممكن بها.

هل لديك أفكار أو آراء أو تحسينات؟ لا يزال القالب يتطور، فلا تتردد في المشاركة وتجربته ومشاركة اقتراحاتك. فمجتمع Rust، في النهاية، من أفضل أصول اللغة، والبناء معًا أفضل طريقة لمساعدته على النمو.

إذا كانت Rust تثيرك بقدر ما تثيرني، فتعالَ إلى مؤتمر Rust ليوم واحد الذي ننظمه في 26 مارس 2025. إنها فرصة ممتازة للاستماع إلى محاضرات خبراء Rust ومشاركة أفكارك والانضمام إلى مجتمع Rust المتنامي. آمل أن أراك هناك!

برمجة سعيدة!