معماری پیشنهادی برای ساختار پوشه بندی و فایل‌ها  در پروژه های برنامه نویسی فلاتر

ساختار پوشه‌بندی و فایل‌ها در یک پروژه برنامه‌نویسی یکی از جنبه‌های کلیدی در توسعه نرم‌افزار است که تأثیر قابل توجهی بر روی کیفیت کد،

هنگام ایجاد یک پروژه جدید فلاتر، ممکن است با این سوال مواجه شوید که چگونه باید معماری برنامه خود را سازماندهی کنید و بفهمید که کدام بخش‌های خاص از کد باید در کجا قرار بگیرند.

اگر برای یادگیری فلاتر از آموزش های مختلف استفاده کرده باشید، به سرعت متوجه خواهید شد که همه آن‌ها روش‌های بسیار نامنظمی برای سازماندهی کد خود دارند تا به سرعت کد خود را توسعه دهند و موضوع مورد نظر را به شما آموزش دهند.

در اکثر موارد این کار مشکلی ندارد، اما فرض کنید در حال ساخت یک پروژه بزرگ یا ریفکتور کردن یک پروژه موجود هستید؛ شما نمی‌خواهید تمام کد خود را در پوشه /lib قرار دهید! و با هدر دادن وقت زیاد برای فهمیدن این که هر فایل کجا قرار دارد خود را گیج کنید و سرعت برنامه نویسی را کاهش دهید.

بنابراین در این آموزش، ما به یک روش مؤثر برای سازماندهی پروژه فلاتر شما خواهیم پرداخت.

این کار با معماری برنامه شما آغاز می‌شود.

این موضوع به شدت تحت تأثیر ابزاری است که برای مدیریت State انتخاب می‌کنید؛ با این حال، بسیاری از شیوه‌ها همچنان یکسان باقی می‌مانند.

هدف نهایی این است که منطق برنامه (عملکرد برنامه/چیزی که کاربر نمی‌بیند) را از رابط کاربری (چیزی که کاربر می‌بیند و با آن تعامل دارد) جدا کنید.

معماری استفاده شده در این آموزش بر اساس ابزار مدیریت State پکیج Riverpod است.

ساختار پوشه‌بندی و فایل‌ها در یک پروژه برنامه‌نویسی یکی از جنبه‌های کلیدی در توسعه نرم‌افزار است که تأثیر قابل توجهی بر روی کیفیت کد، نگهداری، و همکاری تیمی دارد.

یکی از مهم‌ترین دلایل ایجاد یک ساختار منظم برای پوشه‌ها و فایل‌ها، سازماندهی کد است. با داشتن یک ساختار مشخص، توسعه‌دهندگان می‌توانند به راحتی به کدهای مورد نظر دسترسی پیدا کنند.

این موضوع به خصوص در پروژه‌های بزرگ که شامل هزاران فایل و ماژول هستند، اهمیت بیشتری پیدا می‌کند.

یک ساختار مناسب باعث افزایش قابلیت نگهداری کد می‌شود.

زمانی که کد به خوبی سازماندهی شده باشد، تغییرات و به‌روزرسانی‌ها به راحتی انجام می‌شوند.

این امر به ویژه در پروژه‌های بلندمدت اهمیت دارد، زیرا با گذشت زمان، نیاز به تغییر و بهینه‌سازی کدها اجتناب‌ناپذیر است.

اگر ساختار پروژه منسجم نباشد، این تغییرات می‌توانند منجر به بروز اشکالات و خطاهای جدید شوند.

حالا که نکات مقدماتی را بررسی کردیم، بیایید به نحوه ساختاردهی پروژه‌مان بپردازیم!

اندروید استودیو و یا هر محیط کد نویسی دیگری را باز کنید و یک پروژه جدید فلاتر ایجاد کنید.

ساختار پروژه پیش فرض فلاتر به صورت زیر است.

‣ .dart_tool
‣ .idea
‣ android
‣ ios
‣ lib
‣ linux
‣ macos
‣ test
‣ web
‣ windows
.gitignore
.metadata
analysis_options.yaml
(app_name).iml
pubspec.lock
pubspec.yaml
README.md

برای اهداف این آموزش، ما بر روی ساختار پوشه‌ای دایرکتوری /lib تمرکز خواهیم کرد.

اولین کاری که می‌توانید انجام دهید این است که یک پوشه در دایرکتوری /lib به نام /src ایجاد کنید. اینجا جایی است که تمام عملکردهای برنامه قرار خواهد گرفت. به جز /src، تنها چیزی که می‌خواهید در /lib داشته باشید main.dart است.

اولین پوشه‌ای که قرار است ایجاد کنیم، /config نام دارد. این پوشه شامل داده‌هایی خواهد بود که نحوه رفتار برنامه ما را تعیین می‌کند؛ به طور اساسی، پیکربندی عمومی برای برنامه شما. می‌توانید به آن مانند صفحه تنظیمات یک برنامه فکر کنید، اما این بار برای کد شما.

اکنون می‌خواهیم چند پوشه و فایل دیگر در اینجا اضافه کنیم. دو فایل زیر را ایجاد کنید: constants.dart و environment_keys.dart.

این فایل‌ها به طور نسبی خود توضیحی هستند. به constants.dart به عنوان فایلی فکر کنید که به سادگی شامل تمام متغیرهای عم.می غیرقابل تغییر (immutable) در برنامه شماست.

به مثال زیر توجه کنید.

// src/config/constants.dart

// App Configurations
// Dart imports:
// Flutter imports:
import 'package:flutter/material.dart';
// Project imports:
import 'package:clubology/src/config/themes/system_color.dart';
// Package imports:
const String kAppTitle = 'Clubology';
const String kAppVersionNumber = 'v1.3.3 (37)';
const String kFontFamily = 'General Sans';
const String kAppIconImage = 'assets/icons/app_icon.png';
const String kSplashScreenImage = 'assets/images/splash_screen.png';
// App Padding Configurations
const double kXXXXLPadding = 48.0;
const double kXXXLPadding = 40.0;
const double kXXLPadding = 32.0;
const double kXLPadding = 28.0;
const double kLargePadding = 24.0;
const double kDefaultPadding = 16.0;
const double kMediumPadding = 12.0;
const double kSmallPadding = 10.0;
const double kXSPadding = 8.0;
const double kXXSPadding = 6.0;
const double kXXXSPadding = 4.0;
// App BorderRadii Configurations
const double kDefaultBorderRadius = 20.0;
const double kXSBorderRadius = 4.0;
const double kSmallBorderRadius = 6.0;
const double kMediumBorderRadius = 8.0;
const double kLargeBorderRadius = 12.0;
const double kMaxBorderRadius = 999.0;
// Icon Paths
const String kLogoImagePath = 'assets/icons/logo.png';
const String kLogoLargeImagePath = 'assets/icons/logo_large.png';
const String kAltLogoImagePath = 'assets/icons/alt_logo.png';
const String kStoreIconImagePath = 'assets/icons/store_icon.png';
const String kAppIconImagePath = 'assets/icons/app_icon.png';
const String kAndroidAppIconImagePath = 'assets/icons/android_app_icon.png';
const String kProfilePicture = 'assets/icons/pfp.png';
// Image Paths
const String kSplashScreenImagePath = 'assets/images/splash_screen.png';
// Theme
const String kLightModeImagePath = 'assets/images/light_mode_image.png';
const String kDarkModeImagePath = 'assets/images/dark_mode_image.png';
const String kNormalCaseImagePath = 'assets/images/normal_case_image.png';
const String kLowercaseImagePath = 'assets/images/lowercase_image.png';
// Club Banners
const String kClubBannerOne = 'assets/images/club_banner_one.png';
const String kClubBannerTwo = 'assets/images/club_banner_two.png';
const String kClubBannerThree = 'assets/images/club_banner_three.png';
const String kClubBannerFour = 'assets/images/club_banner_four.png';
const List<String> kClubBannerImages = [kClubBannerOne, kClubBannerTwo, kClubBannerThree, kClubBannerFour];
// Scripts
const String kCronParserJs = 'scripts/cron_parser/out.js';
// Shadows
List<BoxShadow> kMediumBoxShadow = [
  BoxShadow(offset: const Offset(0, 4), spreadRadius: -1, blurRadius: 6, color: SystemColor.black.withOpacity(0.1)),
  BoxShadow(offset: const Offset(0, 2), spreadRadius: -2, blurRadius: 4, color: SystemColor.black.withOpacity(0.1)),
];
// Borders
BoxBorder kDefaultBoxBorder = Border.all(color: SystemColor.gray300, width: 1);
BoxBorder kActiveBoxBorder = Border.all(color: SystemColor.primary500, width: 1);
// General
final gradeLevels = <String>[
  'Not Set',
  'Elementary School',
  'Middle School',
  'High School Freshman (Grade 9, Year 10)',
  'High School Sophomore (Grade 10, Year 11)',
  'High School Junior (Grade 11, Year 12)',
  'High School Senior (Grade 12, Year 13)',
  'College Undergraduate',
  'College Graduate',
];
Map<String, String> bearerTokenAuthorizationHeader(String token) => {
      'Authorization': 'Bearer $token',
    };
extension DateOnlyCompare on DateTime {
  bool isSameDate(DateTime other) {
    return year == other.year && month == other.month && day == other.day;
  }
}

در اینجا ما ثابت‌های مربوط به رابط کاربری و همچنین ثابت‌های عمومی و مربوط به داده‌ها و پیکربندی‌های برنامه را داریم.

حالا برای فایل environment_keys.dart، به آن به عنوان یک فایل .env فکر کنید اگر با آن‌ها کار کرده‌اید.

این فایل شامل تمامی کلیدهای عمومی، خصوصی، کلیدهای مخفی و سایر URLها و داده‌های مشابه خواهد بود. استفاده از .env در فلاتر یک الگوی طراحی رایج نیست، بنابراین ما با استفاده از یک فایل واقعی .dart این موضوع را بهبود می‌بخشیم.

این فایل اساساً مانند فایل constants.dart عمل می‌کند به این معنا که شما تعدادی مقدار غیرقابل تغییر ایجاد می‌کنید.

مطمئن شوید که این فایل را به .gitignore خود اضافه کنید. فلاتر به طور خودکار این فایل را اضافه نخواهد کرد زیرا یک فایل سفارشی است، بنابراین قبل از انجام commit حتماً این کار را انجام دهید.

توجه داشته باشید که /themes یک پوشه است! در صورتی که بخواهید حالت تاریک را در برنامه خود گنجانید، باید ۲ فایل تم جداگانه ایجاد کنید.

در اینجا همچنین دوست دارم متغیرهای تایپوگرافی/تم متن و همچنین رنگ‌های خود را نگه‌دارم. در واقع، سیستم طراحی برنامه شما در اینجا قرار می‌گیرد.

▾ themes
  light_theme.dart
  dark_theme.dart
  text_theme.dart
  source_colors.dart

اگر در حال ساخت یک برنامه هستید که به دسترسی به نقاط پایانی API نیاز دارد، ایجاد یک فایل برای نگهداری انواع مختلف استثناها/خطاهایی که ممکن است با آن‌ها مواجه شوید، قطعاً ایده خوبی است.

معمولاً بهتر است آن‌ها را بر اساس API تقسیم کنید، به همین دلیل /exceptions باید یک پوشه باشد.

ساختار پروژه تا به اینجا به این صورت تغییر کرده است.

▾ config
  ▾ exceptions
    api_exceptions.dart
    auth_exceptions.dart
  ▾ themes
    light_theme.dart
    dark_theme.dart
    text_theme.dart
    source_colors.dart
  constants.dart
  environment_keys.dart

با کمال میل می‌توانید سایر فایل‌های غیرقابل تغییر که مقادیر و توابع را در خود نگه می‌دارند، در اینجا قرار دهید!

این پوشه، همان‌طور که از نامش پیداست، محلی برای نگهداری تمام مدل‌ها/کلاس‌های شما است.

این مدل‌ها حاوی متدهایی برای تبدیل داده‌های JSON به کلاس‌های قابل استفاده هستند که می‌توانید در داخل برنامه خود از آن‌ها استفاده کنید.

در اینجا یک مثال از نحوه سازماندهی این پوشه آورده شده است:

▾ models
  club.dart
  member.dart
  ...

سعی کنید این فایل را تا حد ممکن ساده و منسجم نگه دارید و در عین حال توابع لازم را داشته باشید.

اگر برنامه شما به هر نوع عملکرد API خارجی، اینترنتی یا محلی نیاز دارد، باید آن را در اینجا قرار دهید. پوشه خدمات مسئول مدیریت این موارد خواهد بود.

یک بار دیگر، شما به پوشه‌های تقسیم‌شده نیاز خواهید داشت تا انواع مختلف خدماتی که پیاده‌سازی می‌کنید را مدیریت کنید.

اگر به یک پوشه برای خدمات ذخیره‌سازی محلی نیاز دارید، یک پوشه به نام /storage_services ایجاد کنید.

اگر به یک پوشه برای ارائه‌دهندگان احراز هویت (یا احراز هویت به طور کلی) نیاز دارید، یکی به نام /auth_services ایجاد کنید. در اینجا ساختار باید به چه صورت باشد:

▾ services
  ▾ authentication_services
    apple_sign_in_service.dart
    google_sign_in_service.dart
    email_password_sign_in_service.dart
    ...
  ▾ database_services
    club_service.dart
    member_service.dart
    ...
  dio_provider.dart
  ...

اگر شما یک API سفارشی برای برنامه خود راه‌اندازی کرده‌اید، به عنوان مثال، یک سرور express.js، سپس می‌خواهید یک پوشه به نام /database_services ایجاد کنید.

در این پوشه، برای هر نقطه پایانی (endpoint)، یک فایل بسازید و توابع لازم برای دسترسی به هر نقطه پایانی را اضافه کنید.

محبوب‌ترین پکیج برای اتصال به وبسرویس پکیج Dio در فلاتر است.

طبق اطلاعات موجود در سایت آن‌ها، Dio “یک بسته قدرتمند برای شبکه‌سازی HTTP است که از Interceptors، لغو و کنسل کردن درخواست، آداپترهای سفارشی، ترنسفورمرها و غیره پشتیبانی می‌کند.”

در اینجا پیکربندی من برای Dio آورده شده است که می‌توانید در کد خود نیز از آن استفاده کنید! این پیکربندی شامل یک تجزیه‌کننده JSON، ترنسفورمر و کش خودکار است!

// src/services/dio_provider.dart

// Dart imports:
import 'dart:async';
import 'dart:convert';
// Flutter imports:
import 'package:flutter/foundation.dart';
// Package imports:
import 'package:dio/dio.dart';
import 'package:flutter_riverpod/flutter_riverpod.dart';
import 'package:riverpod_annotation/riverpod_annotation.dart';
import 'package:sentry_dio/sentry_dio.dart';
// Project imports:
import 'package:clubology/src/config/environment_keys.dart';
// import 'package:pretty_dio_logger/pretty_dio_logger.dart';

part 'dio_provider.g.dart';
class DioTransformer extends DefaultTransformer {
  DioTransformer() : super(jsonDecodeCallback: _parseJson);
}
// Must be top-level function
_parseAndDecode(String response) {
  return jsonDecode(response);
}
_parseJson(String text) {
  return compute(_parseAndDecode, text);
}
@riverpod
Dio dio(DioRef ref, {Map<String, dynamic>? headers, String? subDomain}) {
  final dio = Dio(BaseOptions(baseUrl: '$kBaseAPIURL${subDomain ?? ''}', headers: headers))
    ..transformer = DioTransformer();
  if (kReleaseMode) {
    dio.addSentry(captureFailedRequests: true, networkTracing: true);
  } else {
    // dio.interceptors.add(
    //   PrettyDioLogger(
    //     requestHeader: true,
    //     requestBody: true,
    //     responseBody: true,
    //     responseHeader: true,
    //     error: true,
    //     compact: true,
    //   ),
    // );
  }
  return dio;
}
extension AutoDisposeRefCache on AutoDisposeRef {
  // keeps the provider alive for [duration] since when it was first created
  // (even if all the listeners are removed before then)
  void cacheFor(Duration duration) {
    final link = keepAlive();
    final timer = Timer(duration, () => link.close());
    onDispose(() => timer.cancel());
  }
}

ما به‌طور موفقیت‌آمیزی منطق کسب‌وکار خود را از صفحات (اسکرین‌ها) خود از طریق تمام پوشه‌های قبلی جدا کردیم. حالا قصد داریم صفحات و اجزای خود را ایجاد کنیم.

نکته: اگر بخواهید، می‌توانید پوشه /themes را به اینجا منتقل کنید.

ما همه چیز را به دو پوشه جدا می‌کنیم: /components و /screens. پوشه /components به سادگی شامل تمام ویجت‌های قابل استفاده مجدد است که در چندین صفحه در سرتاسر برنامه شما استفاده می‌شوند.

شما می‌توانید اجزای UI سفارشی را در اینجا قرار دهید یا حتی ویجت‌های پیش‌فرض متریال یا کوپرتینو که توسط فلاتر ارائه شده‌اند را در اینجا جایگزین کنید!

در اینجا یک مثال از آنچه ممکن است به نظر برسد آورده شده است:

▾ components
  primary_button.dart
  show_club_bottom_sheet.dart
  action_button.dart
  system_text_input.dart
  close_button.dart
  spinner.dart
  ...

توجه: View و Screen به یک معنا هستند.

ما تمام نماهای خود را در پوشه‌های جداگانه سازماندهی خواهیم کرد.

در هر پوشه نه تنها صفحه، بلکه اجزای خاص آن صفحه نیز قرار خواهند گرفت.

این یک روش خوب است که یک زیرپوشه دیگر به نام /components در داخل پوشه view ایجاد کنید تا مشخص شود که کجا خود نما قرار دارد و اجزا.

این کار باعث می‌شود ایمپورت های شما کمی منظم‌تر شود و به شما کمک می‌کند به راحتی فایل‌های خود را پیدا کنید.

این یک روش خوب است، اما اگر معتقد نیستید که برنامه/کد شما به آن نیاز دارد، نیازی به انجام آن نیست.

همچنین پیشنهاد می‌کنم کامپوننت یا ویجت ها را با یک قانون نام‌گذاری نام‌گذاری کنید که به نوعی شامل نام صفحه باشد، چه به صورت اختصاری و چه به صورت کامل. بار دیگر، این کاملاً به خود شما بستگی دارد.

یک روش دیگر که بار دیگر می‌گویم نیازی به انجام آن نیست اما به سازماندهی بهتر منجر می‌شود، ایجاد یک نمای کلی و سپس زیرپوشه‌هایی برای هر زیرنما در داخل صفحه است.

برای مثال، فرض کنید ما یک برنامه خبری داریم. فرض کنید روی یک مقاله کلیک می‌کنیم و سپس برنامه یک درخواست GET برای بازیابی تمام جزئیات مقاله انجام می‌دهد.

پس از اتمام این درخواست GET، به صفحه‌ای به نام article_view.dart منتقل می‌شود. در این صفحه مقاله، یک دکمه داریم که به صفحه‌ای می‌رود که “متادیتا” یا جزئیات اضافی درباره مقاله را ارائه می‌دهد مانند زمان دقیق انتشار، نام گزارشگر و عنوان و غیره. این صفحه و اطلاعات به هیچ روش دیگری در برنامه قابل دسترسی نیست مگر اینکه از طریق خود مقاله بروید.

در این مورد، شما می‌توانید یک زیرپوشه داخل /article_views به نام article_views/article_info_view ایجاد کنید و در آنجا article_info_view.dart را قرار دهید. سپس از article_view.dart می‌توانید با استفاده از Navigator.push(...) در دکمه به article_info_view.dart بروید.

یک مثال از ساختار پروژه در این مرحله

▾ views
  ▾ club_views
    ▾ components
      club_view_app_bar.dart
      club_view_show_club_details_bottom_sheet.dart
      ...
    ▾ club_settings_view
      ▾ components
        club_settings_view_app_bar.dart
      club_settings_view.dart
      ▾ club_announcement_view
        club_announcement_view.dart
    club_view.dart
  ▾ settings_view
    ▾ components
      sv_app_bar.dart
      sv_card.dart
    settings_view.dart
  ▾ home_view
    ▾ components
      app_bar.dart
    home_view.dart
  ▾ welcome_view
      welcome_view.dart

ساختار نهایی پروژه میتوانید حالتی شبیه به ساختار زیر باشد که در آن فایل ها به خوبی از یکدیگر تفکیک شده اند.

▾ lib
  ▾ src
    ▾ config
      ▾ exceptions
        api_exceptions.dart
        auth_exceptions.dart
      ▾ themes
        light_theme.dart
        dark_theme.dart
        text_theme.dart
        source_colors.dart
      constants.dart
      environment_keys.dart
      ...
    ▾ models
      club.dart
      user.dart
      ...
    ▾ services
      ▾ authentication_services
        apple_sign_in_service.dart
        google_sign_in_service.dart
        email_password_sign_in_service.dart
        ...
      ▾ database_services
        club_service.dart
        member_service.dart
        ...
      dio_provider.dart
      ...
    ▾ ui
      ▾ components
        primary_button.dart
        show_club_bottom_sheet.dart
        action_button.dart
        system_text_input.dart
        close_button.dart
        spinner.dart
        ...
    ▾ views
      ▾ club_views
        ▾ components
          club_view_app_bar.dart
          club_view_show_club_details_bottom_sheet.dart
          ...
    ▾ club_settings_view
      ▾ components
        club_settings_view_app_bar.dart
        club_settings_view.dart
      ▾ club_announcement_view
        club_announcement_view.dart
        club_view.dart
      ▾ settings_view
        ▾ components
          sv_app_bar.dart
          sv_card.dart
          settings_view.dart
      ▾ home_view
        ▾ components
          app_bar.dart
        home_view.dart
      ▾ welcome_view
        welcome_view.dart
      ...
main.dart
‣ linux
‣ macos
‣ test
‣ web
‣ windows
.gitignore
.metadata
analysis_options.yaml
(app_name).iml
pubspec.lock
pubspec.yaml
README.md

سازماندهی مؤثر پروژه‌های فلاتر شما برای حفظ یک کدبیس تمیز و اطمینان از مقیاس‌پذیری آینده برنامه‌های شما بسیار حیاتی است.

با جدا کردن منطق کسب‌وکار از اجزای رابط کاربری و سازماندهی منطقی فایل‌ها و پوشه‌های خود، می‌توانید قابلیت خوانایی و نگهداری کد خود را بهبود بخشید.

به یاد داشته باشید که یک پروژه به‌خوبی ساختار یافته نه تنها به نفع شماست، بلکه در همکاری با دیگران نیز کمک می‌کند.

دیدگاه‌ها (0)

    دیدگاه خود را بنویسید

    ایمیل شما نمایش داده نمی‌شود. دیدگاه پس از تأیید نمایش داده می‌شود.