Firebase Cloud Functions — какво е, тригери и как се пишат функции

Какво е Firebase Cloud Functions и как е изградено

Firebase Cloud Functions е изчислителна платформа, изградена на базата на Google Cloud Functions (GCF), адаптирана за екосистемата на Firebase. Функциите представляват обикновен JavaScript или TypeScript код, експортиран от модул и регистриран за определен тип събитие. Когато събитието настъпи (например потребител се регистрира или качва файл), Firebase Cloud Functions стартира съответния код, предавайки му контекста на събитието.

Архитектурата на Cloud Functions следва принципа за единна отговорност: една функция обработва един тип събитие и изпълнява една атомарна операция. Например функцията sendWelcomeEmail се извиква при създаването на нов потребител във Firebase Authentication и изпраща приветствено писмо. Такава изолация опростява отстраняването на грешки, тестването и повторното използване на функции в различни проекти.

Всяка функция се изпълнява в изолиран контейнер с временен жизнен цикъл. Максималното време на изпълнение по подразбиране е 60 секунди (HTTPS функции — 9 минути). Ако функцията не се побере в таймаута, заявката приключва с грешка 500. За дълги операции използвайте Cloud Tasks или Pub/Sub с повторни опити. Контейнерите могат да се преизползват за последващи извиквания (keep-alive), което намалява забавянето при студени стартове след първото извикване.

Среда на изпълнение и версии на Node.js

Firebase Cloud Functions поддържа няколко версии на Node.js: 18, 20 и 22 (препоръчителна за нови проекти). Изборът на версия се задава в полето engines на файла package.json. Firebase CLI автоматично конфигурира средата на изпълнение въз основа на посочената версия. Важно: Firebase Cloud Functions не поддържа стартирането на произволни Docker контейнери — средата е строго фиксирана от Google Cloud Functions.

За нови проекти се препоръчва Node.js 22, тъй като включва последните оптимизации на V8, подобрена работа с ESM модулите и поддръжка на WebSocket на ниво платформа. Ако проектът използва зависимости, компилирани за конкретна версия на Node (например нативни C++ модули), съвместимостта трябва да се провери отделно — не всички нативни модули се компилират в средата на GCF.

Разлика между Firebase Cloud Functions и Google Cloud Functions

Firebase Cloud Functions е обвивка над Google Cloud Functions с предварително инсталиран Firebase SDK и интеграция с услугите на Firebase. Разработчикът пише код чрез SDK firebase-functions, който предоставя типизирани тригери за всички услуги на Firebase. Google Cloud Functions е платформа от по-ниско ниво, където тригерите се конфигурират изрично чрез Eventarc или Pub/Sub.

Ключовата разлика: в Firebase Cloud Functions тригерът се регистрира декларативно чрез извикването functions.firestore.document('path').onWrite(), а в Google Cloud Functions — чрез конфигурация на Eventarc с филтриране по атрибути на събитието. Firebase Cloud Functions също така автоматично се доставя с Admin SDK, инициализиран с правата на служебния акаунт на проекта, което дава пълен достъп до всички услуги на Firebase без допълнителна конфигурация.

Видове тригери: кои събития се поддържат

Firebase Cloud Functions поддържа 8 категории тригери, всяка от които съответства на определена услуга на Firebase или Google Cloud. Тригерът е условие, при чието настъпване функцията се извиква автоматично. Разработчикът не управлява директно жизнения цикъл на функцията: Firebase CLI регистрира тригера в Google Cloud Eventarc, а облачната платформа сама стартира функцията при настъпване на събитието.

Най-популярните тригери — Firestore тригери: onWrite, onCreate, onUpdate, onDelete. Те се задействат при промяна на документи в колекциите на Firestore. Функцията получава моментни снимки на документа преди и след промяната, което позволява сравняване на стойностите и реагиране само на определени промени. Например при промяна на статуса на поръчката от "pending" на "shipped" можете да изпратите push известие на потребителя.

Authentication тригери (onCreate, onDelete) се задействат при създаване или изтриване на акаунт. Използват се за инициализиране на потребителски данни: създаване на документ на потребителя във Firestore, изпращане на приветствен имейл, запис в аналитиката. Важно: функцията не може да отмени създаването на потребителя — тя се изпълнява, след като акаунтът вече е създаден. За предварителна валидация използвайте блокиращи функции (Blocking Functions), достъпни на платформата Identity Platform.

HTTPS тригери и CORS

HTTPS функциите (onRequest) позволяват създаването на пълноценни REST API крайни точки, достъпни чрез HTTP. За разлика от тригерите за събития, HTTPS функциите се извикват чрез URL от вида https://{region}-{project}.cloudfunctions.net/{functionName}. Важно е да конфигурирате правилно CORS, ако крайната точка се извиква от браузър или мобилно приложение. Firebase SDK не включва автоматично CORS хедърите — те трябва да се добавят ръчно чрез middleware.

За мобилните клиенти (Android, iOS) CORS не е необходим, тъй като нативните HTTP клиенти не са ограничени от политиката Cross-Origin. CORS е актуален само за уеб заявки. Ако вашата HTTPS функция се извиква и от приложението, и от уеб, добавете универсална обработка на CORS: res.set('Access-Control-Allow-Origin', '*') за development или списък с разрешени домейни за production.

Планиране с Pub/Sub и Cloud Scheduler

За периодично изпълнение (cron задачи) използвайте комбинацията от Cloud Scheduler и Pub/Sub. Cloud Scheduler изпраща съобщение до Pub/Sub топик по разписание, а тригерът onPublish обработва това съобщение. Firebase CLI не поддържа директен cron синтаксис — разписанието се задава чрез конзолата на Google Cloud или Terraform във формат unix-cron: 0 3 * * * (всеки ден в 3:00).

Примери за задачи: ежедневна разпратка, почистване на остарели данни, генериране на отчети, синхронизация с външни API. Важно: Cloud Scheduler е платена услуга на Google Cloud (около 2 $ на месец за една задача). Всяко задействане се счита за отделно извикване на функция и се таксува по стандартните цени на Cloud Functions.

Как да пишем и разгръщаме функции

Разработката на Cloud Functions започва с инициализация на проекта чрез Firebase CLI: firebase init functions. Тази команда създава директория functions/ с шаблона index.js (или index.ts), файла package.json и конфигурацията на TypeScript (ако е избран). След инициализацията е достатъчно да напишете функция, да я експортирате от модула и да изпълните firebase deploy --only functions за разгръщане.

Всяка функция се регистрира чрез извикване на метода на съответния тригер. Пример за HTTPS функция: exports.helloWorld = functions.https.onRequest((req, res) => { res.send("Hello!"); }). Функциите на Firebase използват асинхронен модел: за тригери за събития (не HTTPS) функцията трябва да връща Promise. Firebase очаква завършването на Promise преди затваряне на контейнера. Ако Promise не бъде върнат, функцията може да бъде прекъсната преди завършването на асинхронните операции.

Локалната разработка се извършва чрез Firebase Emulator Suite, който включва емулатор на Cloud Functions. Командата firebase emulators:start стартира локален сървър с функции, достъпен на адрес http://localhost:5001. Емулаторът поддържа горещо презареждане (hot reload) при промяна на кода и е напълно изолиран от производствената среда, което позволява тестване на функции без риск от въздействие върху реалните данни.

Управление на зависимостите и конфигурацията

Зависимостите на Cloud Functions се управляват чрез package.json. Firebase инсталира само производствените зависимости (dependencies, не devDependencies). Размерът на пакета от функции влияе на времето за студен старт: препоръчва се минимализиране на броя на зависимостите. За работа с Firebase Admin SDK зависимостта firebase-admin вече е предварително инсталирана — не е необходимо да се добавя ръчно.

Конфиденциалните данни (API ключове, токени) не трябва да се съхраняват в кода на функцията. Използвайте functions.config() за съхраняване на конфигурация: firebase functions:config:set stripe.key="sk_...". Стойностите са криптирани и достъпни по време на изпълнение чрез functions.config().stripe.key. За големи сериализирани конфигурации използвайте Google Cloud Secret Manager.

Обработка на грешки и регистриране

Регистрирането в Cloud Functions се извършва чрез console.log, console.warn и console.error. Всички логове автоматично се събират в Google Cloud Logging и са достъпни в конзолата на Firebase (секция Functions > Logs). За структурирано регистриране използвайте библиотеката winston или pino, които поддържат форматиране на JSON и нива на регистриране.

Обработката на грешки е критична за надеждността: необработено изключение в Promise приключва функцията с грешка, след което Firebase автоматично повтаря извикването (retry) с експоненциално забавяне. Броят на опитите се конфигурира: от 0 до безкрайност. За тригери за събития се препоръчва включване на retry, за да се гарантира обработката на всяко събитие дори при временни повреди на външни услуги.

Студен старт и мащабиране

Студеният старт (cold start) е забавянето при първото извикване на функция след период на бездействие, когато контейнерът с кода се зарежда и инициализира отново. Според Firebase documentation (2026), студеният старт продължава от 200 ms до 2 секунди в зависимост от размера на пакета, броя на зависимостите и региона. За потребителския интерфейс забавяне над 1 секунда е забележимо и може да повлияе на user experience.

Начини за минимализиране на студения старт: минимализиране на зависимостите, използване на TypeScript с компилация в CommonJS, намаляване на размера на пакета от функции, задаване на минимален брой активни инстанции. Firebase Cloud Functions v2 (2nd gen) позволява задаване на minInstances — минимален брой подготвени контейнери, които винаги са готови за обработка на заявки. За поддържането на контейнерите в готовност се таксува времето на престой.

Мащабирането на Cloud Functions става автоматично: при увеличаване на броя на заявките Firebase създава нови контейнери. По подразбиране максималният брой паралелни инстанции е 3000 (квота на проекта в Google Cloud). Всяка инстанция обработва една заявка едновременно. Ако функцията е бърза (под 100 ms), една инстанция може да обработи до 10 заявки в секунда, което дава пикова пропускателна способност до 30 000 заявки в секунда на проект.

Конфигуриране на minInstances и maxInstances

minInstances е параметър, който резервира посочения брой контейнери и ги поддържа в готовност. Препоръчва се за критични HTTPS функции, където забавянето при студен старт е недопустимо. Например за крайна точка за удостоверяване задайте minInstances: 1. maxInstances е ограничение за максималния брой паралелни инстанции, полезно за предотвратяване на неконтролиран ръст на разходите при внезапен скок на трафика.

Конфигурацията се извършва в кода: functions.runWith({ minInstances: 1, maxInstances: 10 }). Важно: minInstances увеличава разходите, тъй като контейнерът работи непрекъснато. За тестови проекти minInstances трябва да се изключва. За production се препоръчва minInstances за всички публични HTTPS функции и 0 за тригери за събития, където забавяне от 1 секунда не е критично.

Региони за разгръщане

Регионът на разгръщане влияе на забавянето до крайните потребители и на цената на изходящия трафик. Firebase Cloud Functions е достъпен в над 30 региона на Google Cloud. За мобилни приложения избирайте региона, най-близък до вашата целева аудитория: us-central1 за Америка, europe-west1 за Европа, asia-east2 за Азия. Регионът не може да бъде променен след deploy без повторно разгръщане на функцията.

Промяната на региона се извършва чрез параметъра region в кода: functions.region('europe-west1'). Всички функции в един файл могат да имат различни региони. За глобални проекти се препоръчва разгръщане на функции в няколко региона и използване на Cloud Load Balancing за разпределение на трафика, въпреки че за повечето мобилни приложения един регион е достатъчен при правилен избор.

Примери за код за Firebase Cloud Functions

Нека разгледаме практически примери за Cloud Functions на TypeScript. Кодът използва Firebase Functions SDK v2 (2nd gen) с модулен ES синтаксис. Примерите включват обработка на събитието за създаване на потребител, генериране на миниатюра при качване на изображение и проста HTTPS крайна точка за REST API. Всички функции са асинхронни с връщане на Promise за коректно завършване на контейнера.

Преди стартиране се уверете, че Firebase CLI е обновен до версия 13+: npm install -g firebase-tools. Функциите v2 изискват тарифен план Blaze. Инициализация: firebase init functions с избор на TypeScript.

Обработка на регистрацията на потребителя

Първият пример — създаване на документ във Firestore при регистрация на нов потребител. Функцията се задейства от събитието auth.user().onCreate и записва основен профил в колекцията users/{uid}. Това позволява да се гарантира, че за всеки регистриран потребител съществува документ с необходимите полета.

import * as functions from "firebase-functions"
import * as admin from "firebase-admin"

admin.initializeApp()

export const createUserProfile = functions.auth
    .user()
    .onCreate(async (user) => {
        const profile = {
            email: user.email,
            displayName: user.displayName ?? "User",
            createdAt: admin.firestore.Timestamp.now(),
            role: "free",
            avatarUrl: null,
        }

        await admin.firestore()
            .collection("users")
            .doc(user.uid)
            .set(profile)

        console.log(`Profile created for ${user.uid}`)
    })

Функцията createUserProfile е асинхронна — връща Promise, който Firebase очаква преди завършване. Ако записът във Firestore приключи с грешка (например поради липса на права), функцията ще бъде автоматично повторена (ако retry е включен). Полето role със стойност "free" позволява реализиране на ограниченията на безплатния тарифен план директно в Security Rules на Firestore, като сравнява resource.data.role с необходимото ниво на достъп.

Генериране на миниатюра при качване на изображение

Вторият пример — Storage тригер за автоматично генериране на миниатюра (thumbnail) след качване на изображение. Функцията създава намалено копие с размер 200x200 пиксела и го запазва по пътя на изходния файл с префикс thumb_. За обработка на изображения се използва библиотеката sharp, която поддържа всички разпространени формати и работи в Node.js среда без системни зависимости.

import * as path from "path"
import * as os from "os"
import * as sharp from "sharp"

export const generateThumbnail = functions.storage
    .object()
    .onFinalize(async (object) => {
        if (!object.contentType?.startsWith("image/")) return

        const filePath = object.name!
        const thumbPath = filePath.replace(
            /(\.\w+)$/, "_thumb$1"
        )

        const bucket = admin.storage().bucket()
        const tempDir = os.tmpdir()
        const tempFile = path.join(tempDir, path.basename(filePath))

        await bucket.file(filePath).download({ destination: tempFile })
        await sharp(tempFile)
            .resize(200, 200, { fit: "cover" })
            .toFile(tempFile.replace(/(\.\w+)$/, "_thumb$1"))

        await bucket.upload(tempFile.replace(
            /(\.\w+)$/, "_thumb$1"
        ), { destination: thumbPath })
    })

Функцията generateThumbnail проверява Content-Type на обекта и игнорира не-изображения, което спестява ресурси. За работа със sharp зависимостта трябва да бъде добавена в package.json. Миниатюрата се създава с параметъра fit: "cover", който изрязва изображението в центъра до квадрат 200x200 пиксела. След създаването миниатюрата се качва обратно в същия bucket с променено име.

HTTPS крайна точка за публично API

Третият пример — HTTPS функция, която реализира REST API крайна точка за проверка на статуса на сървъра. Функцията приема GET заявка и връща JSON с информация за състоянието на услугите на Firebase, свързани с проекта. Крайната точка е полезна за мониторинг и за външни системи, които трябва да проверят достъпността на бекенда преди изпращане на данни.

import * as express from "express"

const app = express.Router()

app.get("/status", async (req, res) => {
    try {
        const db = admin.firestore()
        await db.collection("_health").doc("check").get()
        res.json({ status: "ok", timestamp: Date.now() })
    } catch (error) {
        res.status(503).json({ status: "error", message: error })
    }
})

export const api = functions.https.onRequest(app)

Функцията api използва express Router за маршрутизация, което е удобно при създаването на няколко крайни точки в една функция. Health check се записва във Firestore в колекцията _health, което позволява едновременно да се провери достъпността на Firestore. За production се препоръчва добавяне на удостоверяване на заявката чрез API ключ или Firebase Auth токен, за да се предотврати злоупотребата с публичната крайна точка.

Типични сценарии за използване в мобилните приложения

Cloud Functions най-често се използва за задачи, които са невъзможни или нежелателни за изпълнение на клиента: изпращане на push известия, генериране на прегледи на качени изображения, интеграция с външни платежни системи, модерация на съдържание, синхронизация на данни между Firebase и услуги на трети страни. Моделът без сървър прави тези задачи икономични: такса се начислява само за реалното време на изпълнение на кода.

Интеграцията с платежните системи е типичен сценарий за приложения с in-app покупки. Cloud Functions получава webhook от платежния доставчик (Stripe, PayPal), проверява подписа на заявката, обновява статуса на абонамента във Firestore и изпраща потвърждение на потребителя. Целият код се изпълнява на сървъра без риск от подмяна на данни на клиента. Според Stripe documentation (2026), обработката на webhook отнема по-малко от 500 ms.

Интелигентната модерация на съдържание използва Storage тригера за автоматична проверка на качени изображения чрез Google Cloud Vision API. Функцията изпраща изображението в Vision API за откриване на небезопасно съдържание (насилие, съдържание за възрастни) и ако прагът бъде надхвърлен, изтрива файла и уведомява администратора. Този сценарий е критичен за UGC приложения с потребителски галерии.

Агрегацията на данни — Cloud Functions като заместител на броячите на Firebase Realtime Database. Вместо четене и запис на брояча на клиента (което води до race conditions), използвайте Firestore тригера onWrite за атомарно обновяване на агрегирани полета. Например функцията изчислява броя на харесванията на публикацията при всяко добавяне или изтриване на документ в подколекцията /posts/{postId}/likes/{userId} и обновява полето likesCount в родителския документ.