GraphQl学习文档

Nav Inc.已经创建了一个开源模式定义和代码生成器，它使用GraphQL语法来定义事件和消息格式。选择GraphQL是因为它的表达能力和对开发人员的熟悉程度;Nav模式体系结构(NSA)不使用GraphQL runtime。

GraphQL 既是一种用于 API 的查询语言也是一个满足你数据查询的运行时。GraphQL 对你的 API 中的数据提供了一套易于理解的完整描述，使得客户端能够准确地获得它需要的数据，而且没有任何冗余，也让 API 更容易地随着时间推移而演进，还能用于构建强大的开发者工具。

使用GraphQL可以同时表达数据模型Schema和携带该数据模型实体的消息格式，不需要分别定义。

NSA的主要目的是生成多种语言的代码和模式，都是基于使用GraphQL的根定义。输出可以是其他模式语言，比如protobuf或JSON schema，也可以是当前支持Go、Ruby和Python的代码。

公共数据模型的好处在于能够轻松地在多个团队和服务之间传播其实现。构建管道将监视特性分支上的模式更改，并启动第二个管道来生成所有目标语言的输出。将输出提交回特性分支，开发人员可以在合并到主分支之前检查更改。

InfoQ和Nav的谈话

InfoQ会见了Nav项目的一些开发人员，以便更好地理解他们试图解决的问题以及他们从这种方法中看到的好处。

InfoQ:契约优先的开发并不是一个新想法，但是我们会更经常地看到OpenAPI和JSON Schema被用来定义契约。是什么促使您决定使用GraphQL语法作为契约的主要真实性来源，然后从中派生契约?

Nav开发团队:我们决定使用GraphQL有几个原因。GraphQL与OpenAPI和JSONSchema等其他系统的区别在于，GraphQL包含了定义公共数据模型和消息模式的方法，这是同一个问题。一个有效的系统必须允许一种简单的方法来定义两者。GraphQL是一种有效负载描述语言，它解决了在单一领域特定语言中使用验证规则和消息模式定义有效负载的问题。该语言包括一个基于graphql的类型系统，就像任何接口定义语言一样。这个类型系统支持标量、对象、枚举以及这些类型值的基本验证。我们使用这个类型系统来定义有效载荷和自定义验证规则(例如数据格式、允许值范围、正则表达式匹配和必需属性)。消息契约只是基于有效负载类型的消息模式定义。定义消息契约时，可以根据有效负载类型选择在消息契约中包含哪些字段。

另一个原因是，GraphQL语法是人类可读的，与JSON Schema相比，使用起来更简单。这促进了团队之间的沟通。

我们使用NSA从单个GraphQL公共信息模型中生成特定于语言的消息结构，以及JSON和Protobuf模式。因此，除了代码生成之外，NSA还被用于将GraphQL转换为JSON/Protobuf模式。

InfoQ:你的系统架构主要使用异步消息传递还是请求-响应?NSA适用于这两种方法吗?

Nav开发团队：NSA也可以很容易地在请求/响应系统中使用。与AWS Eventbridge和SQS一样，NSA输出结构可以与JSON或任何其他结构化数据格式序列化。实际上，NSA的一个输出目标是谷歌的Protocol Buffers。

NSA将重点放在验证上，与端点管理分离。在NSA中没有对端点、订阅者或发布者的引用。来自NSA的输出代码可以被任何自己管理传输方法的适配器使用。

InfoQ:你还考虑过其他什么设计，你怎么认为这是最好的方法?具体来说，你是否考虑过使用OpenAPI/AsyncAPI或protobuf作为代码生成的语法?

Nav开发团队:在我们当前的体系结构中，不需要使用冗余的异步工具，如AsyncAPI。

AsyncAPI可以有任何消息有效负载，因此NSA生成的输出可以用作AsyncAPI消息模式。我们间接使用Protobuf消息定义作为NSA的输出目标。

AsyncAPI尝试与AWS EventBridge一起处理不必要的传输。此外，将验证与传输逻辑耦合在一起将使我们的系统更加复杂，保持关注点的分离使开发更加容易。

InfoQ:GraphQL模式是存储在单独的repos中，还是存储在生产者或消费者中?

Nav开发团队:GraphQL模式当前存储在与处理器和随后生成的代码相同的存储库中。因为生成的代码本身只涉及到消息验证，所以它被Nav中的许多库和应用程序用作依赖项(无论是生产者、消费者还是一个简单的文档工具)

虽然我们的项目以monorepo形式存在，但情况不一定如此。可以根据职责将项目划分为多个repos，一个或多个repos可以包含GraphQL及其类型扩展，这些类型扩展最终合并为一个模式，作为解析器输入。另一个repo可以容纳解析器本身，它可以作为子模块连接一个或多个代码生成repo。repos的第四层可以包含生成的代码，每种语言一个repos，以及所有必要的验证、测试和打包逻辑。最后，这些不包含传输机制逻辑的包可以被客户端库使用。

更多内容请查看该链接：www.infoq.com/news/2022/0…

原文链接：GraphQL语法用于模式验证和代码生成的新方法 - 掘金 (juejin.cn)