Как использовать Firebase Firestore с Angular — полное руководство по CRUD

Введение

Firebase — это набор облачных сервисов от Google, который упрощает хранение данных, хостинг, аутентификацию и анализ. Одним из наиболее популярных сервисов Firebase является Firestore — документо-ориентированная облачная база данных, удобная для масштабируемых приложений.

В этом руководстве вы найдете пошаговую инструкцию:

• Как создать базу данных Firestore и добавить туда тестовые данные.
• Как подключить Firestore к локальному приложению Angular.
• Примеры сервисов Angular для операций CRUD (Create, Read, Update, Delete).
• Как выполнять запросы/фильтрацию, сортировку и пагинацию.
• Практические советы по безопасности, отладке и развертыванию.

Важно: в примерах используется коллекция “User” с полями firstName, lastName и vipMember (boolean).

Содержание

• Предварительные требования
• Создание проекта и базы Firestore
• Подключение Firebase к Angular
• Сервис для доступа к Firestore (полный пример)
• CRUD: создание, чтение, обновление, удаление
• Запросы, фильтры, сортировка и пагинация
• Безопасность, правила и отладка
• Рекомендации по архитектуре и альтернативы
• Чек-листы по ролям и Критерии приёмки
• SOP/Playbook: быстрый рабочий сценарий
• Частые ошибки и их решения
• Итог

Предварительные требования

• Установлен Node.js и npm.
• Локальное приложение Angular (Angular CLI).
• Аккаунт Google для доступа в Firebase.
• Базовые знания TypeScript и Angular (компоненты, сервисы, модули).

Краткая терминология

• Firestore — документно-ориентированная база данных Firebase.
• Коллекция (Collection) — набор документов, аналог таблицы.
• Документ (Document) — один JSON-подобный объект данных.
• AngularFire — официальная библиотека интеграции Firebase с Angular.

Как создать проект Firebase и базу данных Firestore

1. Перейдите на главную страницу Firebase и нажмите Перейти в консоль.
2. В разделе “Ваши проекты” выберите Добавить проект.
3. Следуйте подсказкам мастера создания проекта.

4. После создания проекта в левой панели найдите Firestore Database и откройте его.

5. Нажмите Создать базу данных и при выборе правил безопасности выберите Начать в тестовом режиме (для разработки). В продакшене обязательно уточните и ужесточите правила.

6. Создайте коллекцию: нажмите Начать коллекцию, введите ID коллекции “User” и добавьте первый документ с полями firstName (string), lastName (string), vipMember (boolean). Документ можно создать с автоматически сгенерированным ID.

7. Добавьте несколько документов (Add document) для тестовых данных — это поможет при разработке и тестировании.

Примечание: режим тестирования открывает доступ ко всем данным; не используйте его в продакшене.

Как подключить Firebase к локальному приложению Angular

1. В консоли Firebase откройте “Обзор проекта” и зарегистрируйте веб-приложение (кнопка с угловыми скобками).

2. Установите SDK Firebase в проект Angular:

npm i firebase

3. Сохраните конфигурацию Firebase, которую покажет панель, и поместите её в environment.ts и environment.prod.ts:

export const environment = {
  production: true,
  firebaseConfig: {
    apiKey: "your-api-key",
    authDomain: "your-auth-domain",
    projectId: "your-project-id",
    storageBucket: "your-storage-buckey",
    messagingSenderId: "your-messaging-sender-id",
    appId: "your-api-id",
    measurementId: "your-measurement-id"
  }
};

4. Установите AngularFire (официальный пакет для Angular):

npm i @angular/fire

Примечание: в исходном материале упомянута несовместимость AngularFirestore с Angular 9+, поэтому перед установкой проверьте совместимость версии @angular/fire с вашей версией Angular в официальной документации.

5. В app.module.ts добавьте импорты и инициализацию:

import { AngularFireModule } from "@angular/fire";
import { AngularFirestoreModule } from "@angular/fire/firestore";
import { environment } from "../environments/environment";

@NgModule({
  imports: [
    AngularFireModule.initializeApp(environment.firebaseConfig),
    AngularFirestoreModule,
    // ... другие модули
  ],
})
export class AppModule {}

Важно: храните конфигурационные файлы в environment и ни в коем случае не выкладывайте приватные ключи в публичные репозитории.

Рекомендуемая структура сервиса доступа к Firestore

Хорошая практика — вынести всю работу с Firestore в сервис(ы). Это повышает повторное использование и тестируемость.

Создайте файл src/app/services/firestore.service.ts и разместите в нём все функции работы с коллекцией User.

Полный пример сервиса (с комментариями):

import { Injectable } from '@angular/core';
import { AngularFirestore } from '@angular/fire/firestore';
import { Observable } from 'rxjs';

export interface User {
  id?: string;
  firstName: string;
  lastName: string;
  vipMember: boolean;
}

@Injectable({
  providedIn: 'root'
})
export class FirestoreService {
  constructor(private db: AngularFirestore) {}

  // Получить всех пользователей (возвращает Promise, который резолвится массивом)
  getAllUsers(): Promise {
    return new Promise((resolve) => {
      this.db.collection('User').valueChanges({ idField: 'id' }).subscribe(users => resolve(users));
    });
  }

  // Добавить нового пользователя с заданным ID
  addNewUser(_newId: any, _fName: string, _lName: string, _vip: boolean) {
    return this.db.collection('User').doc(_newId).set({ firstName: _fName, lastName: _lName, vipMember: _vip });
  }

  // Обновить имя пользователя
  updateUserFirstName(_id: any, _firstName: string) {
    return this.db.doc(`User/${_id}`).update({ firstName: _firstName });
  }

  // Обновить полное имя
  updateUserFullName(_id: any, _firstName: string, _lastName: string) {
    return this.db.doc(`User/${_id}`).update({ firstName: _firstName, lastName: _lastName });
  }

  // Удалить пользователя
  deleteUser(_id: any) {
    return this.db.doc(`User/${_id}`).delete();
  }

  // Запрос VIP пользователей
  getAllVipMembers(): Promise {
    return new Promise((resolve) => {
      this.db.collection('User', ref => ref.where('vipMember', '==', true)).valueChanges().subscribe(users => resolve(users));
    });
  }

  // Запрос VIP пользователей, отсортированных по фамилии и с лимитом
  getVipMembersPaged(limit: number = 3): Promise {
    return new Promise((resolve) => {
      this.db.collection('User', ref => ref.where('vipMember', '==', true).orderBy('lastName').limit(limit)).valueChanges({ idField: 'id' }).subscribe(users => resolve(users));
    });
  }
}

Ключевая мысль: сервис возвращает данные в виде Promise или Observable — выбирайте подходящий стиль в зависимости от архитектуры приложения.

Как использовать сервис в компоненте Angular

Импортируйте сервис в компонент и вызовите методы в ngOnInit или по событию:

import { Component, OnInit } from '@angular/core';
import { FirestoreService, User } from 'src/app/services/firestore.service';

@Component({/* ... */})
export class UsersComponent implements OnInit {
  allUsers: User[] = [];
  vipUsers: User[] = [];

  constructor(private firestore: FirestoreService) {}

  async ngOnInit() {
    this.allUsers = await this.firestore.getAllUsers();
    console.log('All users', this.allUsers);

    this.vipUsers = await this.firestore.getAllVipMembers();
    console.log('VIP users', this.vipUsers);
  }

  addUser() {
    this.firestore.addNewUser('62289836', 'Jane', 'Doe', true).then(() => console.log('User added'));
  }

  updateUser() {
    this.firestore.updateUserFirstName('vLBnSegFl1pD7XQ42TBv', 'Kay');
  }

  deleteUser() {
    this.firestore.deleteUser('vLBnSegFl1pD7XQ42TBv');
  }
}

Примечание: для генерации случайного ID можно использовать метод doc().id или библиотеку для генерации UUID.

Запросы, сортировка, пагинация и индексы

Firestore поддерживает фильтрацию через where(), сортировку orderBy(), а также startAt(), startAfter() и limit().

Примеры:

• Фильтрация по полю:

this.db.collection('User', ref => ref.where('vipMember', '==', true))

• Сортировка по фамилии (может потребоваться создать индекс):

this.db.collection('User', ref => ref.where('vipMember', '==', true).orderBy('lastName'))

• Пагинация: используйте startAfter(lastDoc) и limit(pageSize) или курсоры, чтобы реализовать постраничную загрузку.

Важно: если Firestore требует индекс для сложных запросов, в консоли будет ссылка для его создания. Создавайте индексы в консоли Firebase по мере необходимости.

Безопасность и правила доступа

Firestore использует набор правил безопасности (security rules), которые определяют, кто и какие операции может выполнять.

Пример упрощённых правил (только для разработки):

rules_version = '2';
service cloud.firestore {
  match /databases/{database}/documents {
    match /{document=**} {
      allow read, write: if true; // ОТКРЫТО для всех — опасно в продакшене
    }
  }
}

Рекомендации по безопасности:

• Для производства используйте аутентификацию (Firebase Auth) и проверяйте uid в правилах.
• Ограничивайте доступ по полям и операциям (read/write).
• Минимизируйте раскрытие чувствительных данных.
• Тестируйте правила с Firebase Emulator Suite.

Пример правил с авторизацией:

match /User/{userId} {
  allow read: if request.auth != null; // любые авторизованные пользователи могут читать
  allow write: if request.auth != null && request.auth.uid == userId; // только владелец может писать
}

Отладка и распространённые ошибки

• “Permission denied” — проверьте правила безопасности и аутентификацию.
• “Missing or insufficient permissions” — убедитесь, что запрос соответствует правилам, и что пользователь аутентифицирован.
• “Requires index” — следуйте ссылке в консоли и создайте индекс.
• Несовместимость версий Angular и AngularFire — сверяйтесь с документацией пакета.
• Проблемы с CORS — неверная конфигурация хостинга или запросы с внешних доменов.

Совет: используйте Firebase Emulator Suite для локального тестирования правил и функций без воздействия на продакшн.

Когда Firestore не лучший выбор (контрпримеры)

• Сильно-реляционные данные с множеством JOIN’ов — Firestore не поддерживает JOIN, поэтому сложные реляционные сценарии потребуют денормализации или другой БД.
• Сложные транзакционные операции на большом количестве документов — транзакции возможны, но могут быть ограничены по масштабу.
• Если нужна SQL-совместимость для аналитики — рассмотрите BigQuery или PostgreSQL.

Альтернативы Firestore:

• Realtime Database (Firebase) — простая, но менее гибкая с правилами;
• Supabase/Postgres — если вы хотите SQL и расширяемость;
• MongoDB Atlas — документная база с более гибкими возможностями запросов;
• Hasura (GraphQL поверх Postgres) — если нужен GraphQL/SQL стек.

Роль‑ориентированные чек-листы

Developer:

• Зарегистрировать Firebase проект.
• Добавить тестовую коллекцию и документы.
• Добавить environment.*.ts конфигурации.
• Установить firebase и @angular/fire.
• Реализовать сервисы CRUD и покрыть тестами.

DevOps / Release:

• Проверить правила безопасности и настройку аутентификации.
• Настроить CI/CD так, чтобы не пушить секреты в репозиторий.
• Настроить резервное копирование/экспорт данных.

QA:

• Проверить поведение при нехватке прав (Permission denied).
• Тестировать пагинацию и сортировку.
• Проверить отказоустойчивость при недоступном Firebase.

Security:

• Автоматическое сканирование на утечку ключей.
• Ревью правил безопасности.
• Механизм ротации ключей и ролей.

SOP / Playbook: быстрое подключение Angular → Firebase

1. Создать проект в Firebase и Firestore в режиме тестирования.
2. Создать коллекцию User и добавить пару тестовых документов.
3. Зарегистрировать веб‑приложение и сохранить firebaseConfig.
4. В проекте Angular: npm i firebase @angular/fire.
5. Добавить AngularFireModule.initializeApp(environment.firebaseConfig) и AngularFirestoreModule в AppModule.
6. Создать сервис FirestoreService с методами CRUD.
7. Реализовать компоненты, использующие сервис.
8. Перенастроить правила безопасности перед деплоем и протестировать через Emulator.

Критерии приёмки

• Приложение успешно подключается к Firestore из локальной среды.
• Удачно выполняются операции: создать, прочитать (со списком и по ID), обновить, удалить.
• Пагинация и сортировка работают корректно.
• Время ответа для операций чтения не превышает приемлемых лимитов для UX (проверяется вручную или автотестами).
• Правила безопасности не допускают неавторизованных записей (проверяется тестами правил).

Тестовые случаи и критерии проверки

• Добавление нового пользователя с валидными полями → документ присутствует в Firebase.
• Обновление существующего поля → значение обновлено, другие поля не повреждены.
• Удаление документа → документ удалён и отсутствует в выборке.
• Фильтрация vipMember == true → возвращаются только VIP записи.
• Попытка записи без авторизации → операция отклонена (если правила требуют авторизацию).

Совместимость и миграция

• Всегда проверяйте совместимость @angular/fire с вашей версией Angular.
• При миграции между версиями @angular/fire читайте release notes: API могли измениться (например, примеры инициализации или именование пакетов).
• Для миграции данных можно использовать экспорт/импорт данных из консоли Firebase или инструменты резервного копирования.

Безопасность данных и GDPR (заметки)

• Если приложение обрабатывает персональные данные EU‑граждан, убедитесь, что хранение и обработка соответствуют GDPR: документируйте основания обработки, имейте механизм удаления по запросу, защищайте доступ.
• Минимизируйте хранение лишних персональных данных и используйте шифрование на уровне транспорта (HTTPS) и, при необходимости, дополнительное шифрование полей на клиенте.

Частые ошибки и решения

• Ошибка: “Firebase: No project ID” — проверьте firebaseConfig и правильность экспорта environment.
• Ошибка: “Invalid firebaseConfig” — перепроверьте копирование конфигурации из консоли.
• Проблемы аутентификации → проверьте Firebase Auth и правила Firestore.
• “Requires index” при комбинированных запросах → создайте индекс по подсказке в консоли.

Ментальные модели и эвристики выбора

• Ментальная модель Firestore: думайте в терминах коллекций (таблицы) и документов (строки), но без JOIN — проектируйте данные с возможной денормализацией.
• Эвристика масштабирования: если часто нужно аггрегировать большое количество документов, выносите агрегаты или используйте дополнительные сервисы аналитики.

Короткое руководство по мониторингу и бэкапам

• Используйте Firebase Console для мониторинга трафика и ошибок.
• Настройте регулярный экспорт данных (Managed export) или собственный скрипт экспорта в хранилище.
• Для сложных сценариев интегрируйте экспорт в BigQuery для аналитики.

Превью для социальных сетей

OG заголовок: Firebase + Angular — CRUD с Firestore OG описание: Быстрое руководство по созданию Firestore, подключению к Angular и реализации CRUD с примерами и чек-листами.

Итог

Это руководство даёт практическую основу для начала работы с Firebase Firestore в приложениях Angular: от создания проекта до реализации CRUD-операций и продакшн-советов по безопасности. Начните с тестовой базы, реализуйте сервисы и постепенно ужесточайте правила безопасности перед деплоем.

Ключевые действия:

• Создайте проект и коллекцию User в Firestore.
• Подключите firebase и @angular/fire к приложению.
• Вынесите логику доступа в сервис и используйте методы CRUD.
• Настройте правила безопасности и тестируйте через Emulator.

Важно: всегда проверяйте официальную документацию Firebase и AngularFire для актуальной информации по версиям и API.