ساخت یک برنامه کامل Dart با توابع ابری برای Firebase

۱. مقدمه

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

همچنین یاد می‌گیرید که چگونه مدل‌های داده را بین برنامه و سرور خود به اشتراک بگذارید و نیاز به منطق تکراری را از بین ببرید.

آنچه یاد خواهید گرفت

• منطق تجاری مشترک را در یک بسته Dart مستقل استخراج کنید.
• توابع ابری را برای فایربیس به صورت بومی در دارت بنویسید و مستقر کنید.
• از کامپایل Ahead-of-Time (AOT) دارت برای کاهش شروع‌های سرد بدون سرور استفاده کنید.
• با استفاده از مجموعه شبیه‌ساز Firebase، پشته خود را به صورت محلی آزمایش کنید.

۲. پیش‌نیازها

• کیت توسعه نرم‌افزار فلاتر (آخرین نسخه پایدار).
• رابط خط فرمان فایربیس (نسخه ۱۵.۱۵.۰ یا بالاتر مورد نیاز است).
• یک ویرایشگر کد، مانند Antigravity ، Visual Studio Code، IntelliJ یا Android Studio، که افزونه‌های Dart و Flutter روی آن نصب شده باشد.
• آشنایی اولیه با Flutter و Firebase

۳. چرا از دارت برای بک‌اند استفاده کنیم؟

بسیاری از برنامه‌های ابری از Dart برای رابط کاربری frontend و زبان دیگری مانند TypeScript، Python یا Go برای backend استفاده می‌کنند. این امر مستلزم حفظ دو مجموعه جداگانه از مدل‌های داده است. هنگامی که یک طرحواره پایگاه داده تغییر می‌کند، باید هر دو پایگاه داده را به‌روزرسانی کنید.

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

۴. اپلیکیشن فلاتر را ایجاد کنید

یک برنامه استاندارد Flutter ایجاد کنید:

flutter create my_counter
cd my_counter
# Run the app to see the default counter example
flutter run

در یک برنامه استاندارد فلاتر، lib/main.dart حالت شمارنده را به صورت محلی مدیریت می‌کند:

int _counter = 0;

void _incrementCounter() {
  setState(() {
    _counter++;
  });
}

این رویکرد برای حالت محلی کار می‌کند، اما برای یک برنامه چند نفره که در آن سرور باید به عنوان منبع حقیقت عمل کند، قابل استفاده نیست. برای پشتیبانی از چندین بازیکن، این منطق را در مراحل بعدی به backend منتقل خواهیم کرد.

۵. بسته اشتراکی را ایجاد کنید

برای جلوگیری از تکرار مدل‌ها در frontend و backend، یک پکیج Dart مشترک در مخزن پروژه خود ایجاد کنید. هم برنامه Flutter و هم توابع Firebase به این پکیج وابسته هستند.

از ریشه پروژه my_counter ، دستورات زیر را اجرا کنید:

mkdir -p packages
cd packages
dart create -t package shared

وابستگی‌ها را اضافه کنید

در packages/shared/pubspec.yaml ، ابزارهای سریال‌سازی JSON را اضافه کنید:

dependencies:
  json_annotation: ^4.9.0

dev_dependencies:
  build_runner: ^2.4.9
  json_serializable: ^6.8.0

مدل‌های مشترک خود را تعریف کنید

packages/shared/lib/src/models.dart را ایجاد کنید. این فایل ساختار داده مورد استفاده توسط برنامه و سرور را تعریف می‌کند.

import 'package:json_annotation/json_annotation.dart';

part 'models.g.dart';

@JsonSerializable()
class IncrementResponse {
  final bool success;
  final String? message;
  final int? newCount;

  const IncrementResponse({required this.success, this.message, this.newCount});

  factory IncrementResponse.fromJson(Map<String, dynamic> json) =>
      _$IncrementResponseFromJson(json);

  Map<String, dynamic> toJson() => _$IncrementResponseToJson(this);
}

// Store the function name as a constant to ensure consistency between client and server.
const incrementCallable = 'increment';

در packages/shared/lib/shared.dart ، مدل‌های خود را اکسپورت کنید:

library shared;

export 'src/models.dart';

در دایرکتوری packages/shared ، دستور build runner را اجرا کنید تا کد سریال‌سازی JSON تولید شود:

dart run build_runner build

۶. تنظیم توابع ابری برای فایربیس

توابع ابری برای فایربیس یک چارچوب بدون سرور است که به شما امکان می‌دهد بدون نیاز به مدیریت و مقیاس‌بندی سرورهای خود، به طور خودکار کد بک‌اند را اجرا کنید. دارت گزینه بسیار مناسبی است زیرا Ahead-of-Time (AOT) را به یک فایل باینری کامپایل می‌کند و به یک محیط زمان اجرای سنگین مانند Node.js یا جاوا نیاز ندارد. این امر به طور قابل توجهی زمان شروع سرد برای توابع شما را کاهش می‌دهد.

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

cd ../..
firebase experiments:enable dartfunctions
firebase init functions
dart pub add google_cloud_firestore

• وقتی از شما زبان خواسته شد، Dart را انتخاب کنید.

بسته اشتراکی را پیوند دهید

در functions/pubspec.yaml ، یک مسیر نسبی به بسته‌ی مشترک اضافه کنید:

dependencies:
  firebase_functions:
  google_cloud_firestore:
  shared:
    path: ../packages/shared

۷. تابع را بنویسید

برای نوشتن منطق backend، functions/bin/server.dart را باز کنید و محتویات آن را با کد زیر جایگزین کنید:

import 'dart:convert';
import 'package:firebase_functions/firebase_functions.dart';
import 'package:google_cloud_firestore/google_cloud_firestore.dart'
    show FieldValue;
import 'package:shared/shared.dart';

void main(List<String> args) async {
  await fireUp(args, (firebase) {

    // Listen for calls to the http request and name defined in the shared package.
    firebase.https.onRequest(name: incrementCallable, (request) async {

      // In a production app, verify the user with request.auth?.uid here.
      print('Incrementing counter on the server...');

      // Get firestore database instance
      final firestore = firebase.adminApp.firestore();

      // Get a reference to the counter document
      final counterDoc = firestore.collection('counters').doc('global');

      // Get the current snapshot for the count data
      final snapshot = await counterDoc.get();

      // Increment response we will send back
      IncrementResponse incrementResponse;

      // Check for the current count and if the snapshot exists
      if (snapshot.data() case {'count': int value} when snapshot.exists) {
        if (request.method == 'GET') {
          // Get the current result
          incrementResponse = IncrementResponse(
            success: true,
            message: 'Read-only sync complete',
            newCount: value,
          );
        } else if (request.method == 'POST') {
          // Increment count by one
          final step = request.url.queryParameters['step'] as int? ?? 1;
          await counterDoc.update({'count': FieldValue.increment(step)});
          incrementResponse = IncrementResponse(
            success: true,
            message: 'Atomic increment complete',
            newCount: value + step,
          );
        } else {
          throw FailedPreconditionError(
            'only GET and POST requests are allowed',
          );
        }
      } else {
        // Create a new document with a count of 1
        await counterDoc.set({'count': 1});
        incrementResponse = const IncrementResponse(
          success: true,
          message: 'Cloud-sync complete',
          newCount: 1,
        );
      }

      // Return the response as JSON
      return Response(
        200,
        body: jsonEncode(incrementResponse.toJson()),
        headers: {'Content-Type': 'application/json'},
      );
    });

  });
}

۸. تست محلی با مجموعه شبیه‌ساز Firebase

شما می‌توانید هم frontend و هم backend را به صورت محلی و بدون نیاز به استقرار (deployment) اجرا کنید.

از ریشه پروژه خود، Firebase Emulator Suite را اجرا کنید:

# Enable functions and firestore for the emulators
firebase init emulators
# Start the emulators and optionally open up the Admin UI
firebase emulators:start

بسته اشتراکی را پیوند دهید

در pubspec.yaml ، یک مسیر نسبی به بسته‌ی اشتراکی اضافه کنید و بسته‌ی http را اضافه کنید:

dependencies:
  http: ^1.6.0
  shared:
    path: /packages/shared

در پروژه فلاتر خود، lib/main.dart را باز کنید و محتویات آن را با کد زیر جایگزین کنید. این کد frontend از همان کلاس IncrementResponse که در backend استفاده شده است، استفاده می‌کند.

import 'dart:convert';

import 'package:http/http.dart' as http;
import 'package:flutter/foundation.dart';
import 'package:flutter/material.dart';
import 'package:shared/shared.dart';

/// Get from emulator output when running or when deploying:
/// ✔ functions[us-central1-increment]: http function initialized
///  (http://127.0.0.1:5001/demo-no-project/us-central1/increment).
const incrementUrl = 'FIREBASE_FUNCTIONS_URL_HERE';

void main() {
  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});
  @override
  Widget build(BuildContext context) => MaterialApp(
    debugShowCheckedModeBanner: false,
    theme: ThemeData(useMaterial3: true, colorSchemeSeed: Colors.blue),
    home: const CounterPage(),
  );
}

class CounterPage extends StatefulWidget {
  const CounterPage({super.key});
  @override
  State<CounterPage> createState() => _CounterPageState();
}

class _CounterPageState extends State<CounterPage> {
  int _count = 0;
  bool _loading = false;

  @override
  void initState() {
    super.initState();
    // Fetch the current count
    _increment(readOnly: true).ignore();
  }

  Future<void> _increment({bool readOnly = false}) async {
    setState(() => _loading = true);
    try {
       // Call the Dart function.
      final uri = Uri.parse(incrementUrl);
      final response = readOnly ? await http.get(uri) : await http.post(uri);

      // Parse the response back into the shared Dart object.
      final responseData = jsonDecode(response.body);
      final incrementResponse = IncrementResponse.fromJson(responseData);

      if (incrementResponse.success) {
        setState(() => _count = incrementResponse.newCount ?? _count);
      }
    } catch (e) {
      print("Error calling function: $e");
    } finally {
      setState(() => _loading = false);
    }
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Multiplayer Counter')),
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: [
            const Text('You have pushed the button this many times:'),
            Text(
              '$_count',
              style: Theme.of(context).textTheme.headlineMedium,
            ),
          ],
        ),
      ),
      floatingActionButton: FloatingActionButton(
        onPressed: _loading ? null : _increment,
        tooltip: 'Increment',
        child: const Icon(Icons.add),
      ),
    );
  }
}

برنامه Flutter را اجرا کنید. وقتی روی دکمه اکشن شناور کلیک می‌کنید، برنامه backend محلی Dart را فراخوانی می‌کند، تعداد جدید را بازیابی می‌کند و رابط کاربری را به‌روزرسانی می‌کند.

۹. استقرار در فایربیس

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

ایجاد یک پروژه فایربیس

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

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

   شناسه پروژه خود را به خاطر بسپارید زیرا بعداً برای شناسایی پروژه Firebase خود در Firebase CLI به آن نیاز خواهید داشت. اگر شناسه خود را فراموش کردید، همیشه می‌توانید بعداً آن را در تنظیمات پروژه پیدا کنید.

3. روی ادامه کلیک کنید.
4. در صورت درخواست، شرایط Firebase را مرور و قبول کنید و سپس روی ادامه کلیک کنید.
5. (اختیاری) دستیار هوش مصنوعی را در کنسول Firebase (با نام "Gemini در Firebase") فعال کنید.
6. برای این codelab، به گوگل آنالیتیکس نیاز ندارید ، بنابراین گزینه گوگل آنالیتیکس را غیرفعال کنید .
7. روی ایجاد پروژه کلیک کنید، منتظر بمانید تا پروژه شما آماده شود و سپس روی ادامه کلیک کنید.

طرح قیمت‌گذاری فایربیس خود را ارتقا دهید

برای استفاده از سرویس‌های فایربیس در این آزمایشگاه کد، پروژه فایربیس شما باید در طرح قیمت‌گذاری پرداخت در محل (Blaze) باشد، به این معنی که به یک حساب پرداخت ابری (Cloud Billing ) متصل باشد.

• یک حساب Cloud Billing به یک روش پرداخت، مانند کارت اعتباری، نیاز دارد.
• در طول تخفیف‌های ویژه یا اگر این codelab را به عنوان بخشی از یک رویداد انجام می‌دهید، ممکن است اعتبار Google Cloud در دسترس باشد.
• اگر در استفاده از فایربیس و گوگل کلود تازه‌کار هستید، بررسی کنید که آیا واجد شرایط دریافت اعتبار ۳۰۰ دلاری و یک حساب کاربری رایگان ابری هستید یا خیر.

برای ارتقاء پروژه خود به طرح Blaze، مراحل زیر را دنبال کنید:

1. در کنسول Firebase، گزینه ارتقاء پلن خود را انتخاب کنید.
2. طرح Blaze را انتخاب کنید. دستورالعمل‌های روی صفحه را دنبال کنید تا یک حساب Cloud Billing به پروژه شما متصل شود.
   
   • اگر از اعتبارهای Google Cloud برای این codelab استفاده می‌کنید، حساب صورتحساب احتمالاً Google Cloud Platform Trial Billing Account یا My Billing Account نامیده می‌شود.
   • اگر به عنوان بخشی از این ارتقا نیاز به ایجاد یک حساب Cloud Billing داشتید، ممکن است لازم باشد برای تکمیل ارتقا، به روند ارتقا در کنسول Firebase برگردید.

توجه : پس از تکمیل این کدلاگ، می‌توانید پروژه خود را به طرح قیمت‌گذاری بدون هزینه (Spark) کاهش دهید .

به پروژه Firebase خود مستقر کنید

برای استقرار backend دارت، دستور زیر را با استفاده از Firebase CLI اجرا کنید:

firebase use <PROJECT_ID>
firebase deploy --only functions

پس از اجرای دستور، URL را کپی کرده و FIREBASE_FUNCTIONS_URL_HERE در کد منبع برنامه flutter که قبلاً اضافه کردیم، جایگزین کنید.

۱۰. عیب‌یابی

firebase: command not found

مطمئن شوید که Firebase CLI نصب شده و PATH شما به‌روزرسانی شده است. می‌توانید آن را با استفاده از npm نصب کنید: npm install -g firebase-tools .

دارت در قالب‌های توابع init وجود ندارد

برای اینکه دارت هنگام اجرای firebase init functions لیستی از گزینه‌های استقرار و ایجاد کد الگو را نشان دهد، باید با اجرای firebase experiments:enable dartfunctions یک پرچم آزمایش تنظیم شود.

شبیه‌ساز توابع متصل نمی‌شود

تأیید کنید که از localhost و پورت 5001 استفاده می‌کنید. اگر روی یک شبیه‌ساز اندروید آزمایش می‌کنید، دستگاه localhost به دستگاه میزبان شما اختصاص نمی‌دهد. پیکربندی شبیه‌ساز را در main.dart به‌روزرسانی کنید تا 10.0.2.2 استفاده کند.

بسته مشترک یافت نشد

مسیر نسبی را در functions/pubspec.yaml بررسی کنید. اگر ساختار پوشه شما با codelab متفاوت است، path: ../packages/shared را طوری تنظیم کنید که به دایرکتوری صحیح اشاره کند.

آیا باید از json_serializable استفاده کنم؟

اگرچه کاملاً الزامی نیست، اما استفاده از json_serializable از خطاهای ناشی از نوشتن دستی متدهای fromJson و toJson جلوگیری می‌کند. این تضمین می‌کند که frontend و backend شما دقیقاً از یک قالب داده استفاده می‌کنند.

۱۱. تبریک

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