symphonyql/symphonyql

SymphonyQL is a GraphQL implementation built with Apache Pekko

SymphonyQL

A GraphQL implementation built with Apache Pekko.

Documentation

SymphonyQL homepage

Highlights

• support for Java 21: record classes, sealed interface.
• minimal dependencies, no adapter required.
• native support for Apache Pekko, including Java and Scala.
• minimal amount of boilerplate: no need to manually define a schema for every type in your API.

Quickstart

Quickstart Java

Quickstart Scala

Inspire By

1. caliban
2. graphql-java

The design of this library references caliban and graphql-java, and a large number of ADTs and Utils have been copied from caliban.

symphonyql's Issues

执行计划的自动Trace

参考ZIO Trace

scheme分析计划(Stage)实现

生成一个 PreparedQuery/Mutation/Stream
基于pekko-stream

需实现一个简单的验证器

• 生成已完成。还需测试和优化。

用于执行的Query解析器

`Schema`和`ArgumentExtractor`自动生成

• Scala 3 Schema 自动生成
• Scala 3 ArgumentExtractor 自动生成
• Java Schema 自动生成
• Java ArgumentExtractor 自动生成

由于我们的目标是Code First，应该尽可能自动生成。

• ArgumentExtractor 用于从AST解析请求参数，若请求参数是已知POJO，ArgumentExtractor 是确定的
• Schema是描述 GraphQL 接口的结构，若接口输入输出的类型是已知POJO，Schema 也是确定的
  因此可以自动生成。Java 通过注解、Scala通过宏或者Compiler插件、sbt插件代码生成实现

Meta issue: A quick design for the first release.

Note: For now, I will type it in Chinese.

核心目标

1. Java first，Pekko-Stream first， Scala first
2. 在第一版本中，交付核心的功能（比如query）。其他超集功能，以后再考虑。
3. Java first 中的注解支持、Scala first 中的宏支持，在上层模块中交付。

核心设计

要点

1. 支持 query、mutation；stream 和 defer 功能可以后续交付
2. 因为是 Java first，所以核心的模型层要支持最后 手动builder，参考 graphql-java 这样的简单实现
3. 序列化使用 pekko 自带的jackson就好了
4. 模型全部使用 pekko strema 的Source、Flow， 查询相当于是 Run the graph， 方便最后也支持 stream 和 defer。
5. 建议实现为基于预先分析的解释器，可以简化部分。

核心模块

1. parser; 这个使用pekko-http 的依赖 parboiled2，可以单独一个module，方便以后别个只用这个parser
2. 抽象一个 resolver，比如 MethodResolver, FieldResolver， resolver 的签名为 ctx, params => Source[T]
3. 抽象一个 action，比如 DBWriteAction之类的，mutation才需要，可以理解为 ctx, params => Flow[T, R, Effect]
4. schema 的定义参考官方的rfc 即可，scala 的 case class。支持值的转换，用户可能乱写。
5. anaylyzer 分析器，结合ctx 和 query对象，生成一个 preparedQuery/Mutation/Stream, 相当于RunnableGraph
6. 分析的过程中，埋入 trace，可以参考 zio的方式通过 using trace:Trace 搞
7. interpretor 解释器， 直接解释执行 preparedQuery/Mutation/Stream，相当于 RunnableGraph.run
8. object Symphony {} 是我们的入口类
9. web-console, 基于 pekko-http 提供embed console，可以直接访问和测试。
10. 在上面提供 javadsl、scaladsl。后续java 的外围搞基于 Spring 的，类似 Graphql-Spring， 支持基于注解来搞schema，或者手写。scala 的搞成宏或者手写。
11. 参考haxl， 在分析器下点功夫，解决 N+1 的问题

以后卷的方向

0. schema，从各种地方构建编排schema
1. 分析器，极致优化
2. 解释器，可以搞asm、bytebuddy之类的，越快越好。
3. resolver，外部扩展，比如提供 sql、http、grpc resolver
4. action ， 执行到db之类的
5. 自动的客户端~~

其他的：暂时就这么多吧，很累的。

实现一个默认的pekko-http集成

目标：对于pekko用户，开箱即用。

尝试支持Flow Schema

现在仅仅支持function，supplier的返回是Source的场景，其输入要么是对象要么是空。看看能不能实现Flow，输入输出都有了。

验证器Validator实现

模块 symphony-validator，依赖parser，参考Caliban

支持获取index用于错误提示

解析时push index，返回 final case class LocationInfo(column: Int, line: Int)

合并字段预处理，pekko-streams异常捕获

均需要参考caliban

1. 现有字段合并是在reduce阶段完成，性能较差。
2. 现有stage没有捕获执行异常

由于Field上缺少index，执行异常不提供LocationInfo。

提供插件`sbt-symphonyql`，默认引入依赖+开启Java apt功能

基于pekko-http实现Console

待定

集成pekko-grpc，支持提供 grpc endpoint

支持从grpc 提交请求

基于parboiled2实现AST解析

参考Caliban和Pekko-http

• #11
• #12
• #13

切面/拦截器实现

定义trait SymphonyQLAspect，，允许通过SymphonyQL.addAspect方式加入拦截。
拦截类型：
解析器，验证器，全局(执行响应)，每个字段，自省查询

按需，暂定仅实现全局拦截。

考虑与解释器issue一起实现。

支持脚本管理

graphql script 支持存储在 DB 中：

scriptName, version, env 作为联合组件，支持灰度、回滚；支持脚本预编译。

查询可以变为 execute(param:ScriptParam)

解释器Interpretor实现

对Executor进行封装，增加指令，自省，验证等，完善流程。

• 自省
• 验证
• 指令
• 全局切面

支持指令

• 增加scala注解用于在类型上声明指令
  • 修改scala derivation支持生成带指令的schema定义
• 增加java注解用于在类型上声明指令
  • 修改Java apt支持生成带指令的schema定义
• 修改执行器处理

用于验证的Type解析器

参考caliban、graphql-java

External Annotations

一些建议，除了常见的 annotations, 如 #18 外：

name	description
@MountAt	@MountAt("./family") 这样可以用来重新组织结构
@GQLResolver	提供一个resolver，用于获取值
@GQLNullable	允许java字段为空，默认非空，除非使用Optional
@GQLIdentity	N+1 批量的时候需要，标记是无状态的，可以跨请求合并
@GQLField	标识为GraphQL Field
@GQLExport	自动导出一个类的所有get方法
@CoEval	标识可以直接求值
@BatchedAlia	标识对应的批量方法，N+1用
@MaxParallelism	N+1并行度
@MaxBatchedParallelism	N+1批量并行度
@MaxBatchSize	N+1归组大小