在 Visual Studio Code 中开发 GraphQL 应用程序

了解如何使用 React、Apollo 客户端和 TypeScript 生成与 Microsoft Fabric 中托管的 GraphQL API 集成的前端应用程序。本教程介绍如何设置本地开发工具，包括自动完成、代码生成和 IntelliSense，以获得最佳的开发人员体验。

谁应使用 VS Code 开发工具

使用 VS Code 进行本地开发是为了：

React 开发人员 构建通过 GraphQL 使用 Fabric Lakehouse 和数据仓库数据的 Web 应用程序
需要为 Fabric GraphQL API 生成类型安全的客户端代码的 TypeScript 开发人员
全堆栈开发人员在支持本地 IDE 的 Fabric 平台上构建自定义分析应用程序。
希望为Fabric数据访问应用程序使用具有IntelliSense和调试功能的新式工具的开发团队

使用 TypeScript 和 Apollo 客户端生成需要丰富的 IDE 支持、代码生成和本地调试功能的 React 应用程序时，请使用此方法。

先决条件

在开始之前，请确保具备：

Microsoft Fabric 工作区访问权限：成为 Fabric 工作区的成员，并至少具有 参与者 角色（或更高角色：管理员、成员），以便创建和修改 GraphQL API 项目。
数据源权限：计划通过 GraphQL API 公开的数据源的读取/写入权限
Node.js 安装在开发计算机上（包括 npm）
在您的开发计算机上安装了Visual Studio Code
React、TypeScript 和 GraphQL 概念的基础知识

步骤 1：在 Microsoft Fabric 中创建 GraphQL API

注释

本指南演示如何从 SQL 数据库上下文创建 GraphQL API。首先创建 SQL 数据库，然后直接从该数据库中创建 GraphQL API。如果已有现有的 GraphQL API 并想要连接到它，请按照 “入门”指南作，先创建 API，然后再连接到 SQL 数据库或其他数据源。

创建 SQL 数据库

创建包含 GraphQL API 示例数据的 SQL 数据库：

在 Fabric 工作区中，选择“ 新建项”。
选择 SQL 数据库（预览版）。
为数据库提供名称。
选择 示例数据 以自动创建表，并使用示例数据填充这些表。这会使用 SalesLT 架构创建 AdventureWorksLT 示例数据库，包括 SalesLT.Customer、SalesLT.Product 和 SalesLT.SalesOrderHeader 等表。

小窍门

如果已有一个包含上一教程或 GraphQL API 创建示例数据的 SQL 数据库，则可以重复使用同一数据库。单个数据库可以支持多个 GraphQL API，因此，如果已有具有 SalesLT 架构的数据库，则无需创建新数据库。

创建 GraphQL API

现在已有包含示例数据的 SQL 数据库，请创建 GraphQL API：

在 SQL 数据库中，从功能区中选择 GraphQL 的新 API 。
提供 API 的名称。
从数据库选择所有 SalesLT 表。
选择 “加载 ”以生成 API。

GraphQL API 现已准备就绪，可在 Fabric 工作区中使用。

步骤 2：设置开发环境

若要继续学习本教程，请完成以下步骤以设置 React 初学者应用程序、安装必要的依赖项，以及配置 Visual Studio Code 和 GraphQL 支持。

克隆入门应用程序 - 从 Microsoft Fabric 示例库获取 React 入门应用程序：

git clone https://github.com/microsoft/fabric-samples.git
cd fabric-samples/docs-samples/data-engineering/GraphQL/React-Apollo-TS

安装依赖项 - 安装 GraphQL 开发、自动完成和代码生成所需的包：
```
npm install
```
安装所需的 Visual Studio Code 扩展 - 在 Visual Studio Code 中安装 GraphQL：语言功能支持扩展，以启用 GraphQL 操作的语法突出显示、验证和 IntelliSense。

步骤 3：配置 GraphQL 架构

GraphQL 架构定义 API 的结构 - 可用的数据、可执行的作以及不同数据类型之间的关系。开发工具使用此模式提供 IntelliSense、代码补全和类型生成功能，使编写正确的 GraphQL 查询和变更变得更加容易。

可以通过两种方式获取 GraphQL 架构：

选项 1：将架构导出为静态文件

在 Fabric GraphQL API 中，从功能区中选择“ 导出架构 ”。
下载的文件名包括 GraphQL API 的 ID（例如）。 GraphQL_your-api-id_schema.graphql 将其保存到项目根目录并将其重命名为 schema.graphql - 这是在后续配置步骤中使用的文件名。

选项 2：使用远程终结点

访问在 Fabric 门户中创建的 GraphQL API。
通过 Get-PowerBIAccessToken 使用 PowerShell 获取授权令牌

注释

虽然远程终结点选项始终提供最新的架构，但获得的令牌是临时的，并且每小时失效。它们应仅用于测试和开发目的，只要可能使用静态文件来避免令牌过期问题。

步骤 4：配置 IntelliSense 和自动完成

现在，你将使用步骤 3 中的架构设置 IntelliSense。架构文件（无论是静态还是来自远程终结点）使 VS Code 能够在编写 GraphQL 查询时提供实时代码建议、错误检测和字段验证。

在项目根目录中创建配置文件：

使用静态架构文件

如果将架构导出为静态文件，请使用以下配置：

创建 .graphqlrc.yml：

schema: './schema.graphql'
documents: 'src/**/*.{ts,tsx,graphql,gql}'

使用远程终结点

如果想要直接从 GraphQL API 终结点提取架构，请使用以下配置：

创建 graphql.config.yml：

schema:
  - https://your-graphql-endpoint.com/graphql:
      headers:
        Authorization: Bearer YOUR_ACCESS_TOKEN
documents: src/**/*.{ts,tsx,graphql,gql}

配置选项

schema：指定 GraphQL 架构的位置
documents：定义哪些文件应具有 IntelliSense 支持

创建配置文件后，重启 Visual Studio Code 以确保更改生效。

步骤 5：设置代码生成

GraphQL 代码生成会自动从您的架构和操作中创建强类型的 TypeScript 接口和 React 钩子，从而减少错误并提高开发效率。其主要目的是增强 GraphQL 项目中的类型安全性并简化开发，尤其是在使用 TypeScript 等强类型语言时。

创建代码生成配置

静态文件选项

如果将架构导出为静态文件，请在项目根目录中创建 codegen.yml ：

schema: './schema.graphql'
documents: './src/**/*.graphql'
generates:
  src/generated/graphql.tsx:
    plugins:
      - typescript
      - typescript-operations
      - typescript-react-apollo
    config:
      withHooks: true

远程终结点选项

如果使用远程终结点方法，请在项目根目录中创建 codegen.yml ：

schema:
  - https://your-graphql-endpoint.com/graphql:
      headers:
        Authorization: Bearer YOUR_ACCESS_TOKEN
documents: 'src/**/*.{ts,tsx,graphql,gql}'
generates:
  src/generated/graphql.tsx:
    plugins:
      - typescript
      - typescript-operations
      - typescript-react-apollo
    config:
      withHooks: true

配置细目

schema：架构文件或远程终结点的路径
文档：用于查找 GraphQL 操作文件的 Glob 模式
generates：指定生成的代码的输出文件
插件：确定要生成的代码（TypeScript 类型和 React Apollo 挂钩）

添加 codegen 脚本

将代码生成脚本添加到项目目录中的 package.json 文件中（此文件已在您在步骤 2 中克隆存储库时包含）：

{
  "scripts": {
    "codegen": "graphql-codegen --config codegen.yml"
  }
}

步骤 6：编写 GraphQL操作

在.graphql目录中创建src/operations文件以定义查询和突变。 IntelliSense 提供自动完成和验证。

示例查询

创建 src/operations/queries.graphql 并输入以下查询：

下面是用于检索客户数据的示例查询：

query GET_CUSTOMERS(
  $after: String
  $first: Int
  $filter: CustomerFilterInput
  $orderBy: CustomerOrderByInput
) {
  customers(after: $after, first: $first, filter: $filter, orderBy: $orderBy) {
    items {
      CustomerID
      FirstName
      LastName
    }
  }
}

下面是一个示例突变：

mutation ADD_CUSTOMER($input: CreateCustomerInput!) {
  createCustomer(item: $input) {
    CustomerID
    FirstName
    LastName
    Title
    Phone
    PasswordHash
    PasswordSalt
    rowguid
    ModifiedDate
    NameStyle
  }
}

步骤 7：生成类型和钩子

运行代码生成命令以创建 TypeScript 类型和 React 挂钩：

npm run codegen

成功完成后，你已在 src/generated/graphql.tsx 中生成了以下代码：

所有 GraphQL 类型的 TypeScript 接口
各个操作的强类型 React 钩子
输入和输出类型定义

步骤 8：在 React 组件中使用生成的代码

在 React 组件中导入和使用生成的钩子，例如：

import React from 'react';
import { useGetCustomersQuery, useAddCustomerMutation } from '../generated/graphql';

const CustomersComponent: React.FC = () => {
  const { data, loading, error } = useGetCustomersQuery({
    variables: { first: 10 }
  });

  const [addCustomer] = useAddCustomerMutation();

  if (loading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;

  return (
    <div>
      {data?.customers?.items?.map(customer => (
        <div key={customer.CustomerID}>
          {customer.FirstName} {customer.LastName}
        </div>
      ))}
    </div>
  );
};

export default CustomersComponent;

步骤 9：配置身份验证

为应用程序配置Microsoft Entra ID 身份验证：

按照“将应用程序连接到 Fabric API for GraphQL”中的“创建Microsoft Entra 应用”部分创建Microsoft Entra 应用。
使用所需的参数更新authConfig.ts文件在您的项目中。

export const AUTH_CONFIG = {
    clientId: "<Enter_the_Application_Id_Here>",
    tenantId: "<Enter_the_Tenant_Id_Here>",
    clientSecret: "<Enter_the_Client_Secret_Here>", //optional
}
export const GRAPHQL_ENDPOINT = '<Enter_the_GraphQL_Endpoint_Here>';

// The scope required for Fabric GraphQL API access
export const DEFAULT_SCOPE = "https://analysis.windows.net/powerbi/api/.default";

有关完整的配置文件，请参阅存储库中的 authConfig.ts示例。

步骤 10：运行应用程序

启动开发服务器：

npm run dev

您的应用程序将在浏览器中启动，网址为 http://localhost:3000。系统会提示使用Microsoft凭据登录，以访问 GraphQL API 数据。身份验证成功后，你将看到 Fabric SQL 数据库 SalesLT.Customer 表中的客户数据显示在 React 应用程序中。

反馈

此页面是否有帮助？

Last updated on 2026-01-21