企业官网建设流程全解析

• 后端

Altair GraphQL Client 是一款功能丰富的跨平台 GraphQL 客户端 IDE，本指南基于 graphql-dotnet 仓库的官方文档 altair-graphql.md，介绍如何通过GraphQL.Server.Ui.AltairNuGet 包，在 ASP.NET Core 应用中用一行中间件代码挂载 Altair 界面，并详解默认端点、自定义 options 参数以及仓库内可直接运行的完整示例。读完本文，你将掌握 Altair 与 GraphQL.NET 服务的标准集成姿势，并能在本地快速复现一个带可视化 IDE 的 GraphQL 调试环境。

Altair GraphQL Client 是什么

Altair GraphQL Client 是一款功能丰富、界面美观的 GraphQL 客户端 IDE，它允许你在任意平台上与任何你有权访问的 GraphQL 服务器进行交互。官方文档对其定位如下：

• 便于测试与优化GraphQL 实现；
• 内置subscriptions（订阅）支持，可调试实时数据流；
• 提供查询脚手架（query scaffolding）、格式化等开发辅助能力；
• 支持多语言界面与主题切换等个性化配置。

在 graphql-dotnet 仓库中，Altair 也被收录在项目 README 的生态工具清单中（见 README.md），并与 GraphiQL、Voyager、Playground 等一起被列为 GraphQL.Server 支持的多种 UI 选项（见 ASP.NET Core 集成指南 中的 “Multiple UI options (GraphiQL, Playground, Altair, Voyager)” 描述）。

快速集成：NuGet 包 + 一行中间件

将 Altair 接入 ASP.NET Core 应用最简单的方式，是安装GraphQL.Server.Ui.AltairNuGet 包。仓库内的多个示例工程均采用这种方式，例如 GraphQL.Harness.csproj 与 GraphQL.DataLoader.Sample.Default.csproj 中都是直接声明：

<PackageReference Include="GraphQL.Server.Ui.Altair" Version="8.*" />

说明：GraphQL.Server.Ui.Altair属于 graphql-dotnet 组织下的独立 Server 仓库（graphql-dotnet/server），本仓库并不包含该包的实现源码。本仓库内 samples 目录下的GraphQL.Server.Polyfill工程正是为在缺少 Server 仓库的情况下运行示例而准备的替代中间件，其 GraphQL.Server.Polyfill.csproj 注释明确写道：GraphQL.NET Server resides in another repository。因此在实际生产项目中，建议安装完整的GraphQL.Server系列包（如GraphQL.Server.All，参见 aspnetcore.md 中的 Quick Start）。

安装完成后，只需在请求管线的配置代码中追加一行。官方文档给出的经典Startup.cs写法如下：

public void Configure(IApplicationBuilder app, IHostingEnvironment env) { app.UseGraphQLAltair(); }

如果你使用的是现代 .NET 模板（minimal hosting / top-level statements），则等价写法是放在Program.cs中，例如仓库内 GraphQL.DataLoader.Sample.Default/Program.cs 的做法：

var app = builder.Build(); app.UseGraphQL(); // 挂载 GraphQL 端点（默认 /graphql） app.UseGraphQLAltair(); // 挂载 Altair UI（默认 /ui/altair） await app.RunAsync();

可见无论采用哪种宿主风格，核心都只有UseGraphQLAltair()这一个中间件调用。

默认端点与请求路由

官方文档明确了 Altair 集成后的默认行为：

• 如果你没有通过可选的options参数显式指定端点，Altair UI 默认运行在/ui/altair端点；
• 它默认会向/graphql这个 GraphQL API 端点发送请求。

也就是说，启动应用后访问http://localhost:5000/ui/altair即可打开 Altair 客户端界面，而界面上发起的查询会默认打到http://localhost:5000/graphql。

这里的/graphql默认端点与 GraphQL 服务中间件的默认路径是相互呼应的。仓库内GraphQL.Server.Polyfill的 GraphQLServerExtensions.cs 中UseGraphQL扩展方法的签名即为：

public static IApplicationBuilder UseGraphQL(this IApplicationBuilder builder, string path = "/graphql")

即 GraphQL 端点默认就是/graphql，与 Altair 默认的请求目标完全匹配。若你的 GraphQL 端点被改到了其他路径，则需要同时通过UseGraphQLAltair的options参数告诉 Altair 新的端点地址——这也是官方文档强调“可通过可选options参数指定 endpoints”的原因。更细粒度的选项属性（如自定义 UI 路径、GraphQL 端点、订阅端点、默认请求头等）以 GraphQL.Server 仓库的 UI 包文档为准；作为同族的参考，GraphiQL 的定制方式可见 graphiql.md，其中展示了通过GraphiQLOptions设置GraphQLEndPoint与Headers的完整示例。

仓库内的完整可运行示例

为了让读者有可直接运行的参照，仓库提供了多个已接入 Altair 的示例工程：

1. GraphQL.Harness（综合示例）

GraphQL.Harness/Startup.cs 在一个应用中同时挂载了多个 UI 中间件：

app.UseGraphQL(); app.UseGraphQLGraphiQL(); app.UseGraphQLAltair(); app.UseGraphQLVoyager();

该工程基于 StarWars 示例 Schema（通过AddSchema<StarWarsSchema>()注册），并配置了SystemTextJson序列化与字段级中间件，是观察 Altair 与 GraphQL.NET 服务端配合的最直接样本。其入口 Program.cs 同时兼容传统WebHost.CreateDefaultBuilder与 .NET 10 的WebApplication.CreateBuilder两种宿主模式。

2. GraphQL.DataLoader.Sample.Default / GraphQL.DataLoader.Sample.DI（业务示例）

这两个示例工程基于 SQLite 的汽车经销店场景，演示 DataLoader 批量加载。它们在 Program.cs 中同样以app.UseGraphQL(); app.UseGraphQLAltair();的组合挂载服务与 IDE，并在各自的 README 中说明使用GraphQL.Server.All包配合 Altair UI 呈现。运行方式均为标准的dotnet run，启动后即可在浏览器中通过 Altair 调试查询、验证 DataLoader 的批处理行为。

与其他 IDE 选项的取舍

GraphQL.Server 为 ASP.NET Core 提供了多种可视化调试 UI，除 Altair 外还包括：

• GraphiQL：交互式浏览器内 GraphQL IDE，集成方式与默认端点见 graphiql.md（默认挂载于/ui/graphiql）；
• Voyager：Schema 可视化图谱工具；
• Playground：另一款常见 GraphQL IDE。

Altair 的差异化优势在于其开箱即用的订阅调试、查询脚手架、请求格式化、多语言与主题支持等增强特性（见官方文档首段描述）。由于这些 UI 中间件可以同时挂载而互不冲突（如 GraphQL.Harness 所示），你完全可以在开发环境中同时启用多个 IDE，按需切换。

注意事项

• UI 包与核心库分属不同仓库：GraphQL.Server.Ui.Altair由 graphql-dotnet/server 仓库提供，安装时注意与GraphQL.Server.Transports.AspNetCore（提供UseGraphQL中间件）配套使用；若直接使用本仓库的 polyfill 替代实现，请留意 GraphQL.Server.Polyfill.csproj 中“不应用于生产环境”的注释说明。
• 端点一致性：Altair 默认请求/graphql，若自定义了 GraphQL 端点路径，务必同步修改 Altair 的 options，否则界面会出现请求 404。
• 认证场景：如需在 Altair 中携带 JWT 等默认请求头，可按 GraphQL.Server UI 包的 options 文档配置；其配套思路与 graphiql.md 中通过Headers注入Authorization: Bearer <token>的方式一致。

• 后端