从Hello World开始理解GraphQL背后处理及执行过程

package com.graphqljava.tutorial.bookdetails;
import graphql.ExecutionResult;
import graphql.GraphQL;
import graphql.schema.GraphQLSchema;
import graphql.schema.StaticDataFetcher;
import graphql.schema.idl.RuntimeWiring;
import graphql.schema.idl.SchemaGenerator;
import graphql.schema.idl.SchemaParser;
import graphql.schema.idl.TypeDefinitionRegistry;
public class HelloWorld {
    public static void main(String[] args) {
        // 从最简单的schema字符串开始，省去对graphqls文件的读取
        String schema = "type Query{hello: String}";
        // 用于获得graphql schema定义，并解析放入TypeDefinitionRegistry中，以便放置在SchemaGenerator中使用
        SchemaParser schemaParser = new SchemaParser();
        // 解析schema定义字符串，并创建包含一组类型定义的TypeDefinitionRegistry
        TypeDefinitionRegistry typeDefinitionRegistry = schemaParser.parse(schema);
        // runtime wiring 是data fetchers、type resolves和定制标量的规范，这些都需要连接到GraphQLSchema中
        RuntimeWiring runtimeWiring = RuntimeWiring.newRuntimeWiring()
                // 添加一个类型连接
                .type("Query", builder -> builder.dataFetcher("hello", new StaticDataFetcher("world")))
                .build();
        //schemaGenerator对象可以使用typeDefinitionRegistry、runtimeWiring生成工作运行时schema
        SchemaGenerator schemaGenerator = new SchemaGenerator();
        //graphQLSchema代表graphql引擎的组合类型系统。
        GraphQLSchema graphQLSchema = schemaGenerator.makeExecutableSchema(typeDefinitionRegistry, runtimeWiring);
        //构建GraphQL用于执行查询
        GraphQL build = GraphQL.newGraphQL(graphQLSchema).build();
        //执行并获得结果
        ExecutionResult executionResult = build.execute("{hello}");
        System.out.println(executionResult.getData().toString());
    }
}

public TypeDefinitionRegistry parse(String schemaInput) throws SchemaProblem {
    try {
        Parser parser = new Parser();
        Document document = parser.parseDocument(schemaInput);
        return buildRegistry(document);
    } catch (ParseCancellationException e) {
        throw handleParseException(e);
    }
}

public TypeDefinitionRegistry buildRegistry(Document document) {
    List<GraphQLError> errors = new ArrayList<>();
    TypeDefinitionRegistry typeRegistry = new TypeDefinitionRegistry();
    List<Definition> definitions = document.getDefinitions();
    for (Definition definition : definitions) {
        if (definition instanceof SDLDefinition) {
            typeRegistry.add((SDLDefinition) definition).ifPresent(errors::add);
        }
    }
    if (errors.size() > 0) {
        throw new SchemaProblem(errors);
    } else {
        return typeRegistry;
    }
}

public Document parseDocument(String input, String sourceName) {
    CharStream charStream;
    if(sourceName == null) {
        charStream = CharStreams.fromString(input);
    } else{
        charStream = CharStreams.fromString(input, sourceName);
    }
    GraphqlLexer lexer = new GraphqlLexer(charStream);
    CommonTokenStream tokens = new CommonTokenStream(lexer);
    GraphqlParser parser = new GraphqlParser(tokens);
    parser.removeErrorListeners();
    parser.getInterpreter().setPredictionMode(PredictionMode.SLL);
    parser.setErrorHandler(new BailErrorStrategy());
    //词法分析从schema中解析出tokens（每个关键字、最后一个为EOF），documentContext包含children、start/stop字符等相当于结构。
    GraphqlParser.DocumentContext documentContext = parser.document();
    GraphqlAntlrToLanguage antlrToLanguage = new GraphqlAntlrToLanguage(tokens);
    // 生成document
    Document doc = antlrToLanguage.createDocument(documentContext);
    Token stop = documentContext.getStop();
    List<Token> allTokens = tokens.getTokens();
    if (stop != null && allTokens != null && !allTokens.isEmpty()) {
        Token last = allTokens.get(allTokens.size() - 1);
        //
        // do we have more tokens in the stream than we consumed in the parse?
        // if yes then its invalid.  We make sure its the same channel
        boolean notEOF = last.getType() != Token.EOF;
        boolean lastGreaterThanDocument = last.getTokenIndex() > stop.getTokenIndex();
        boolean sameChannel = last.getChannel() == stop.getChannel();
        if (notEOF && lastGreaterThanDocument && sameChannel) {
            throw new ParseCancellationException("There are more tokens in the query that have not been consumed");
        }
    }
    return doc;
}

public Builder type(String typeName, UnaryOperator<TypeRuntimeWiring.Builder> builderFunction) {
    TypeRuntimeWiring.Builder builder = builderFunction.apply(TypeRuntimeWiring.newTypeWiring(typeName));
    return type(builder.build());
}

public Builder type(TypeRuntimeWiring typeRuntimeWiring) {
    String typeName = typeRuntimeWiring.getTypeName();
    Map<String, DataFetcher> typeDataFetchers = dataFetchers.computeIfAbsent(typeName, k -> new LinkedHashMap<>());
    typeRuntimeWiring.getFieldDataFetchers().forEach(typeDataFetchers::put);
    defaultDataFetchers.put(typeName, typeRuntimeWiring.getDefaultDataFetcher());
    TypeResolver typeResolver = typeRuntimeWiring.getTypeResolver();
    if (typeResolver != null) {
        this.typeResolvers.put(typeName, typeResolver);
    }
    EnumValuesProvider enumValuesProvider = typeRuntimeWiring.getEnumValuesProvider();
    if (enumValuesProvider != null) {
        this.enumValuesProviders.put(typeName, enumValuesProvider);
    }
    return this;
}

public GraphQL build() {
    assertNotNull(graphQLSchema, "graphQLSchema must be non null");
    assertNotNull(queryExecutionStrategy, "queryStrategy must be non null");
    assertNotNull(idProvider, "idProvider must be non null");
    return new GraphQL(graphQLSchema, queryExecutionStrategy, mutationExecutionStrategy, subscriptionExecutionStrategy, idProvider, instrumentation, preparsedDocumentProvider);
}

public ExecutionResult execute(ExecutionInput executionInput) {
    try {
        return executeAsync(executionInput).join();
    } catch (CompletionException e) {
        if (e.getCause() instanceof RuntimeException) {
            throw (RuntimeException) e.getCause();
        } else {
            throw e;
        }
    }
}

public CompletableFuture<ExecutionResult> executeAsync(ExecutionInput executionInput) {
    try {
        log.debug("Executing request. operation name: '{}'. query: '{}'. variables '{}'", executionInput.getOperationName(), executionInput.getQuery(), executionInput.getVariables());
        // 创建InstrumentationState对象，这是一个跟踪Instrumentation全生命周期的对象
        InstrumentationState instrumentationState = instrumentation.createState(new InstrumentationCreateStateParameters(this.graphQLSchema, executionInput));
        InstrumentationExecutionParameters inputInstrumentationParameters = new InstrumentationExecutionParameters(executionInput, this.graphQLSchema, instrumentationState);
        // 检测输入对象
        executionInput = instrumentation.instrumentExecutionInput(executionInput, inputInstrumentationParameters);
        InstrumentationExecutionParameters instrumentationParameters = new InstrumentationExecutionParameters(executionInput, this.graphQLSchema, instrumentationState);
        // 在执行检测 chain前调用
        InstrumentationContext<ExecutionResult> executionInstrumentation = instrumentation.beginExecution(instrumentationParameters);
        // 检测GraphQLSchema
        GraphQLSchema graphQLSchema = instrumentation.instrumentSchema(this.graphQLSchema, instrumentationParameters);
        // 对客户端传递的query进行验证并执行
        CompletableFuture<ExecutionResult> executionResult = parseValidateAndExecute(executionInput, graphQLSchema, instrumentationState);
        //
        // finish up instrumentation
        executionResult = executionResult.whenComplete(executionInstrumentation::onCompleted);
        //
        // allow instrumentation to tweak the result
        executionResult = executionResult.thenCompose(result -> instrumentation.instrumentExecutionResult(result, instrumentationParameters));
        return executionResult;
    } catch (AbortExecutionException abortException) {
        return CompletableFuture.completedFuture(abortException.toExecutionResult());
    }
}

private CompletableFuture<ExecutionResult> execute(ExecutionInput executionInput, Document document, GraphQLSchema graphQLSchema, InstrumentationState instrumentationState) {
    String query = executionInput.getQuery();
    String operationName = executionInput.getOperationName();
    Object context = executionInput.getContext();
    Execution execution = new Execution(queryStrategy, mutationStrategy, subscriptionStrategy, instrumentation);
    ExecutionId executionId = idProvider.provide(query, operationName, context);
    log.debug("Executing '{}'. operation name: '{}'. query: '{}'. variables '{}'", executionId, executionInput.getOperationName(), executionInput.getQuery(), executionInput.getVariables());
    CompletableFuture<ExecutionResult> future = execution.execute(document, graphQLSchema, executionId, executionInput, instrumentationState);
    future = future.whenComplete((result, throwable) -> {
        if (throwable != null) {
            log.error(String.format("Execution '%s' threw exception when executing : query : '%s'. variables '%s'", executionId, executionInput.getQuery(), executionInput.getVariables()), throwable);
        } else {
            int errorCount = result.getErrors().size();
            if (errorCount > 0) {
                log.debug("Execution '{}' completed with '{}' errors", executionId, errorCount);
            } else {
                log.debug("Execution '{}' completed with zero errors", executionId);
            }
        }
    });
    return future;
}

public CompletableFuture<ExecutionResult> execute(Document document, GraphQLSchema graphQLSchema, ExecutionId executionId, ExecutionInput executionInput, InstrumentationState instrumentationState) {
    // 获得要执行的操作
    NodeUtil.GetOperationResult getOperationResult = NodeUtil.getOperation(document, executionInput.getOperationName());
    Map<String, FragmentDefinition> fragmentsByName = getOperationResult.fragmentsByName;
    OperationDefinition operationDefinition = getOperationResult.operationDefinition;
    ValuesResolver valuesResolver = new ValuesResolver();
    // 获得输入的参数
    Map<String, Object> inputVariables = executionInput.getVariables();
    List<VariableDefinition> variableDefinitions = operationDefinition.getVariableDefinitions();
    Map<String, Object> coercedVariables;
    try {
        coercedVariables = valuesResolver.coerceArgumentValues(graphQLSchema, variableDefinitions, inputVariables);
    } catch (RuntimeException rte) {
        if (rte instanceof GraphQLError) {
            return completedFuture(new ExecutionResultImpl((GraphQLError) rte));
        }
        throw rte;
    }
    ExecutionContext executionContext = newExecutionContextBuilder()
            .instrumentation(instrumentation)
            .instrumentationState(instrumentationState)
            .executionId(executionId)
            .graphQLSchema(graphQLSchema)
            .queryStrategy(queryStrategy)
            .mutationStrategy(mutationStrategy)
            .subscriptionStrategy(subscriptionStrategy)
            .context(executionInput.getContext())
            .root(executionInput.getRoot())
            .fragmentsByName(fragmentsByName)
            .variables(coercedVariables)
            .document(document)
            .operationDefinition(operationDefinition)
            // 放入dataloder
            .dataLoaderRegistry(executionInput.getDataLoaderRegistry())
            .build();
    InstrumentationExecutionParameters parameters = new InstrumentationExecutionParameters(
            executionInput, graphQLSchema, instrumentationState
    );
    // 获得执行上下文
    executionContext = instrumentation.instrumentExecutionContext(executionContext, parameters);
    return executeOperation(executionContext, parameters, executionInput.getRoot(), executionContext.getOperationDefinition());
}

private CompletableFuture<ExecutionResult> executeOperation(ExecutionContext executionContext, InstrumentationExecutionParameters instrumentationExecutionParameters, Object root, OperationDefinition operationDefinition) {
    // ...
    ExecutionStrategyParameters parameters = newParameters()
            .executionStepInfo(executionStepInfo)
            .source(root)
            .fields(fields)
            .nonNullFieldValidator(nonNullableFieldValidator)
            .path(path)
            .build();
    CompletableFuture<ExecutionResult> result;
    try {
        ExecutionStrategy executionStrategy;
        if (operation == OperationDefinition.Operation.MUTATION) {
            executionStrategy = mutationStrategy;
        } else if (operation == SUBSCRIPTION) {
            executionStrategy = subscriptionStrategy;
        } else {
            executionStrategy = queryStrategy;
        }
        log.debug("Executing '{}' query operation: '{}' using '{}' execution strategy", executionContext.getExecutionId(), operation, executionStrategy.getClass().getName());
        result = executionStrategy.execute(executionContext, parameters);
    } catch (NonNullableFieldWasNullException e) {
          // ...
    }
    // ...
    return deferSupport(executionContext, result);
}

public CompletableFuture<ExecutionResult> execute(ExecutionContext executionContext, ExecutionStrategyParameters parameters) throws NonNullableFieldWasNullException {
    Instrumentation instrumentation = executionContext.getInstrumentation();
    InstrumentationExecutionStrategyParameters instrumentationParameters = new InstrumentationExecutionStrategyParameters(executionContext, parameters);
    ExecutionStrategyInstrumentationContext executionStrategyCtx = instrumentation.beginExecutionStrategy(instrumentationParameters);
    Map<String, List<Field>> fields = parameters.getFields();
    // 字段名称
    List<String> fieldNames = new ArrayList<>(fields.keySet());
    List<CompletableFuture<FieldValueInfo>> futures = new ArrayList<>();
    List<String> resolvedFields = new ArrayList<>();
    for (String fieldName : fieldNames) {
        List<Field> currentField = fields.get(fieldName);
        ExecutionPath fieldPath = parameters.getPath().segment(mkNameForPath(currentField));
        ExecutionStrategyParameters newParameters = parameters
                .transform(builder -> builder.field(currentField).path(fieldPath).parent(parameters));
        if (isDeferred(executionContext, newParameters, currentField)) {
            executionStrategyCtx.onDeferredField(currentField);
            continue;
        }
        resolvedFields.add(fieldName);
        // 处理字段，这里处理的是"hello"
        CompletableFuture<FieldValueInfo> future = resolveFieldWithInfo(executionContext, newParameters);
        futures.add(future);
    }
    CompletableFuture<ExecutionResult> overallResult = new CompletableFuture<>();
    executionStrategyCtx.onDispatched(overallResult);
    //并行执行所有filed处理的futures
    Async.each(futures).whenComplete((completeValueInfos, throwable) -> {
        BiConsumer<List<ExecutionResult>, Throwable> handleResultsConsumer = handleResults(executionContext, resolvedFields, overallResult);
        if (throwable != null) {
            handleResultsConsumer.accept(null, throwable.getCause());
            return;
        }
        List<CompletableFuture<ExecutionResult>> executionResultFuture = completeValueInfos.stream().map(FieldValueInfo::getFieldValue).collect(Collectors.toList());
        executionStrategyCtx.onFieldValuesInfo(completeValueInfos);
        Async.each(executionResultFuture).whenComplete(handleResultsConsumer);
    }).exceptionally((ex) -> {
        // if there are any issues with combining/handling the field results,
        // complete the future at all costs and bubble up any thrown exception so
        // the execution does not hang.
        overallResult.completeExceptionally(ex);
        return null;
    });
    overallResult.whenComplete(executionStrategyCtx::onCompleted);
    return overallResult;
}

protected CompletableFuture<FieldValueInfo> resolveFieldWithInfo(ExecutionContext executionContext, ExecutionStrategyParameters parameters) {
    GraphQLFieldDefinition fieldDef = getFieldDef(executionContext, parameters, parameters.getField().get(0));
    Instrumentation instrumentation = executionContext.getInstrumentation();
    InstrumentationContext<ExecutionResult> fieldCtx = instrumentation.beginField(
            new InstrumentationFieldParameters(executionContext, fieldDef, createExecutionStepInfo(executionContext, parameters, fieldDef))
    );
    CompletableFuture<Object> fetchFieldFuture = fetchField(executionContext, parameters);
    CompletableFuture<FieldValueInfo> result = fetchFieldFuture.thenApply((fetchedValue) ->
            completeField(executionContext, parameters, fetchedValue));
    CompletableFuture<ExecutionResult> executionResultFuture = result.thenCompose(FieldValueInfo::getFieldValue);
    fieldCtx.onDispatched(executionResultFuture);
    executionResultFuture.whenComplete(fieldCtx::onCompleted);
    return result;
}

protected CompletableFuture<Object> fetchField(ExecutionContext executionContext, ExecutionStrategyParameters parameters) {
    Field field = parameters.getField().get(0);
    GraphQLObjectType parentType = (GraphQLObjectType) parameters.getExecutionStepInfo().getUnwrappedNonNullType();
    GraphQLFieldDefinition fieldDef = getFieldDef(executionContext.getGraphQLSchema(), parentType, field);
    GraphqlFieldVisibility fieldVisibility = executionContext.getGraphQLSchema().getFieldVisibility();
    Map<String, Object> argumentValues = valuesResolver.getArgumentValues(fieldVisibility, fieldDef.getArguments(), field.getArguments(), executionContext.getVariables());
    GraphQLOutputType fieldType = fieldDef.getType();
    DataFetchingFieldSelectionSet fieldCollector = DataFetchingFieldSelectionSetImpl.newCollector(executionContext, fieldType, parameters.getField());
    // ...
    CompletableFuture<Object> fetchedValue;
    // 获得dataFetcher，这里为HelloWorld的`new StaticDataFetcher("world")`
    DataFetcher dataFetcher = fieldDef.getDataFetcher();
    dataFetcher = instrumentation.instrumentDataFetcher(dataFetcher, instrumentationFieldFetchParams);
    ExecutionId executionId = executionContext.getExecutionId();
    try {
        log.debug("'{}' fetching field '{}' using data fetcher '{}'...", executionId, executionStepInfo.getPath(), dataFetcher.getClass().getName());
        // 执行dataFetcher获取值，enviroment为上下文环境包含参数
        Object fetchedValueRaw = dataFetcher.get(environment);
        log.debug("'{}' field '{}' fetch returned '{}'", executionId, executionStepInfo.getPath(), fetchedValueRaw == null ? "null" : fetchedValueRaw.getClass().getName());
        // 如果是具体值就返回已经有值的CompletableFuture,如果是CompletionStage就直接返回
        fetchedValue = Async.toCompletableFuture(fetchedValueRaw);
    } catch (Exception e) {
        log.debug(String.format("'%s', field '%s' fetch threw exception", executionId, executionStepInfo.getPath()), e);
        fetchedValue = new CompletableFuture<>();
        fetchedValue.completeExceptionally(e);
    }
    fetchCtx.onDispatched(fetchedValue);
    // 对结果的后续处理
    return fetchedValue
            .handle((result, exception) -> {
                fetchCtx.onCompleted(result, exception);
                if (exception != null) {
                    handleFetchingException(executionContext, parameters, field, fieldDef, argumentValues, environment, exception);
                    return null;
                } else {
                    return result;
                }
            })
            .thenApply(result -> unboxPossibleDataFetcherResult(executionContext, parameters, result))
            .thenApply(this::unboxPossibleOptional);
}