FSharp.Data.GraphQL.Server.AspNetCore 2.2.1

FSharp.Data.GraphQL

F# 实现的 Facebook GraphQL 查询语言规范。

安装项目模板

键入以下命令以安装用于创建 Web 应用程序的模板

从 GitHub： dotnet new -i "FSharp.Data.GraphQL::2.0.0-ci-*" --nuget-source "https://nuget.pkg.github.com/fsprojects/index.json"

从 NuGet： dotnet new -i "FSharp.Data.GraphQL::2.0.0"

快速入门

open FSharp.Data.GraphQL
open FSharp.Data.GraphQL.Types

type Person =
    { FirstName: string
      LastName: string }

// Define GraphQL type 
let PersonType = Define.Object(
    name = "Person",
    fields = [
        // Property resolver will be auto-generated
        Define.AutoField("firstName", StringType)
        // Asynchronous explicit member resolver
        Define.AsyncField("lastName", StringType, resolve = fun context person -> async { return person.LastName })
    ])

// Include person as a root query of a schema
let schema = Schema(query = PersonType)
// Create an Exector for the schema
let executor = Executor(schema)

// Retrieve person data
let johnSnow = { FirstName = "John"; LastName = "Snow" }
let reply = executor.AsyncExecute(Parser.parse "{ firstName, lastName }", johnSnow) |> Async.RunSynchronously
// #> { data: { "firstName", "John", "lastName", "Snow" } } 

它是类型安全的。诸如无效的字段或无效的返回类型等问题将在编译时进行检查。

ASP.NET / Giraffe / WebSocket（用于 GraphQL 订阅）的使用

参见 AspNetCore/README.md

演示

GraphiQL 客户端

前往GraphiQL 示例目录。要运行它，请使用调试设置构建和运行Star Wars API 示例项目 - 这将创建一个与 GraphQL 规范兼容的 Giraffe 服务器，在端口 8086 上运行。然后您需要运行 node.js GraphiQL 前端。为此，运行 npm i 以获取所有依赖项，然后运行 npm run serve | npm run dev - 这将在 http://localhost:8090/ 上启动一个 webpack 服务器。访问此链接，应该会出现 GraphiQL 编辑器。您可以尝试以下查询来使用它：

{
  hero(id:"1000") {
    id,
    name,
    appearsIn,
    homePlanet,
    friends {
      ... on Human {
        name
      }
      ... on Droid {
        name
      }
    }
  }
}

Relay.js 入门套件

第二个示例是流行的 Relay Starter Kit 的 F# 版本 - 一个使用 React.js + Relay 和兼容 Relay 的服务器 API 的示例应用程序。

要运行它，请使用调试设置构建 FSharp.Data.GraphQL 和 FSharp.Data.GraphQL.Relay 项目。然后，通过在你的 FSI 中运行 server.fsx 脚本来启动服务器 - 这将在端口 8083 上启动一个兼容 Relay 的 F# 服务器。然后，通过获取所有依赖项（《npm i》）并运行它（＜code>npm run serve | npm run dev）来构建 node.js 前端 - 这将启动一个使用 Relay 来管理应用程序状态的 React 应用程序的 webpack 服务器。您可以在 http://localhost:8083/ 上访问它。

为了更新客户端模式，请访问 http://localhost:8083/ 并将响应（即当前 F# 服务器的 introspection 查询结果）复制粘贴到 data/schema.json 中。

流功能

stream 指令现在有了额外的功能，如通过间隔和/或批大小进行批处理（缓冲）。为了使其工作，必须在 SchemaConfig.Directives 列表中放置一个自定义流指令，这个自定义指令包含两个可选参数，分别称为 interval 和 preferredBatchSize。

let customStreamDirective =
    let args = [|
        Define.Input(
            "interval",
            Nullable IntType,
            defaultValue = Some 2000,
            description = "An optional argument used to buffer stream results. ")
        Define.Input(
            "preferredBatchSize",
            Nullable IntType,
            defaultValue = None,
            description = "An optional argument used to buffer stream results. ") |]
    { StreamDirective with Args = args }
let schemaConfig =
    { SchemaConfig.Default with
        Directives = [
            IncludeDirective
            SkipDirective
            DeferDirective
            customStreamDirective
            LiveDirective ] }

可以很容易地使用内置实现来减少这个样板代码。

let streamOptions =
    { Interval = Some 2000; PreferredBatchSize = None }
let schemaConfig =
    SchemaConfig.DefaultWithBufferedStream(streamOptions)

实时查询

live 指令现在被服务器组件支持。为了支持实时查询，需要将模式中的每种类型的每个字段的配置为实时字段。这是通过使用 ILiveFieldSubscription 和 ILiveQuerySubscriptionProvider 来完成的，这些可以在 SchemaConfig 中配置。

type ILiveFieldSubscription =
    interface
        abstract member Identity : obj -> obj
        abstract member TypeName : string
        abstract member FieldName : string
    end

and ILiveFieldSubscription<'Object, 'Identity> =
    interface
        inherit ILiveFieldSubscription
        abstract member Identity : 'Object -> 'Identity
    end

and ILiveFieldSubscriptionProvider =
    interface
        abstract member HasSubscribers : string -> string -> bool
        abstract member IsRegistered : string -> string -> bool
        abstract member AsyncRegister : ILiveFieldSubscription -> Async<unit>
        abstract member TryFind : string -> string -> ILiveFieldSubscription option
        abstract member Add : obj -> string -> string -> IObservable<obj>
        abstract member AsyncPublish<'T> : string -> string -> 'T -> Async<unit>
    end

要将字段设置为实时字段，请调用 Register 扩展方法。每个订阅都需要知道一个对象标识符，因此它必须在 ILiveFieldSubscription 的 Identity 函数上配置。此外，还需要传递 ObjectDef 内部的类型名称和字段名称。

let schemaConfig = SchemaConfig.Default
let schema = Schema(root, config = schemaConfig)
let subscription =
    { Identity = fun (x : Human) -> x.Id
      TypeName = "Hero"
      FieldName = "name" }

schemaConfig.LiveFieldSubscriptionProvider.Register subscription

这样，英雄字段的名称现在能够实时更新，每当它被带有 live 指令查询时，都会更新到客户端。要向订阅者推送更新，只需调用 Publish 方法，传入类型名称、字段名称和更新后的对象即可。

let updatedHero = { hero with Name = "Han Solo - Test" }
schemaConfig.LiveFieldSubscriptionProvider.Publish "Hero" "name" updatedHero

客户端提供者

我们的客户端库现在有一个完全重新设计的类型提供者。要开始使用它，首先需要获取您尝试连接的服务器的 introspection 模式。这可以通过提供者在以下两种方式之一中完成：

1. 提供所需 GraphQL 服务器（无需任何自定义 HTTP 标头）。提供者将访问服务器，发送一个 Introspection 查询，并使用该模式提供用于发出查询的类型。

type MyProvider = GraphQLProvider<"http://some.graphqlserver.development.org">

2. 提供供提供者使用的 introspection JSON 文件。但请注意，introspection JSON 应该包含提供者所需的全部字段。您可以通过在所需服务器上运行（请添加超链接到标准 introspection 查询）来获取正确的字段，并将其保存到与使用提供者的项目在同一路径上的文件中。

type MyProvider = GraphQLProvider<"swapi_schema.json">

从现在起，您可以开始运行查询和突变了。

let operation = 
    MyProvider.Operation<"""query q {
      hero (id: "1001") {
        name
        appearsIn
        homePlanet
        friends {
          ... on Human {
            name
            homePlanet
          }
          ... on Droid {
            name
            primaryFunction
          }
        }
      }
    }""">()

// This is a instance of GraphQLProviderRuntimeContext.
// You can use it to provider a runtime URL to access your server,
// and optionally additional HTTP headers (auth headers, for example).
// If you use a local introspection file to parse the schema,
// The runtime context is mandatory.
let runtimeContext =
  { ServerUrl = "http://some.graphqlserver.production.org"
    CustomHttpHeaders = None }

let result = operation.Run(runtimeContext)

// Query result objects have pretty-printing and structural equality.
printfn "Data: %A\n" result.Data
printfn "Errors: %A\n" result.Errors
printfn "Custom data: %A\n" result.CustomData

// Response from the server:
// Data: Some
//   {Hero = Some
//   {Name = Some "Darth Vader";
// AppearsIn = [|NewHope; Empire; Jedi|];
// HomePlanet = Some "Tatooine";
// Friends = [|Some {Name = Some "Wilhuff Tarkin";
// HomePlanet = <null>;}|];};}

// Errors: <null>

// Custom data: map [("documentId", 1221427401)]

有关如何使用客户端提供者的更多信息，请参阅示例文件夹。

中间件

您可以在Executor<'Root>对象之上创建和使用中间件。

通过使用Executor查询执行过程涉及三个阶段

• 模式编译阶段：此阶段发生在Executor<'Root>类实例化时。在这个阶段，使用类型的Schema映射构建字段执行映射，其中包含所有字段定义及其字段解析函数。该映射在后续的规划和执行阶段用于检索查询的字段值。

• 操作规划阶段：此阶段发生在运行没有执行计划的查询之前。这个阶段负责分析由查询生成的AST文档，并构建用于执行的操作计划。

• 操作执行阶段：此阶段是执行查询的阶段。它需要一个执行计划，因此通常在操作规划阶段之后发生。

所有阶段都将需要的执行数据包裹在一个上下文对象内。它们通过函数在内部表示。

let internal compileSchema (ctx : SchemaCompileContext) : unit =
  // ...

let internal planOperation (ctx: PlanningContext) : ExecutionPlan =
  // ...

let internal executeOperation (ctx : ExecutionContext) : AsyncVal<GQLResponse> =
  // ...

因此，在编译Schema阶段，内在的SchemaCompileContext对象内修改Schema并生成执行映射。在操作规划阶段，使用PlanningContext对象的值生成执行计划，并将此计划与其他值一起传递到ExecutionContext对象中，然后操作执行阶段使用它们来执行查询并生成一个GQLResponse。

有了这些，中间件可以用于截获每个阶段并按需自定义它们。每个中间件必须以一个具有特定签名的函数实现，并封装在一个IExecutorMiddleware接口中。

type SchemaCompileMiddleware =
    SchemaCompileContext -> (SchemaCompileContext -> unit) -> unit

type OperationPlanningMiddleware =
    PlanningContext -> (PlanningContext -> ExecutionPlan) -> ExecutionPlan

type OperationExecutionMiddleware =
    ExecutionContext -> (ExecutionContext -> AsyncVal<GQLResponse>) -> AsyncVal<GQLResponse>

type IExecutorMiddleware =
    abstract CompileSchema : SchemaCompileMiddleware option
    abstract PlanOperation : OperationPlanningMiddleware option
    abstract ExecuteOperationAsync : OperationExecutionMiddleware option

为了便于实现，可以作为一个具体类来继承，从构造函数接收仅有的可选子中间件函数。

type ExecutorMiddleware(?compile, ?plan, ?execute) =
    interface IExecutorMiddleware with
        member _.CompileSchema = compile
        member _.PlanOperation = plan
        member _.ExecuteOperationAsync = execute

每个中间件函数都像一个截获函数一样工作，有两个参数：阶段的上下文、下一个中间件（或实际阶段，它是最后一个运行的）的功能和返回值。这些函数可以作为参数传递给Executor<'Root>对象的构造函数。

let middleware = [ ExecutorMiddleware(compileFn, planningFn, executionFn) ]
let executor = Executor(schema, middleware)

一个实用的中间件可以是测量查询规划所需时间的例子。其结果作为规划上下文中的Metadata的一部分返回。《MetaData》对象是Map的实现，它作为信息包传递的媒介，直到它包含在GQLResponse对象中返回。您可以用它通过中间件传递自定义信息。

let planningMiddleware (ctx : PlanningContext) (next : PlanningContext -> ExecutionPlan) =
    let watch = Stopwatch()
    watch.Start()
    let result = next ctx
    watch.Stop()
    let metadata = result.Metadata.Add("planningTime", watch.ElapsedMilliseconds)
    { result with Metadata = metadata }

内置中间件

在FSharp.Data.GraphQL.Server.Middleware包中存在一些内置中间件。

QueryWeightMiddleware

此中间件可用来对Schema的字段施加权重。这些加权的字段现在可用来保护服务器免受可能被用于DDOS攻击的复杂查询。

在定义字段时，我们使用扩展方法WithQueryWeight为它设置权重。

let resolveFn (h : Human) =
  h.Friends |> List.map getCharacter |> List.toSeq

let field =
  Define.Field("friends", ListOf (Nullable CharacterType),
    resolve = resolveFn).WithQueryWeight(0.5)

然后我们为Executor定义阈值中间件。如果一个查询递归地请求“朋友的朋友”，则Executor只接受嵌套4次，直到查询超过权重阈值2.0。

let middleware = [ Define.QueryWeightMiddleware(2.0) ]

ObjectListFilterMiddleware

此中间件可用来自动生成schema对象中列表字段上的过滤器。此过滤器可以作为查询中字段的参数传递，并在字段解析函数的ResolveFieldContext参数中恢复。

例如，我们可以为 Human 对象的列表字段创建一个中间件，这些字段类型是 Character option

let middleware = [ Define.ObjectListFilterMiddleware<Human, Character option>() ]

筛选参数是一个对象，它通过字段上的 filter 参数中的 JSON 定义进行映射。一个简单的例子就是筛选以字母 A 开头的英雄的朋友

query TestQuery {
    hero(id:"1000") {
        id
        name
        appearsIn
        homePlanet
        friends (filter : { name_starts_with: "A" }) {
            id
            name
        }
    }
}

这个筛选器通过中间件映射到 ObjectListFilter 定义中

type FieldFilter<'Val> =
    { FieldName : string
      Value : 'Val }

type ObjectListFilter =
    | And of ObjectListFilter * ObjectListFilter
    | Or of ObjectListFilter * ObjectListFilter
    | Not of ObjectListFilter
    | Equals of FieldFilter<System.IComparable>
    | GreaterThan of FieldFilter<System.IComparable>
    | LessThan of FieldFilter<System.IComparable>
    | StartsWith of FieldFilter<string>
    | EndsWith of FieldFilter<string>
    | Contains of FieldFilter<string>
    | FilterField of FieldFilter<ObjectListFilter>

查询中回收的筛选值可以在字段的解析函数的 ResolveFieldContext 中使用。为了方便访问，可以使用扩展方法 Filter，它返回一个 ObjectListFilter option（如果没有实现带有中间件泛型定义的列表，或者用户没有提供筛选输入，则它没有值）。

Define.Field("friends", ListOf (Nullable CharacterType),
    resolve = fun ctx (d : Droid) -> 
        ctx.Filter |> printfn "Droid friends filter: %A"
        d.Friends |> List.map getCharacter |> List.toSeq)

通过从字段解析上下文检索这个筛选器，可以使用客户端代码定制数据库查询的查询，并扩展 GraphQL API 功能。

LiveQueryMiddleware

这个中间件可以快速允许你的模式字段使用 live 指令进行查询，假设所有字段都有一个可以由函数 IdentityNameResolver 发现的身份属性名。

/// A function that resolves an identity name for a schema object, based on a object definition of it.
type IdentityNameResolver = ObjectDef -> string

例如，如果我们所有模式对象都有一个名为 Id 的身份字段，我们可以这样使用我们的中间件

let schema = Schema(query = queryType)

let middleware = [ Define.LiveQueryMiddleware(fun _ -> "Id") ]

let executor = Executor(schema, middleware)

IdentityNameResolver 是可选的。如果没有提供解析函数，则使用此默认实现。同样，必须通过 ILiveFieldSubscriptionProvider 的 Publish 来执行对订阅者的通知，如上述所述。

使用扩展来构建自己的中间件

您可以使用由 FSharp.Data.GraphQL.Shared 包提供的扩展方法来帮助构建自己的中间件。创建中间件时，通常需要修改模式定义以向用户代码定义的模式添加功能。例如，ObjectListFilter 中间件需要一个名为 filter 的参数来修改实现特定类型列表的所有字段。

由于字段定义默认是不可变的，因此在模式编译阶段向已定义的字段中添加一个参数可能需要大量的工作。这就是扩展方法发挥作用的地方：例如，如果您需要在模式的编译阶段向已经定义的字段中添加一个参数，您可以使用 FieldDef<'Val> 接口的 WithArgs 方法。

let field : FieldDef<'Val> = // Search for field inside ISchema
let arg : Define.Input("id", StringType)
let fieldWithArg = field.WithArgs([ arg ])

要查看用于增强定义的扩展方法列表，请查看 FSharp.Data.GraphQL.Shared 包中包含的 TypeSystemExtensions 模块。