前端GraphQL【免费下载链接】apollo-clientThe industry-leading GraphQL client for TypeScript, JavaScript, React, Vue, Angular, and more. Apollo Client delivers powerful caching, intuitive APIs, and comprehensive developer tools to accelerate your app development.项目地址https://gitcode.com/gh_mirrors/ap/apollo-client点击查看免费下载SchemaLink 是 Apollo Client 提供的一个终止型terminatingApolloLink它不发起任何网络请求而是将 GraphQL 操作直接交给本地的一个可执行 GraphQL Schema如通过makeExecutableSchema或buildSchema构建执行并把执行结果封装成标准 Observable 返回。本篇指南以.api-reports/api-report-link_schema.api.md中定义的公开 API 为骨架结合apollo/client/link/schema的源码实现、单元测试与集成测试完整讲解SchemaLink的构造选项、类型签名、执行流程以及服务端渲染SSR和 Mock 数据两大核心实战场景。读完本文你将能独立使用SchemaLink搭建零网络请求的 GraphQL 客户端链路并理解其与 Apollo Client 本地状态管理的边界。SchemaLink 是什么在 Apollo Client 的 Link 体系里请求会按顺序穿过一条由多个 link 组成的链chain。链上的 link 可以对操作进行修改、打日志、加鉴权头但最终必须有一个终止型 link真正处理请求。HttpLink是面向远程服务器的终止型 link而SchemaLink则是面向本地 Schema 的终止型 link它直接在当前进程中完成 GraphQL 查询的解析与执行。SchemaLink的定位和典型应用场景见 docs/source/api/link/apollo-link-schema.mdx服务端渲染SSR当客户端与渲染进程运行在同一台服务器上时用SchemaLink代替网络调用避免为每个 SSR 请求发起一次 HTTP 往返Mocking / 测试把带 mock resolvers 的 Schema 接进客户端使前端在真实后端就绪前就能基于真实 GraphQL 查询结构开发、联调与测试。SchemaLink从apollo/client/link/schema子路径导出。公开导出项只有一个SchemaLink类这一点由 src/tests/exports.ts 的快照.api-reports校验体系锁定exports of public entry points apollo/client/link/schema的导出数组仅包含字符串SchemaLink。import { SchemaLink } from apollo/client/link/schema;公开 API 总览API Report 解读.api-reports/api-report-link_schema.api.md是 API Extractor 自动生成的公开 API 报告它完整刻画了SchemaLink的类型面。先看整体结构// public export class SchemaLink extends ApolloLink { constructor(options: SchemaLink.Options); context: SchemaLink.Options[context]; request(operation: ApolloLink.Operation): ObservableApolloLink.Result; rootValue: SchemaLink.Options[rootValue]; schema: SchemaLink.Options[schema]; validate: boolean; }SchemaLink继承自ApolloLink基类定义见 src/link/core/ApolloLink.ts并拥有四个公开实例属性schema、rootValue、context、validate它们与构造参数一一对应此外覆盖了request方法作为请求处理器。request的返回类型是ObservableApolloLink.Result其中ApolloLink.Result即graphql库的FormattedExecutionResult可含data与errors这说明 SchemaLink 的输出与远程 GraphQL 服务器返回的 JSON 结构完全一致。SchemaLink.Options 选项接口Options是构造函数唯一入参的类型其中schema为必填项export interface Options { context?: SchemaLink.ResolverContext | SchemaLink.ResolverContextFunction; rootValue?: any; schema: GraphQLSchema; validate?: boolean; }下表汇总各选项的作用、默认值与使用建议选项类型必填默认值作用schemaGraphQLSchema是无用于执行操作的可执行 GraphQL Schema应通过makeExecutableSchemagraphql-tools/schema或buildSchemagraphql创建rootValueany否undefined传给根级 resolver 的根值root value大多数 Schema 用不到仅少数高级模式需要contextResolverContext或ResolverContextFunction否undefined传给所有 GraphQL resolver 的第三个参数——上下文对象可以是静态对象也可以是按操作动态生成上下文的函数validateboolean否false是否在执行前用graphql的validate校验查询文档开启后校验错误会像远程服务器一样放进结果的errors数组两个 Context 类型export type ResolverContext Recordstring, any; export type ResolverContextFunction (operation: ApolloLink.Operation) SchemaLink.ResolverContext | PromiseLikeSchemaLink.ResolverContext;ResolverContext普通对象通常装数据获取连接器data-fetching connectors、鉴权信息以及其它请求级数据它会被透传给每个 resolver 的第三个参数。ResolverContextFunction一个接收ApolloLink.Operation、返回上下文对象或返回 Promise的函数。由于它在每个操作上被调用你可以把操作上下文operation.getContext()里携带的 headers、variables 等信息加工进 resolver 上下文实现每个请求一套上下文。源码注释里给出了典型用法src/link/schema/index.tsconst link new SchemaLink({ schema, context: (operation) { return { userId: operation.getContext().userId, dataSources: { userAPI: new UserAPI(), }, }; }, });构造函数与内部执行流程源码级构造函数实现非常直白src/link/schema/index.ts保存四个选项并用!!options.validate把validate归一化为布尔值——这也解释了为什么validate的默认值是false。核心逻辑在request方法中src/link/schema/index.ts它返回一个基于rxjs的Observable内部流程可以概括为四步解析 context若context是函数则调用this.context(operation)否则直接使用静态对象并用Promise.resolve包裹以统一支持同步/异步上下文可选执行查询校验若validate为true调用graphql的validate(this.schema, operation.query)一旦存在校验错误直接返回{ errors: validationErrors }——这与真实 GraphQL 服务器的行为一致执行操作调用graphql的execute把schema、document操作文档、rootValue、解析出的contextValue、variableValues操作变量和operationName全部传入派发结果执行成功后调用observer.next(data)与observer.complete()若 observer 未关闭执行抛错时调用observer.error(error)。export class SchemaLink extends ApolloLink { public request(operation: ApolloLink.Operation): ObservableApolloLink.Result { return new ObservableApolloLink.Result((observer) { new PromiseSchemaLink.ResolverContext((resolve) resolve( typeof this.context function ? this.context(operation) : this.context ) ) .then((context) { if (this.validate) { const validationErrors validate(this.schema, operation.query); if (validationErrors.length 0) { return { errors: validationErrors }; } } return execute({ schema: this.schema, document: operation.query, rootValue: this.rootValue, contextValue: context, variableValues: operation.variables, operationName: operation.operationName, }); }) .then((data) { if (!observer.closed) { observer.next(data); observer.complete(); } }) .catch((error) { if (!observer.closed) { observer.error(error); } }); }); } }值得注意的细节因为底层用的是graphql的execute所以SchemaLink天然支持同步执行——单元测试 src/link/schema/tests/schemaLink.ts 中专门有一条supports query which is executed synchronously用内省查询introspection query验证同步路径也能正常nextcomplete结果契约resolver 抛出的错误不会以 Observable 的error通道传播而是进入执行结果的errors数组data相应字段为null测试用例 calls error when fetch fails 断言了这一点await expect(stream).toEmitTypedValue({ data: { sampleQuery: null }, errors: [{ message: Unauthorized, path: [sampleQuery] }], });validate开启后对 Schema 上不存在的字段会返回形如Cannot query field unknown on type Query.的校验错误测试 reports errors for unknown queries。实战一服务端渲染SSR中避免网络调用最经典的使用方式SSR 与客户端同机时用SchemaLink让服务端渲染直接在当前进程内执行查询。docs 中的完整示例docs/source/api/link/apollo-link-schema.mdximport { ApolloClient, InMemoryCache } from apollo/client; import { SchemaLink } from apollo/client/link/schema; import schema from ./path/to/your/schema; const graphqlClient new ApolloClient({ cache: new InMemoryCache(), ssrMode: true, link: new SchemaLink({ schema }), });要点配合ssrMode: true使用提示客户端处于服务端渲染模式避免额外的重复请求link直接传入new SchemaLink({ schema })不需要再串联HttpLink因为SchemaLink本身就是终止型 link渲染得到的 Apollo 状态__APOLLO_STATE__可随 HTML 一起注入浏览器端再用new InMemoryCache(window.__APOLLO_STATE__)水合。仓库的 Next.js 集成测试 integration-tests/next/src/libs/schemaLink.ts 展示了真实的落地形态先用makeExecutableSchema({ typeDefs, resolvers })组装包含 resolver 的 Schema再export const schemaLink new SchemaLink({ schema })供页面使用——这个文件正是integration-tests/next中 SSR 用例的链接来源。实战二用 Mock resolvers 做前端开发与测试当后端接口未就绪时可以用graphql-tools的 mock 能力生成 schema 后交给SchemaLink。docs 中的示例import { ApolloClient, InMemoryCache } from apollo/client; import { SchemaLink } from apollo/client/link/schema; import { makeExecutableSchema, addMockFunctionsToSchema } from graphql-tools; const typeDefs Query { ... } ; const mocks { Query: () ..., Mutation: () ... }; const schema makeExecutableSchema({ typeDefs }); const schemaWithMocks addMockFunctionsToSchema({ schema, mocks }); const apolloCache new InMemoryCache(window.__APOLLO_STATE__); const graphqlClient new ApolloClient({ cache: apolloCache, link: new SchemaLink({ schema: schemaWithMocks }) });这段代码的关键在于查询仍是真实的前端查询文档只是执行引擎被换成了带 mock 的本地 Schema因此查询的字段结构、变量、别名等都会被真实校验能提前暴露前后端字段不一致的问题。这也是为什么测试领域普遍用SchemaLink驱动基于真实查询的组件测试。单元测试覆盖的行为契约src/link/schema/tests/schemaLink.ts 用makeExecutableSchema构造了一个type Query { sampleQuery: Stub }的迷你 Schema验证了以下行为可作为你使用时的心智模型测试用例验证的行为throws if no arguments given不传参数构造会抛错schema必填correctly receives the constructor arguments构造参数被原样保存在公开属性上link.schema、link.rootValuecalls next and then complete正常路径先next再completecalls error when fetch failsresolver 抛错时错误进入结果的errors而非 Observable 的 error 通道passes operation context into execute with context functioncontext函数按操作调用测试断言只调用 1 次返回值被传给 resolverpasses static context into execute静态context对象被透传给每个 resolverreports errors for unknown queriesvalidate: true时未知字段返回校验错误其中context 函数按操作调用与静态 context 透传两条直接对应Options.context的两种形态ResolverContext | ResolverContextFunction是你在设计多租户、按请求注入用户信息时最重要的依据。使用注意事项与边界validate的取舍默认关闭以避免额外开销。源码注释建议在测试与开发阶段开启以尽早暴露查询错误生产环境视 Schema 体量与性能要求决定。开启后校验错误会以errors数组形式返回和远程服务器表现一致。包体积提醒SchemaLink依赖完整的graphql执行层这一层体积较大。官方文档明确提示客户端本地状态管理优先考虑 Apollo Client 的 local state 功能与缓存集成SchemaLink更适合 SSR 同机渲染、mock 与测试这类场景不应作为浏览器端常规数据层的默认选择。与 Link 链的组合SchemaLink是终止型 link你可以把它作为链的末端与其它 link 组合——例如前面接日志 link、错误重试 link最后落到SchemaLink执行也可以用split按条件在SchemaLink与HttpLink之间路由比如开发环境用本地 Schema、生产环境走网络。基类ApolloLink提供了from、split、concat等组合能力见 src/link/core/ApolloLink.ts。类型安全context与rootValue的取值自由度高Recordstring, any与any实际项目建议用 TypeScript 泛型或类型断言收窄 resolver 的 context 类型。总结SchemaLink是 Apollo Client Link 体系中在进程内执行 GraphQL的入口schema必填决定执行目标rootValue支撑根级高级模式context支持静态与按操作动态两种注入方式validate控制是否先校验再执行。通过源码可以看到它的实现只有一次 context 解析、一次可选校验和一次graphql.execute调用行为契约同步执行、错误进errors、nextcomplete 生命周期均有单元测试背书。对 SSR 同机渲染、前端 mock 联调与组件测试这三类需求它都是比起一个假 HTTP 服务更轻量、更贴近真实 GraphQL 语义的解决方案。延伸阅读仓库内路径API 报告.api-reports/api-report-link_schema.api.md源码实现src/link/schema/index.ts单元测试src/link/schema/tests/schemaLink.ts官方用法文档docs/source/api/link/apollo-link-schema.mdxNext.js 集成示例integration-tests/next/src/libs/schemaLink.tsLink 基类与组合能力src/link/core/ApolloLink.ts赞分享前端GraphQL【免费下载链接】apollo-clientThe industry-leading GraphQL client for TypeScript, JavaScript, React, Vue, Angular, and more. Apollo Client delivers powerful caching, intuitive APIs, and comprehensive developer tools to accelerate your app development.项目地址https://gitcode.com/gh_mirrors/ap/apollo-client点击查看免费下载相关推荐Pixelle-Video 一句话生成 AI 短视频完整指南Pixelle Video 一句话生成 AI 短视频完整指南 在 Pixelle Video 里输入一句健康饮食的重要性等上 2 5 分钟一条成片短视频人工智能AI 应用音视频媒体生成如何在5分钟内完成黑苹果EFI配置OpCore-Simplify终极自动化指南如何在5分钟内完成黑苹果EFI配置OpCore Simplify终极自动化指南 想要体验macOS但被复杂的EFI配置吓退OpCore Simplify正是开发工具CLIDynamicTp架构设计与多租户线程池性能优化实践DynamicTp架构设计与多租户线程池性能优化实践 DynamicTp是一款基于配置中心的轻量级动态线程池框架内置监控告警功能支持主流配置中心集成和SPI后端任务调度可观测性上一篇如何为 GitHub Enterprise Server 配置 repository cache 加速仓库克隆下一篇开源贡献指南如何为react-awesome-shapes新增一个形状组件并提交你的第一个PR创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考