أفضل الممارسات لهيكلة مجلدات مشروع Go

نظرة عامة

هذا هو تخطيط أساسي لمشروعات تطبيقات Go. إنها ليست معياراً رسمياً محدداً من قبل فريق تطوير Go الأساسي; إنه تخطيط مستخدم بشكل شائع لمشاريع Go في المجتمع.

إذا كنت تتعلم Go أو تقوم ببناء دليل البرهان (PoC) أو مشروع شخصي بسيط، فإن تخطيط المشروع هذا معقد للغاية. بدلاً من ذلك، ابدأ بتخطيط بسيط حقاً (مجرد ملف main.go وملف go.mod كافي). على الرغم من تطور مشروعك، تأكد من أن بنية الكود جيدة، وإلا فستنتهي بالكثير من الرمز المرتبط بالتبعيات والحالة العامة المخفية. عندما يشارك المزيد من الأشخاص في المشروع، تحتاج إلى طريقة مُنظمة. في هذه الحالة، من المهم أن تُدخل طريقة شائعة لإدارة الحزم/المكتبات. عندما تكون لديك مشروع مفتوح المصدر أو تعلم أن مشاريعًا أخرى تقوم بتوريث الرمز من مستودع مشروعك، يصبح من الأهمية وجود حزم ورمز (تُعرف أيضًا باسم internal) خاصة. انسخ المستودع، احتفظ بالأجزاء التي تحتاجها، واحذف كل شيء آخر! لا يعني وجود شيء أنه يجب عليك استخدام كل شيء. لا يُستخدم أيٌ من هذه الأنماط في كل مشروع. حتى نمط vendor ليس شاملاً.

تم تصميم تخطيط هذا المشروع بشكل متعمد ليكون عامًا للغاية ولا يحاول فرض بنية محددة لحزمة Go.

مواصفات مجلد مشروع Go

أدناه توجيهات تخطيط المجلد الموصى بها لمشروع Go.

.
├── go.mod
├── api
├── assets
├── build
├── cmd
├── configs
├── deployments
├── docs
├── examples
├── githooks
├── go.mod
├── init
├── internal
├── pkg
├── scripts
├── test
├── third_party
├── tools
├── vendor
├── web
└── website

يتم تقديم معاني كل مجلد أدناه.

/cmd

التطبيقات الرئيسية للمشروع، أي نقطة الدخول للبرامج. يُنشئ ملفات Go في هذا المجلد عادةً ملفات قابلة للتنفيذ. في مشروع بسيط، يمكن لملف مثل /test/main.go أن يكون نقطة الدخول.

يجب أن يتطابق اسم المجلد مع اسم الملف القابل للتنفيذ الذي ترغب فيه (على سبيل المثال /cmd/myapp).

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

عادةً ما يكون هناك دالة main صغيرة تقوم باستيراد واستدعاء الرمز من المجلدين /internal و/pkg، ولا شيء آخر.

/internal

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

قد تختار إضافة بعض الهيكل الإضافي لحزم الداخلية للتفريق بين الرمز الداخلي المشترك وغير المشترك. ليس مطلوباً هذا (خاصةً للمشاريع الصغيرة)، ولكن توضيح الرمز المقصود استخدامه بصرياً هو ممارسة جيدة. يمكن وضع رمز التطبيق الفعلي في مجلد /internal/app (على سبيل المثال /internal/app/myapp)، ويمكن وضع الرمز المشترك لهذه التطبيقات في مجلد /internal/pkg (على سبيل المثال /internal/pkg/myprivlib).

/pkg

رمز المكتبة الذي يمكن استخدامه من قبل تطبيقات خارجية (على سبيل المثال /pkg/mypubliclib). ستقوم مشاريع أخرى بإستيراد هذه المكتبات وتتوقع أن تعمل بشكل صحيح، لذا فكر جيداً قبل وضع المحتوى هنا :-) لاحظ أن مجلد internal هو طريقة أفضل للتأكد من عدم إمكانية استيراد الحزم الخاصة، حيث يُنفذ ذلك ذاتياً بواسطة Go. مع ذلك، مجلد /pkg لا يزال وسيلة جيدة للتعبير بشكل صريح عن أن الرمز في هذا المجلد آمن للاستخدام من قبل الآخرين.

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

/vendor

تعتمد تطبيقات الوثيقة (سواء تم إدارتها يدويًا أو باستخدام أداة إدارة الاعتمادات المفضلة لديك ، مثل ميزة Go Modules المدمجة). سيقوم الأمر go mod vendor بإنشاء دليل /vendor لديك. يرجى ملاحظة أنه إذا لم تكن تستخدم إصدار Go 1.14 المفعل بشكل افتراضي ، فقد تحتاج إلى إضافة علم -mod=vendor إلى أمر go build.

إذا كنت تقوم ببناء مكتبة ، يرجى عدم تأكيد اعتمادات تطبيقك.

دلائل تطبيق الخدمة

/api

مواصفات OpenAPI/Swagger ، ملفات مخطط JSON ، ملفات تعريف البروتوكول ، ودلائل البروتوكول API.

دلائل تطبيق الويب

/web

مكونات محددة لتطبيقات الويب: أصول الموقع الثابتة لموقع الويب ، القوالب الخادمية ، وتطبيقات الصفحة الواحدة (SPAs).

دلائل تطبيق عامة

/configs

قوالب ملفات التكوين أو تكوينات افتراضية.

ضع ملفات النموذج confd أو consul-template هنا.

/init

تهيئة النظام (systemd ، upstart ، sysv) وتكوينات مدير العمليات/الخدمة (runit ، supervisord).

/scripts

نصوص لمختلف عمليات البناء والتثبيت والتحليل وغيرها من العمليات.

/build

التغليف والتكامل المستمر.

ضع تكوينات الحزمة السحابية (AMI) ، وحاوية (Docker) ، ونظام التشغيل (deb ، rpm ، pkg) ، والنصوص في الدليل /build/package.

ضع تكوينات ونصوص التكامل المستمر (travis ، circle ، drone) في الدليل /build/ci. يرجى ملاحظة أن أدوات التكامل المستمر (مثل Travis CI) تكون محددة للغاية فيما يتعلق بموقع ملفات التكوين الخاصة بها. حاول وضع ملفات التكوين في الدليل /build/ci واستخدام الروابط لربطها بالموقع المتوقع من أدوات التكامل المستمر (إذا كان ذلك ممكنًا).

/deployments

تكوينات النشر والقوالب لـ IaaS ، PaaS ، النظام ، وتنظيم الحاويات (docker-compose ، kubernetes/helm ، terraform). يرجى ملاحظة أنه في بعض مستودعات البيانات (خاصة بالتطبيقات المنشورة باستخدام Kubernetes) يُسمى هذا الدليل /deploy.

/test

تطبيقات اختبار خارجية وبيانات اختبار أخرى. لا تتردد في تنظيم الدليل /test بالطريقة التي تناسب احتياجاتك. بالنسبة للمشاريع الكبيرة ، يُعقل تنظيم البيانات في مجلدات فرعية. على سبيل المثال ، يمكنك إنشاء مجلدات /test/data أو /test/testdata داخل /test لجعل Go يتجاهل المحتويات. يرجى ملاحظة أن Go يتجاهل أيضًا المجلدات أو الملفات التي تبدأ بـ "." أو "_", مما يوفر مزيدًا من المرونة في تسمية مجلدات بيانات الاختبار.

دلائل أخرى

/docs

توثيق التصميم والمستخدم (بخلاف مستندات godoc التي تولدها).

/tools

أدوات الدعم لهذا المشروع. يرجى ملاحظة أن هذه الأدوات يمكنها استيراد الكود من الدلائل /pkg و /internal.

/examples

أمثلة عن التطبيقات و/أو المكتبات العامة.

/third_party

أدوات الدعم الخارجية والشفرة المطوية وأدوات الأطراف الثالث الأخرى (على سبيل المثال ، Swagger UI).

/githooks

هوكات الجيت.

/assets

الأصول الإضافية (الصور ، الشعارات ، الخ).

/website

موقع لتخزين بيانات موقع المشروع إذا كنت لا تستخدم صفحات GitHub.

/src

قد تحتوي مشروعات Go على مجلد src ، ولكن هذا يرجع عادةً إلى المطورين القادمين من عالم Java ، حيث يعتبر نمط شائع. إذا كان ذلك ممكنًا ، فحاول تجنب اعتماد هذا النمط المشابه للجافا. حقًا لا ترغب في أن يبدو كود Go الخاص بك أو مشروعك مثل الجافا :-)

لا تلتبس بين دليل /src على مستوى المشروع مع دليل /src المستخدم لمساحة العمل Go ، الموصوفة في كيفية كتابة كود Go. المتغير البيئي $GOPATH يشير إلى مساحة العمل (الحالية) الخاصة بك (افتراضيًا ، في الأنظمة غير ويندوز يشير إلى دليل $HOME/go). تتضمن هذه المساحة الأدلة العلوية /pkg ، /bin ، و /src. سيكون مشروعك الفعلي مجلدًا فرعيًا تحت دليل /src ، لذا إذا كان لمشروعك دليل /src ، فإن مسار المشروع سيبدو على النحو التالي: /some/path/to/workspace/src/your_project/src/your_code.go. يرجى ملاحظة أنه من إصدار Go 1.11 فصاعدًا ، يمكن تحديد مشروعك خارج GOPATH ، ولكن ذلك لا يعني أن استخدام نمط التخطيط هذا فكرة جيدة.