SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场moai-platform-firestore

moai-platform-firestore

数据与分析

查看项目

更新于 10-16 10:59

技能介绍

用途

moai-platform-firestore 是一个 Firebase Firestore 专项技能（Specialist），聚焦 NoSQL 文档数据库的模式、实时同步、离线缓存与 Security Rules。适用场景包括：离线优先的移动应用、实时协作功能、跨 iOS / Android / Web / Flutter 的跨平台应用、需要 Google Cloud 集成的项目，以及数据结构灵活演进的应用。

主要能力

  • 实时同步：在所有已连接客户端之间自动同步。
  • 离线缓存：使用 IndexedDB 持久化，在线后自动同步。
  • 安全规则：提供声明式的字段级访问控制。
  • Cloud Functions：支持文档触发器，用于服务端处理。
  • 复合索引：支持复杂查询优化。

使用方式

该技能按模块组织，提供深度实现指引：

  • 安全规则模块（modules/security-rules.md）：基础规则结构与语法、基于角色的访问控制模式、自定义 claims 集成、字段级验证、规则测试与调试。
  • 离线与缓存模块（modules/offline-cache.md）：持久缓存配置、多标签页管理器设置、缓存大小优化、同步状态处理、网络状态管理。
  • 实时监听器模块（modules/realtime-listeners.md）：快照监听器模式、待写入元数据处理、查询订阅优化、监听器生命周期管理、错误处理策略。
  • 事务模块（modules/transactions.md）：原子批量操作、事务模式与约束、分布式计数器实现、冲突解决策略、性能考量。

Context7 文档访问

第 1 步：使用 mcp__context7__resolve-library-id，将 libraryName 设为 "firebase"，获取兼容 Context7 的库 ID。

第 2 步：使用 mcp__context7__get-library-docs 及解析得到的 ID 获取 Firestore 文档。将 topic 设为具体领域，例如 "firestore security-rules"、"firestore offline" 或 "firestore real-time"。分配 6000 到 8000 token 以获得全面覆盖。

实现指南（示例片段）

带离线持久化的 Firestore 初始化：从 firebase/app 导入 initializeApp，从 firebase/firestore 导入 initializeFirestore、persistentLocalCache、persistentMultipleTabManager 和 CACHE_SIZE_UNLIMITED。使用 initializeApp 传入包含 apiKey、authDomain、projectId（来自环境变量）的 config 对象创建 app。导出 db 实例，由 initializeFirestore 创建，传入 app 以及使用 persistentLocalCache 的 localCache 配置，tabManager 设为 persistentMultipleTabManager()，cacheSizeBytes 设为 CACHE_SIZE_UNLIMITED。

基础 Security Rules 结构：使用 rules_version 2 和 service cloud.firestore 定义规则。在 databases match 块中，创建 users 集合 match 及 userId 通配符，若 request.auth.uid 等于 userId 则允许读写。创建 documents 集合 match 及 docId 通配符。若文档 isPublic 字段为 true，或 request.auth.uid 等于 ownerId 字段，或 request.auth.uid 在 collaborators 数组中，则允许读取。若 request.auth 不为 null 且新文档 ownerId 等于 request.auth.uid，则允许创建。若 request.auth.uid 等于文档 ownerId，则允许更新与删除。

带元数据的实时监听器：从 firebase/firestore 导入 collection、query、where、orderBy、onSnapshot。创建 subscribeToDocuments 函数，接收 userId 和 callback。在 documents 集合上构建查询，筛选 collaborators array-contains userId，并按 createdAt 降序排列。调用 onSnapshot，传入查询、includeMetadataChanges 设为 true，以及回调，将 snapshot.docs 映射为包含 id、展开的文档数据、_pending 设为 doc.metadata.hasPendingWrites、_fromCache 设为 doc.metadata.fromCache 的对象。返回取消订阅函数。

复合索引配置：在 firestore.indexes.json 中定义索引，包含 indexes 数组。每个索引对象指定 collectionGroup、queryScope 为 COLLECTION、以及 fields 数组。字段指定 fieldPath 和 order（ASCENDING 或 DESCENDING），或对数组字段使用 arrayConfig 为 CONTAINS。为常见查询模式创建索引，例如 organizationId 配 createdAt 降序，或 tags 数组配 createdAt 降序。

性能与定价

性能特征：读取延迟 50 到 200 毫秒（依区域而定）；写入延迟 100 到 300 毫秒；实时传播 100 到 500 毫秒；离线同步在重连时自动进行。

免费额度（2024）：存储 1GB；每日读取 50,000；每日写入 20,000；每日删除 20,000。

配合使用

  • moai-platform-firebase-auth：Firebase Authentication 集成
  • moai-lang-flutter：Flutter SDK 模式
  • moai-lang-typescript：TypeScript 客户端模式
  • moai-domain-mobile：移动架构模式
  • moai-quality-security：Security Rules 最佳实践

其他资源

  • reference.md：扩展文档与最佳实践
  • examples.md：完整可运行代码示例
  • modules/security-rules.md：Security Rules 深入讲解
  • modules/offline-cache.md：离线持久化模式
  • modules/realtime-listeners.md：实时订阅模式
  • modules/transactions.md：批量与事务操作

状态：Production Ready。生成工具：MoAI-ADK Skill Factory v2.0。最后更新：2026-01-11。平台：Firebase Firestore。