水环QL

HydraphQL 提供了通过还原来组织您的 Schema 的功能 重复并用 图QL 模块 定义新 类型和如何解决它们.

• 指令 API
  • @field
  • @implements
  • @discriminates
  • @discriminationAlias
  • @resolve
• 开始
  • 图QL 应用程序
  • 扩展Schema
  • @graphql-codegen/ Type 脚本

指令 API

通过图形QL模块,您可以构建您的图形ql代码基础, 但您仍然需要使用 TypeScript 代码来写解析器 。 不过, hydraphQL最重要的优势之一是,大多数的 您不需要写入任何类型脚本 。 相反,你可以告诉 GraphQL 通过直接向Schema添加关于它应该做什么的提示 哪个字段映射到什么。 这些提示叫做 directives。 。 。 .

以下指令将告诉 GraphQL 如何写入解析器 自动,所以你不用.

@field

@ field 指令允许您访问对象的属性 使用给定路径。 它允许您指定一个字段的解析器 完全没有写一个真正的解析器 下 盖子,它为你创造了解药。 要看到这个行动, 检查出来 catalog.graphql 使用 @field 广泛指令取回模块 属性类 namespace, (中文(简体) ), title 还有其他.

1. 绘图 namespace.name 从源数据到 Entity#name 字段 :

type Entity {
  name: String! @field(at: "namespace.name")
}

2. 如果源路径的字段包含点 { spec: { "data.label": "..." } },可以使用数组 :

type Entity {
  label: String @field(at: ["spec", "data.label"])
}

3. 如果找不到字段, 您可以指定默认值为倒计时 :

type Entity {
  tag: String! @field(at: "spec.tag", default: "N/A")
}

@implements

这个 @implements 指令允许您从另一个字段继承 接口。 我们创建这个指令是为了更容易执行 从其他接口继承的接口。 它使图形QL类型 类似于 TypeScript 中的扩展类型。 在类型脚本中,当一个类 继承另一类, 孩子类自动继承 父类的属性和方法。 这个功能没有 在 GraphQL 有等同的图形。 没有这个指令 Service graphQL 中的接口需要重新执行许多字段 定义了导致大量重复的已执行接口.

1. 使用此指令定义新类型 包括父界面的所有属性.

type Service @implements(interface: "Component") {
  endpoint: String! @field(at: "spec.endpoint")
}

在产出计划中,它转变为:

type Service implements Component & Entity & Node {
  id: ID!
  name: String!
  kind: String!
  namespace: String!
  # ... rest `Entity` and `Component` fields ...

  endpoint: String!
}

@discriminates

这个 @discriminates 指令告诉 GraphQL App 接口 被某个特定值歧视到另一个接口或类型. 按路径排列的值 with 参数用于确定 键入接口应解决.

interface Entity
  @implements(interface: "Node")
  @discriminates(with: "kind") {
    # ...
  }

type Component @implements(interface: "Entity") {
  # ...
}
type Service @implements(interface: "Entity") {
  # ...
}

注:本例中,如果我们掌握下列数据: Entity 类型,它已经 kind 字段 与 Component 值,这意味着数据将被解决到 Component 类型

当运行时间数据没有值时有一个特殊的情况 用于区分界面或没有类型 和数值相符 在这种情况下,你可以定义 opaqueType 参数

interface Entity
  @implements(interface: "Node")
  @discriminates(with: "kind", opaqueType: "OpaqueEntity") {
    # ...
  }

在这种情况下,如果 kind 字段与任何计划类型不符, 页:1 OpaqueEntity 类型将被使用。 您不需要定义此类型, GraphQL 插件会为你生成它 .

还有另一种方法通过使用 generateOpaqueTypes 选项.

@discriminationAlias

默认值从 with 参数用于找到类型为-is或转换为PascalCase. 有时需要将数值与有不同名称的类型相匹配. 在这种情况下,你可以使用 @discriminationAlias 指令.

interface API
  @implements(interface: "Node")
  @discriminates(with: "spec.type")
  @discriminationAlias(value: "openapi", type: "OpenAPI") {
    # ...
  }

type OpenAPI @implements(interface: "API") {
  # ...
}

这意味着,当 spec.type 等于 openapi,则 API 界面将被解析为 OpenAPI 类型.

@resolve

这个 @resolve 指令类似于 @field 指令,但改为 从源数据中解出一个字段,它从第三方中解出一个字段 API (英语). 如果您想要在您的计划中添加字段, 则此选项很有用 来源数据中已有,但可从另一个API中获取.

1. 要做到这一点,首先需要创建数据记录器 createLoader 函数

import querystring from "querystring";
import { createLoader, NodeQuery } from "@frontside/hydraphql";

export const loader = createLoader({
  async ExampleCom(queries: NodeQuery[]) {
    return Promise.all(
      queries.map(async ({ ref, args }) => {
        const response = await fetch(
          `https://example.com/api/${ref}?${querystring.stringify(args)}`,
        );
        return response.json();
      }),
    );
  },
});

2. 那你可以用这个 @resolve 指定您 API 的加载器名称的指示 :

type Project {
  tasks: [Task!] @resolve(at: "spec.projectId", from: "ExampleCom")
}

开始

图QL 应用程序

由于 HydraphQL 使用 GraphQL 模块 createGraphQLApp 返回图形QL应用程序 它可用于所有流行的 GraphQL 服务器,如 apollo-server, (中文(简体) ), express-graphql, (中文(简体) ), graphql-yoga 还有其他.

1. 通过使用创建应用程序 createGraphQLApp 函数

import {
  createGraphQLApp,
  createLoader,
  NodeQuery,
} from "@frontside/hydraphql";
import modules from "./modules";

export async function main() {
  const application = await createGraphQLApp({ modules });
  const loader = createLoader({
    async MyAPI(queries: NodeQuery[]) {
      // ...
    },
  });

  //...
}

2. 使用您的 GraphQL 服务器的应用程序

页:1 您可以找到如何使用 HydraphQL 的简单示例 graphql-yoga 内 examples/graphql-yoga 目录.

用自定义模块扩展您的计划

要扩展您的方案, 您将使用 GraphQL Schema 定义定义 语言,然后(可选择的)写解析器来处理各种类型 你所定义的.

1. 创建模块目录,用于存储您的 GraphQL 模块, 例如 ./src/modules
2. 创建模块目录 my-module 那边
3. 创建 GraphQL 计划文件 my-module.graphql 模块目录中

extend type Query {
  hello: String!
}

此代码添加 a hello 区域 Query 类型。 接下来,我们将 编写包含此方案及其解析器的模块.

4. 创建 GraphQL 模块文件 my-module.ts 模块目录中

import { loadFilesSync } from "@graphql-tools/load-files";
import { createModule } from "graphql-modules";

export const myModule = createModule({
  id: "my-module",
  dirname: __dirname,
  typeDefs: loadFilesSync(require.resolve("./my-module.graphql")),
  resolvers: {
    Query: {
      hello: () => "world",
    },
  },
});

@graphql-codegen脚本

如果您使用 @graphql-codegen 生成输出计划以用于 校验前端查询和/或类型脚本以进行类型检查 GraphQL 模块解析器, 您需要修改 @graphql-codegen 相会.

1. 首先创建一个 schema.ts 文件为 transformSchema 函数并传递您的 GraphQL 文件

// ./src/schema.ts
import { transformSchema } from "@frontside/hydraphql";
import { printSchemaWithDirectives } from "@graphql-tools/utils";
import { MyModule } from "./modules/my-module/my-module";

export const schema = printSchemaWithDirectives(transformSchema([MyModule]));

2. 那你需要更新 schema 选项 codegen.ts

import { CodegenConfig } from "@graphql-codegen/cli";
import { schema } from "./src/schema";

const config: CodegenConfig = {
  schema,
  generates: {
    /* ... */
  },
};

export default config;