翻译 RST(reStructuredText) 和转换为 MD(Markdown)

准备

安装 restbuilder

https://pythonhosted.org/sphinxcontrib-restbuilder/

安装 pandoc

https://pandoc.org/installing.html

操作

  1. 生成 rst 文件:
    make -e SPHINXOPTS="-D language='zh_CN'" rst

  2. 转换 rst 到 md 文件

#!/usr/bin/env bash

export pandoc="pandoc +RTS -V0 -RTS"

cd _build/rst 
FILES="*.rst"
for f in $FILES
do
  filename="${f%.*}"
  echo "Converting '$f' to '$filename.md'"
  $pandoc "$f" -f rst -t markdown -o "$filename.md"
done

graphql-java: 使用文档首页

欢迎使用 graphql-java

这是一个用Java实现的GraphQL。基于 GraphQL规范JavaScript参考实现.

Status: Version 6.0 is released.

强烈推荐你关注一下 基于 graphql-java 开发的 相关项目 .

贡献或编码的行为规范

请注意,这个项目的发行条款,包括了 `贡献或编码的行为规范 <https://github.com/graphql-java/graphql-java/blob/master/CODE_OF_CONDUCT.md>`_为本项目作贡献(提交代码和问题等【译注原文:commenting or opening PR/Issues etc】)的同时,你即同意遵守这个行为规范,所以请你花时间认真阅读它.

问题与讨论

如果你有问题或想讨论与本项目相关的事:

发行授权

graphql-java is licensed under the MIT License.

文档

 

英文原文:https://github.com/graphql-java/graphql-java

翻译:GraphQL中文网 http://blog.mygraphql.com

graphql-java:贡献

贡献

所有的贡献都是欢迎的。谢谢!

为了让大家快乐贡献,以下是一些提示:

  • Respect the [Code of Conduct](#code-of-conduct)
  • Before opening an Issue to report a bug, please try the latest development version. It can happen that the problem is already solved.
  • Please use Markdown to format your comments properly. If you are not familiar with that: Getting started with writing and formatting on GitHub
  • For Pull Requests:
    * Here are some general tips

    • Please be a as focused and clear as possible and don’t mix concerns. This includes refactorings mixed with bug-fixes/features, see [Open Source Contribution Etiquette](http://tirania.org/blog/archive/2010/Dec-31.html)
    • It would be good to add a automatic test. All tests are written in Spock.

本地构建和测试

Just clone the repo and type

./gradlew build

In build/libs you will find the jar file.

Running the tests:

./gradlew test

Installing in the local Maven repository:

./gradlew install

graphql-java:如何落地应用(Application concerns)

如何落地应用(Application concerns)

graphql-java 引擎主要的关注点是按 GraphQL 规范来执行查询。

它本身不关注应用的其它方面,如:

  • 数据库访问
  • 缓存数据
  • 数据权限控制
  • 数据分页
  • HTTP 转换
  • JSON 编码
  • 依赖注入的编程方法

你需要在自己的业务逻辑层中实现这些。

下面是一些相关方案的介绍:

上下文对象(Context Objects)

为更方便的业务调用,你可以在查询执行中加入Context Object。

例如,你的应用的边界模块可能会做用户识别,然后 GraphQL 查询执行时,你可以想做数据权限控制。

下面例子演示怎么向你的查询传递信息:

//
// this could be code that authorises the user in some way and sets up enough context
// that can be used later inside data fetchers allowing them
// to do their job
//
UserContext contextForUser = YourGraphqlContextBuilder.getContextForUser(getCurrentUser());

ExecutionInput executionInput = ExecutionInput.newExecutionInput()
        .context(contextForUser)
        .build();

ExecutionResult executionResult = graphQL.execute(executionInput);

// ...
//
// later you are able to use this context object when a data fetcher is invoked
//

DataFetcher dataFetcher = new DataFetcher() {
    @Override
    public Object get(DataFetchingEnvironment environment) {
        UserContext userCtx = environment.getContext();
        Long businessObjId = environment.getArgument("businessObjId");

        return invokeBusinessLayerMethod(userCtx, businessObjId);
    }
};

graphql-java:关于 Relay 支持

关于 Relay 支持

包含了一些基础的 Relay 特性的支持。

注意: 这里的 Relay 指 “Relay Classic”, 暂不支持 “Relay Modern”.

完整的例子,见 https://github.com/graphql-java/todomvc-relay-java

Relay 以 JSON 格式,向服务器发送 queryvariables 两个字段。query 字段是一个 JSON 格式的字符串, variables 字段是一个 变量定义( variable definitions) 的 map。relay 兼容的服务器,需要解释 JSON 然后传 query 字符串到本框架。包括 variables map 作为 execute 方法的第3个参数。如下:

@RequestMapping(value = "/graphql", method = RequestMethod.POST, produces = MediaType.APPLICATION_JSON_VALUE)
@ResponseBody
public Object executeOperation(@RequestBody Map body) {
    String query = (String) body.get("query");
    Map<String, Object> variables = (Map<String, Object>) body.get("variables");
    if (variables == null) {
        variables = new LinkedHashMap<>();
    }
    ExecutionResult executionResult = graphql.execute(query, (Object) null, variables);
    Map<String, Object> result = new LinkedHashMap<>();
    if (executionResult.getErrors().size() > 0) {
        result.put("errors", executionResult.getErrors());
        log.error("Errors: {}", executionResult.getErrors());
    }
    result.put("data", executionResult.getData());
    return result;
}

Apollo 支持

没有为对接 Apollo 客户端做什么。因它兼容所有schema。

上面的 Controller 例子一样可以与 Apollo 客户端交互。

graphql-java:拦截器Instrumentation

拦截器Instrumentation

通过实现 graphql.execution.instrumentation.Instrumentation 接口,你可以在执行查询的过程中注入定制代码。并可以修改运行期的行为。

它的主要用途是性能监控和定制日志,但也可以完成其它任务。

当创建 `Graphql 对象时,可以绑定相关的 Instrumentation

GraphQL.newGraphQL(schema)
        .instrumentation(new TracingInstrumentation())
        .build();

定制拦截器(Custom Instrumentation)

要实现 Instrumentation ,需要实现多个 “begin” 开头的方法。这方法会在查询执行过程中,每一步骤开始前被调用。

所有回调方法,都应该返回 graphql.execution.instrumentation.InstrumentationContext 对象,这个对象会在本步骤完成时被回调用,回调用时会告知数据的获取结果,如果出错,可以获取 Throwable 对象。.

下面是一个定制的 Instrumentation 。作用是测量执行时间。

class CustomInstrumentationState implements InstrumentationState {
    private Map<String, Object> anyStateYouLike = new HashMap<>();

    void recordTiming(String key, long time) {
        anyStateYouLike.put(key, time);
    }
}

class CustomInstrumentation implements Instrumentation {
    @Override
    public InstrumentationState createState() {
        //
        // instrumentation state is passed during each invocation of an Instrumentation method
        // and allows you to put stateful data away and reference it during the query execution
        //
        return new CustomInstrumentationState();
    }

    @Override
    public InstrumentationContext<ExecutionResult> beginExecution(InstrumentationExecutionParameters parameters) {
        long startNanos = System.nanoTime();
        return (result, throwable) -> {

            CustomInstrumentationState state = parameters.getInstrumentationState();
            state.recordTiming(parameters.getQuery(), System.nanoTime() - startNanos);
        };
    }

    @Override
    public InstrumentationContext<Document> beginParse(InstrumentationExecutionParameters parameters) {
        //
        // You MUST return a non null object but it does not have to do anything and hence
        // you use this class to return a no-op object
        //
        return new NoOpInstrumentation.NoOpInstrumentationContext<>();
    }

    @Override
    public InstrumentationContext<List<ValidationError>> beginValidation(InstrumentationValidationParameters parameters) {
        return new NoOpInstrumentation.NoOpInstrumentationContext<>();
    }

    @Override
    public InstrumentationContext<ExecutionResult> beginDataFetch(InstrumentationDataFetchParameters parameters) {
        return new NoOpInstrumentation.NoOpInstrumentationContext<>();
    }

    @Override
    public InstrumentationContext<CompletableFuture<ExecutionResult>> beginExecutionStrategy(InstrumentationExecutionStrategyParameters parameters) {
        return new NoOpInstrumentation.NoOpInstrumentationContext<>();
    }

    @Override
    public InstrumentationContext<ExecutionResult> beginField(InstrumentationFieldParameters parameters) {
        return new NoOpInstrumentation.NoOpInstrumentationContext<>();
    }

    @Override
    public InstrumentationContext<Object> beginFieldFetch(InstrumentationFieldFetchParameters parameters) {
        return new NoOpInstrumentation.NoOpInstrumentationContext<>();
    }

    @Override
    public DataFetcher<?> instrumentDataFetcher(DataFetcher<?> dataFetcher, InstrumentationFieldFetchParameters parameters) {
        //
        // this allows you to intercept the data fetcher used ot fetch a field and provide another one, perhaps
        // that enforces certain behaviours or has certain side effects on the data
        //
        return dataFetcher;
    }

    @Override
    public CompletableFuture<ExecutionResult> instrumentExecutionResult(ExecutionResult executionResult, InstrumentationExecutionParameters parameters) {
        //
        // this allows you to instrument the execution result some how.  For example the Tracing support uses this to put
        // the `extensions` map of data in place
        //
        return CompletableFuture.completedFuture(executionResult);
    }
}

链式拦截(Chaining Instrumentation)

你可以用 graphql.execution.instrumentation.ChainedInstrumentation 把多个 Instrumentation 连接起来。这些 Instrumentation 对象会按顺序被调用。

List<Instrumentation> chainedList = new ArrayList<>();
chainedList.add(new FooInstrumentation());
chainedList.add(new BarInstrumentation());
ChainedInstrumentation chainedInstrumentation = new ChainedInstrumentation(chainedList);

GraphQL.newGraphQL(schema)
        .instrumentation(chainedInstrumentation)
        .build();

Apollo跟踪与拦截( Tracing Instrumentation)

graphql.execution.instrumentation.tracing.TracingInstrumentation 是一个可以收集跟踪信息的拦截器。

它按照 Apollo 跟踪格式 https://github.com/apollographql/apollo-tracing 来收集跟踪信息。

详细的跟踪信息( tracing map)会放在查询结果的 extensions(扩展) 部分。

如以下的查询:

query {
  hero {
    name
    friends {
      name
    }
  }
}

会返回如下的结果:

{
  "data": {
    "hero": {
      "name": "R2-D2",
      "friends": [
        {
          "name": "Luke Skywalker"
        },
        {
          "name": "Han Solo"
        },
        {
          "name": "Leia Organa"
        }
      ]
    }
  },
  "extensions": {
    "tracing": {
      "version": 1,
      "startTime": "2017-08-14T23:13:39.362Z",
      "endTime": "2017-08-14T23:13:39.497Z",
      "duration": 135589186,
      "execution": {
        "resolvers": [
          {
            "path": [
              "hero"
            ],
            "parentType": "Query",
            "returnType": "Character",
            "fieldName": "hero",
            "startOffset": 105697585,
            "duration": 79111240
          },
          {
            "path": [
              "hero",
              "name"
            ],
            "parentType": "Droid",
            "returnType": "String",
            "fieldName": "name",
            "startOffset": 125010028,
            "duration": 20213
          },
          {
            "path": [
              "hero",
              "friends"
            ],
            "parentType": "Droid",
            "returnType": "[Character]",
            "fieldName": "friends",
            "startOffset": 133352819,
            "duration": 7927560
          },
          {
            "path": [
              "hero",
              "friends",
              0,
              "name"
            ],
            "parentType": "Human",
            "returnType": "String",
            "fieldName": "name",
            "startOffset": 134105887,
            "duration": 6783
          },
          {
            "path": [
              "hero",
              "friends",
              1,
              "name"
            ],
            "parentType": "Human",
            "returnType": "String",
            "fieldName": "name",
            "startOffset": 134725922,
            "duration": 7016
          },
          {
            "path": [
              "hero",
              "friends",
              2,
              "name"
            ],
            "parentType": "Human",
            "returnType": "String",
            "fieldName": "name",
            "startOffset": 134875089,
            "duration": 6342
          }
        ]
      }
    }
  }
}

字段校验拦截器(Field Validation Instrumentation)

graphql.execution.instrumentation.fieldvalidation.FieldValidationInstrumentation 拦截器,可以在执行查询前校验字段和字段参数。如果校验失败,查询将停止,并返回错误信息。

你可以编写自己的``FieldValidation`` 实现,或者直接用 SimpleFieldValidation 去为每个field定义校验逻辑。

ExecutionPath fieldPath = ExecutionPath.parse("/user");
FieldValidation fieldValidation = new SimpleFieldValidation()
        .addRule(fieldPath, new BiFunction<FieldAndArguments, FieldValidationEnvironment, Optional<GraphQLError>>() {
            @Override
            public Optional<GraphQLError> apply(FieldAndArguments fieldAndArguments, FieldValidationEnvironment environment) {
                String nameArg = fieldAndArguments.getFieldArgument("name");
                if (nameArg.length() > 255) {
                    return Optional.of(environment.mkError("Invalid user name", fieldAndArguments));
                }
                return Optional.empty();
            }
        });

FieldValidationInstrumentation instrumentation = new FieldValidationInstrumentation(
        fieldValidation
);

GraphQL.newGraphQL(schema)
        .instrumentation(instrumentation)
        .build();