firebase-data-connect

用途

本技能为在 Angular 应用中集成 Firebase Data Connect 提供专家级指导，帮助开发者使用由 PostgreSQL 支撑的类型安全 GraphQL 操作。当需要为 Firebase Data Connect 定义 GraphQL schema、创建数据操作的查询与变更、将 Data Connect 集成到 Angular 服务、生成类型安全的 TypeScript SDK、实现实时数据订阅、配置 Data Connect 连接器与服务、从 Firestore 迁移到 Data Connect，或优化 GraphQL 查询性能时，可启用本技能。

什么是 Firebase Data Connect

Firebase Data Connect 是一项关系型数据库服务，提供：面向类型安全数据访问的 GraphQL API、PostgreSQL 关系型数据后端、为 TypeScript/JavaScript 生成的 SDK、实时数据订阅、服务端校验与安全规则，以及用于开发和测试的本地模拟器。

前置条件

所需工具包括：Firebase CLI（npm install -g firebase-tools）、Node.js 18+ 与 npm/pnpm、Angular 20+ 项目，以及已启用 Data Connect 的 Firebase 项目。

安装命令：

# Install Firebase CLI
npm install -g firebase-tools

# Login to Firebase
firebase login

# Initialize Data Connect in your project
firebase init dataconnect

# Install Angular Fire (if not already installed)
npm install @angular/fire

项目结构

dataconnect/
├── dataconnect.yaml          # Connector configuration
├── schema/
│   ├── schema.gql            # GraphQL schema definitions
│   └── types.gql             # Custom types and enums
├── queries/
│   ├── users.gql             # User queries
│   └── workspace.gql         # Workspace queries
├── mutations/
│   ├── createUser.gql        # User mutations
│   └── updateWorkspace.gql   # Workspace mutations
└── seed_data.gql             # Development seed data

src/dataconnect-generated/    # Generated TypeScript SDK
└── index.ts                  # Auto-generated type-safe operations

主要能力

Schema 定义

在 dataconnect/schema/schema.gql 中定义类型与关系。示例包含 User、Workspace、WorkspaceMember 三个类型，使用 @table 标注表，@default(expr: "uuidV4()") 生成 UUID，@default(expr: "request.time") 生成时间戳，@unique 设置唯一约束，@relation 与 @relationFrom 定义关系，并支持复合唯一约束 @unique(fields: ["userId", "workspaceId"]) 以及枚举 MemberRole（OWNER、ADMIN、MEMBER、VIEWER）。

查询

在 dataconnect/queries/ 下定义查询，使用 @auth(level: USER) 声明认证级别。示例包括 GetUser、ListUserWorkspaces、SearchWorkspaces，支持 where 条件（如 contains）、orderBy（如 createdAt: DESC）与 limit。

变更

在 dataconnect/mutations/ 下定义变更，示例包括 CreateWorkspace、AddWorkspaceMember、UpdateWorkspace，使用 workspace_insert、workspaceMember_insert、workspace_update 等操作。

Angular 集成

通过 @angular/fire/data-connect 的 getDataConnect 获取连接，并从 @/dataconnect-generated 导入生成的 getUser、listUserWorkspaces、createWorkspace、addWorkspaceMember 等函数，在服务中执行查询与变更。

仓储模式

示例展示 WorkspaceDataConnectRepository 实现 IWorkspaceRepository，使用 RxJS 的 from 与 map 将 Data Connect 响应映射为领域实体。

NgRx Signals 集成

示例展示使用 signalStore、withState、withMethods、rxMethod、tapResponse 构建 WorkspaceStore，管理 workspaces、selectedWorkspace、loading、error 状态，并实现 loadUserWorkspaces 与 createWorkspace 方法。

配置

dataconnect.yaml 示例包含 connectorId、cloudSql（instanceId、database）、schema（source、datasource.postgresql）、queries.source、mutations.source。Angular Fire 配置在 app.config.ts 中通过 provideFirebaseApp、provideDataConnect 提供，getDataConnect 指定 connector 与 location。

本地开发

启动模拟器：

# Start Data Connect emulator
firebase emulators:start --only dataconnect

# Run with seed data
firebase emulators:start --only dataconnect --import=./seed-data

# Generate TypeScript SDK
firebase dataconnect:sdk:generate --output=src/dataconnect-generated

种子数据在 dataconnect/seed_data.gql 中通过 user_insert、workspace_insert 等变更定义。

最佳实践

Schema 设计应使用正确的关系（如 authorId 配合 @relation），避免重复数据（如直接存 authorEmail、authorName）。查询优化应只请求所需字段，避免过度获取。错误处理应检查 result.errors 并抛出异常，而非忽略错误。

安全

认证规则使用 @auth(level: USER)，可结合表达式（如 expr: "auth.uid == resource.ownerId"）限制特定角色。输入校验使用 @unique、@check(expr: "length(this) >= 3")、@check(expr: "this >= 18") 等约束。

故障排查

常见问题包括：SDK 生成失败（schema 语法错误，运行 firebase dataconnect:validate）、查询返回 null（缺少 @auth 指令）、关系错误（字段引用不正确，检查 @relation 字段与列名匹配）、模拟器无法启动（端口被占用，修改 firebase.json 端口或结束进程）、类型不匹配（生成代码过期，重新运行 firebase dataconnect:sdk:generate）。

从 Firestore 迁移

示例对比：Firestore 使用 doc、getDoc、docSnap.data()；Data Connect 使用 getWorkspace(dataConnect, { id }) 并读取 result.data.workspace。

适用场景与限制

适用于使用 Angular 20+ 与 Firebase Data Connect、需要类型安全 GraphQL 访问 PostgreSQL 的项目。资料未提供具体收费、价格、平台限制或性能指标等信息。