قائمة تحقق موثوقة لإعداد مشاريع Scala الجديدة
أهم الإعدادات والممارسات التي يجدر النظر فيها عندما تريد تحسين عمليات البناء أو سير عملك في التطوير. ويصلح عدد منها ليكون جزءًا من القوالب.
غالبًا ما ينتهي بدء مشروع Scala جديد بنسخ إعدادات البناء ولصقها من مكان آخر. فإعدادات البناء التي مرّ عليها وقت طويل تميل إلى جمع كثير من الإعدادات والإضافات المفيدة. بعض المؤسسات تنقل إعداداتها الافتراضية إلى إضافات (plugins) داخلية أو تعتمد على ميزات مثل قوالب GitHub. ونادرًا ما تكون هذه القوالب مفيدة خارج السياق الذي أُعدّت له، ولذلك فإن محاولة بناء هيكل مشروع واحد نهائي لكل غرض ليست مجدية.
ما أودّ تقديمه بدلًا من ذلك هو قائمة تحقق بأهم الإعدادات والممارسات التي يجدر النظر فيها عندما تريد تحسين عمليات البناء أو سير عملك في التطوير. ويصلح عدد منها ليكون جزءًا من القوالب. أما الباقي فهو ببساطة خطوات أساسية أحب أن تكون مطبّقة قبل أن يبدأ أي شخص بالمساهمة.
نظرة عامة على القائمة (باختصار)
إذا كنت تفضّل تصفّح القائمة كاملة دون قراءة فقرات مملة، فها هي:
- .gitignore
- sbt-dotenv وdirenv
- local.conf
- .sbtopts
- إصدار Java
- أعلام المترجم (Compiler flags)
- .scalafmt.conf
- .scala-steward.conf أو renovate
- إعدادات النشر (publish)
- .mergify.conf أو automerge
- GitHub actions وCODEOWNERS
- المكتبات الأساسية
- مدد TTL لإصدارات SNAPSHOT
- إضافة: nix
.gitignore
جهّز ملف .gitignore شاملًا منذ البداية، كي لا تصل إلى طلبات السحب (pull requests) ملفات محلية مزعجة وغير ضرورية.
sbt-dotenv وdirenv
كثيرًا ما تُمرَّر قيم إعداد المشروع المخصّصة عبر متغيرات البيئة. ففي مشاريع Scala مثلًا، من الشائع الإشارة إليها في application.conf ثم تحديد القيم الفعلية للبيئات المحلية والاختبارية والإنتاجية. أداة direnv أداة واسعة الاستخدام تحمّل البيئة تلقائيًا في الصدفة (shell) الحالية بمجرد دخولك مجلد مشروع يحتوي ملف .envrc، بمحتوى مثل
export KAFKA_HOST=localhost
export KAFKA_PORT=9131
ربط ملف كهذا بوحدة تحكم sbt مفيد جدًا، خصوصًا عند تشغيلها من بيئة تطوير متكاملة (IDE). تستحق إضافة sbt-dotenv النظر في هذا الغرض. ومن المنطقي إعدادها كإضافة عامة (global) لتُطبَّق على كل مشاريعك المحلية.
ابدأ بإنشاء ~/.sbt/1.0/plugins/dotenv.sbt بالمحتوى:
addSbtPlugin("nl.gn0s1s" % "sbt-dotenv" % "3.0.0")
وأقترح أيضًا تغيير اسم الملف الافتراضي للإضافة من .env إلى .envrc. فهذا هو الاسم القياسي الذي تستخدمه direnv، وهي أداة أكثر شعبية وتخدم أغراضًا أخرى. ولفعل ذلك، أضف الملف .sbt/1.0/envrc.sbt بالمحتوى:
ThisBuild / envFileName := ".envrc"
بعد ذلك، في كل مرة تشغّل فيها وحدة تحكم sbt، ستحمّل متغيرات البيئة من ملف .envrc الموجود في جذر مساحة العمل. ينبغي أن يبقى الملف محليًا، فتأكد من أن git يتجاهله؛ راجع قسم .gitignore.
(ملاحظة: تعتمد sbt-dotenv على الانعكاس (reflection). ابتداءً من Java 17 صار الانعكاس محظورًا، فتتعطل sbt-dotenv عند التشغيل. يشرح القسم التالي، عن .sbtopts، كيفية إصلاح ذلك).
local.conf
إلى جانب متغيرات البيئة، هناك ممارسة مفيدة أخرى هي تجاوز عناصر الإعداد في application.conf. أضف local.conf إلى .gitignore ليتمكن المطورون من إنشاء ملف src/main/resources/local.conf يضمّن application.conf، مثلًا:
include "application.conf"
akka {
loggers = ["akka.event.slf4j.Slf4jLogger"]
loglevel = "DEBUG"
stdout-loglevel = "DEBUG"
}
يسري الملف عند تشغيل التطبيق مع -Dconfig.file=path/to/src/main/resources/local.conf. يمكنك تمرير هذا الوسيط إلى sbt بعدة طرق:
- عند تشغيل وحدة تحكم sbt العادية:
sbt 'set javaOptions+="-Dconfig.file=path/to/src/main/resources/local.conf"; test:runMain com.myapp.MyMain' - في وحدة تحكم sbt داخل IntelliJ: أضف ببساطة
-Dconfig.file=...إلى «VM parameters» ضمن «sbt settings» - في إعدادات «Run» في IntelliJ: كما في وحدة تحكم sbt، استخدم حقل «VM parameters»
- وكذلك في الأدوات الأخرى
.sbtopts
هذا مكان مناسب لتحديد خيارات sbt أو Java لعمليات البناء ووحدة تحكم sbt. ولمشاركة مجموعة موحّدة مع كل المطورين ومع CI، ضعها في .sbtopts، على سبيل المثال:
تفعيل الانعكاس في إصدارات Java الأحدث: (مطلوب لـ sbt-dotenv على Java 17 وما بعدها)
-J--add-opens=java.base/java.util=ALL-UNNAMED
-J--add-opens=java.base/java.lang=ALL-UNNAMED
تحديد إعدادات ذاكرة معيّنة:
-J-Xmx5G
-J-Xms1G
-J-Xss2M
تحديد خيارات sbt معيّنة (القائمة الكاملة هنا):
-Dsbt.task.timings=true
إصدار Java
بين حين وآخر ينتهي تحقيق طويل باكتشاف أن إصدار Java المحلي لديك يختلف عن الإصدار الذي يستخدمه CI، وقد يكون الإصدار المنشور مع التطبيق شيئًا آخر تمامًا. يمكن توحيد إصدار Java عبر جميع طبقات مشروعك، لكن الأمر ليس مباشرًا.
محليًا، يعتمد المطورون كثيرًا على sdkman أو jenv. الأولى عامة الأغراض ويمكن دمجها مع .envrc، لكن الطريقة الوحيدة التي استطعت العثور عليها بعيدة عن الأناقة. وإلا فاعتمد إما .sdkmanrc أو .java-version، وهما الملفان المخصّصان اللذان تستخدمهما هاتان الأداتان.
أما مسار التكامل المستمر (Continuous Integration) لديك فلديه على الأرجح إعداد JDK خاص به (انظر إجراء GitHub Action هذا الذي يقرؤه من ملف)، ثم هناك sbt-native-packager الذي يتطلب تعريف صورة أساس في build.sbt.
لم أرَ إصدارات JDK هذه كلها مجتمعة في مكان واحد حتى صادفت nix، وسأصفه بعمق في مقال مدونة منفصل.
أعلام المترجم (Compiler flags)
سؤال: هل تستطيع اكتشاف المشكلة في هذه الشيفرة؟
def doStuff(data: Data): F[Unit] = {
Logger[F].info(s"Logging important metadata: ${data.metadata}")
processor.process(data).void
}
الجواب: من الواضح أن الشيفرة تفتقر إلى >> التي تربط قيمة F[Unit] التي يعيدها المسجِّل (logger) بقيمة F[Unit] الأخرى التي يعيدها استدعاء المعالج، وهي نتيجتنا النهائية. لكن هل هذا واضح فعلًا؟ على الأرجح نعم حين يُطلب منك البحث عن أخطاء في سطرين من الشيفرة، لكن في سياق أكبر يسهل تفويته.
المشكلة أن مترجم Scala 2.13 يبقى صامتًا تمامًا، ويمكن لأخطاء كهذه أن تفلت من مراجعات الشيفرة! تحتاج إعدادات المترجم الافتراضية دائمًا تقريبًا إلى تشديد، مثلًا للتحذير من القيم غير المستخدمة والمهملة ومن مشكلات محتملة أخرى. توفر إضافة sbt-tpolecat مجموعة ممتازة من أعلام مترجم sbt. اقرنها بـكتم التحذيرات الانتقائي وسيكتمل المطلوب. فمثلًا، ضع:
scalacOptions += "-Wconf:src=src_managed/.*:s"
في إعدادات البناء لديك لكتم التحذيرات الخاصة بالأصناف التي يولّدها ScalaPB من ملفات protobuf.
.scalafmt.conf
إدخال قواعد التنسيق في مرحلة متأخرة من عمر المشروع يؤدي إلى تحديثات مؤلمة، لذا فالاتفاق على مجموعة قواعد جيدة في البداية أمر أساسي. فيما يلي بعض القواعد التي أحبها، لكن تذكّر أن أعراف أسلوب الشيفرة ذاتية إلى حد كبير:
maxColumn = 140
// breaks long class/def definitions into multiline
verticalMultiline.atDefnSite = true
// forces newline before and after implicit params
newlines.implicitParamListModifierForce = [before, after]
// only format files tracked by git
project.git = true
// PreferCurlyFors: Replaces parentheses into curly braces in for comprehensions that contain multiple enumerator generators
// RedundantBraces, RedundantParens: Remove redundant braces, parens
rewrite.rules = [PreferCurlyFors, RedundantBraces, RedundantParens, SortImports]
// Add spaces next to curly braces in imports
spaces.inImportCurlyBraces = true
// more than standard align rules https://scalameta.org/scalafmt/docs/configuration.html#alignpresetmore
style = defaultWithAlign
// all infix operators can be exempted from applying continuation indentation
indentOperator.exemptScope = all
rewriteTokens {
"⇒" = "=>"
"→" = "->"
"←" = "<-"
}
.scala-steward.conf أو renovate
إبقاء الاعتماديات محدّثة عملية معقدة تتطلب عملًا منتظمًا وتتبع غالبًا قواعد محددة. ويمكن اليوم أتمتتها بأدوات مثل Scala Steward أو renovate، يكمّلها dependabot. وقد ترغب أحيانًا في تخطي مكتبات معينة، أو ضبط عناوين طلبات السحب، أو تحديد عدد التحديثات أو وتيرتها. عدّل قواعد Scala Steward (انظر هذا المرجع وأعدّ ملف إعداد محدد بوضوح.
إعدادات النشر (publish)
في مشاريع sbt متعددة الوحدات، يكون اختيار الوحدات التي تُعامل بكل أسلوب محددًا في الغالب:
- تُنشر كحزم (artifacts)
- تُنشر كصور docker
- تُنشر مع scaladoc
- لا تُنشر
يستفيد ملف build.sbt الأولي لدي دائمًا تقريبًا من:
-
قائمة افتراضية من المستودعات (resolvers)
-
مسار إلى بيانات اعتماد ivy المحلية
-
إعدادات النشر
-
إعدادات docker الأساسية مثل صورة الأساس أو اسم الحزمة
-
Compile / packageDoc / publishArtifact := falseفيcommonSettingsلكل وحدة، مما يتخطى scaladoc ويقلل زمن البناء كثيرًا.
مجموعة منlazy val noPublishSettings = Seq( publish := {}, publishLocal := {} ) lazy val dockerNoPublishSettings = Seq( Docker / publishLocal := {}, Docker / publish := {} )
يمكن تطبيقها لاحقًا على النحو
.settings(noPublishSettings)
.settings(dockerNoPublishSettings)
على الوحدات التي لا ينبغي نشرها.
أعدّ النشر مسبقًا، كي تحتاج المستودعات المستقبلية المبنية على قالبك إلى أقل عمل إضافي ممكن.
.mergify.conf أو automerge
هناك مواقف كثيرة يفيد فيها دمج طلبات السحب تلقائيًا. على سبيل المثال:
- الدمج التلقائي لطلبات السحب المعتمدة التي يفتحها بوت تحديث الاعتماديات
- الدمج التلقائي لطلبات السحب التي تمسّ ملفات محددة
اطّلع على نموذج .mergify.conf يتضمن بعض القواعد التي نطبّقها. وتذكّر أن mergify مجاني للشيفرة مفتوحة المصدر فقط، لذا قد يناسب مشروعك أكثر الدمج التلقائي في GitHub أو renovate. نموذج إعداد:
# Enables automatic merge of master -> PR for Scala Steward PRs
# created by user 'github-actions', when all checks
# pass (including review approvals)
name: automerge
on:
pull_request:
types:
- labeled
- unlabeled
- synchronize
- edited
- ready_for_review
- reopened
- unlocked
pull_request_review:
types:
- submitted
check_suite:
types:
- completed
jobs:
automerge:
runs-on: ubuntu-latest
if: github.event.pull_request.user.login == 'github-actions'
steps:
- name: automerge
uses: "pascalgn/automerge-action@v0.15.3"
env:
GITHUB_TOKEN: "${{ secrets.GITHUB_TOKEN }}"
MERGE_FILTER_AUTHOR: "github-actions"
MERGE_METHOD: "squash"
MERGE_LABELS: ""
MERGE_RETRIES: "15"
MERGE_RETRY_SLEEP: "20000"
UPDATE_LABELS: ""
GitHub actions وCODEOWNERS
أعطيتُ أعلاه مثالًا واحدًا على GitHub action يناسب قالب المشروع تمامًا - automerge. ما الإجراءات الأخرى التي ترى أنها أساسية قبل أن يبدأ المساهمون بالإيداع؟
وبالحديث عن المساهمين، أحب إضافة ملف .github/CODEOWNERS، الذي يتيح تعيين مراجعي طلبات السحب تلقائيًا بناءً على محتواه. ولا يلزم أن تسرد أفرادًا؛ إذ يقبل الملف فرقًا أيضًا، مثل
@my-organization/alpha-team
المكتبات الأساسية
لا مكان للمكتبات في قوالب المشاريع، لكنها تستحق موضعًا في قائمة التحقق عند بدء قاعدة شيفرة جديدة. فكثير منها يُعدّ أدوات مساعدة أساسية نريدها غالبًا في مشروعنا منذ البداية. فقد أعدّ مطوّر Scala زميل، مثلًا، قائمة ممتازة: cats, refined, iron, chimney, ducktape, scala-newtype, monocle, quicklens, enumeratum, derevo, macwire, jam, PPrint, sbt-thank-you-stars.
وقد تتضمن مجموعتك الابتدائية أيضًا مكتبات للتسجيل (logging) والمقاييس والاختبار وغيرها من الاهتمامات المشتركة في مؤسستك.
تنبيه! لا أوصي بإضافة «مكتبات مشتركة» تُتقاسم بين المشاريع. بل على العكس - أتجنب هذا النهج، لأنه يسبب مشكلات اعتماديات فظيعة وينتج وحدة متضخمة تحمل مئات الميغابايتات من أشياء قد لا تحتاجها. أما الاحتفاظ بقائمة اقتراحات تراجعها الفرق عند بدء قاعدة شيفرة جديدة فيعمل بصورة أفضل بكثير.
مدد TTL لإصدارات SNAPSHOT
في بعض الحالات يكون التطوير مقابل اعتماديات SNAPSHOT منطقيًا. تخيّل فريقين يتبادلان حزمة «api» كثيرًا خلال مرحلة النموذج الأولي المبكرة بينما يستقران على عقد التواصل. إذا كان ذلك ينطبق عليك، فتذكّر أن TTL في Coursier هو 24 ساعة، فلن تُحدَّث حزمك حتى بعد نشر إصدار جديد. لتقصير هذه المدة، اختر أحد خيارين:
-
أضف إعداد TTL إلى قالبك (
build.sbt)csrConfiguration := csrConfiguration.value.withTtl(Some(1.minute))
أو
- استخدم ملف
.envrcالمذكور سابقًا، وأضف exportCOURSIER_TTL=60s(أو أي قيمة تحتاجها)، ثم أعد تشغيل جلسة sbt.
لاحظ أنه حتى عندما يلتقط sbt هذه الإعدادات ويعيد تحميل SNAPSHOT بشكل صحيح، يبدو أن IntelliJ يواجه صعوبة في ملاحظة الحزم الجديدة. وقد تحتاج إلى إعادة تشغيله في كل مرة تُنزَّل فيها SNAPSHOT جديدة.
إضافة: nix
ذكرتُ سابقًا nix بإيجاز كأداة يمكنها توسيع sbt-native-packager لبناء صور docker بنفس jdk المستخدم تمامًا في التطوير وCI. يقدم nix أكثر من ذلك، مثل تعريف بيئات كاملة من حزم SDK والمكتبات وحزم النظام لا تُحمَّل إلا وأنت داخل مجلد مشروعك (nix shells). والمحاضرة «Nix all the things» مقدمة لطيفة إلى nix للمبتدئين.
الخلاصة
آمل أن تساعدك قائمة التحقق هذه على إعداد إعدادات بناء سليمة مبكرًا في مشاريعك. وأنا واثق أن هناك نقاطًا كثيرة لا أعرفها، فإن كانت لديك أفكار للإضافة أو التحديث، فيرجى ترك تعليق!