1.1类型定义→Type Definition

创建类型是一切的起点，GraphQL 支持如下的类型

• Scalar
  • ID
  • String
  • Float
  • Int
  • Boolean
• Object
• InputObject
• Enum
• Union

2.1图的上下文

在GraphQL 中，一切都是 Graph。 许多领域都会有关联，比如一个 Customer领域 拥有 Metafield 的知识，尽管他们之前的关联非常弱。 现在在同一个graph中，他们可以互相传递自己的知识。

这意味着，我们在设计 GraphQL 的时候，考虑的 每一个领域都不再是一个单独的 领域实体 ，应当将领域 理解成为 聚合根。每一个聚合根都可能关联其他聚合根。 聚合根的边界 用来划分不同的团队。每个域的团队都应该慎重的考虑业务模型，基于聚合根的边界来决定对于其他领域的依赖。 比如 Customer 不会依赖 Online Store 的对象。 因为，Customer 的聚合根应当聚合 从customer视角出发观察到的边。 相反的，Online Store 却可以包含 Customer。

在构建图的时候，需要团队协作。

举个例子，比如 User 和 Order往往是两个团队，他们处于两个不同的 领域聚合根下，但是，在一个 用户订单图中，他们是需要合作的，因此顶层设计者需要先设计出 基于当前图的新的领域对象， 如 UserOrderGraph, 在当前图下，会产生新的领域聚合根，如 UserOrderObject, User 团队 和 Order 团队共享 UserOrderObject。 他们各自提供一部分能力，但是在设计上不能表达出这种差异。 使用者感知到的是 UserOrderObject 对象，他们在开发的时候思维会自动进入到 UserOrderObject上下文。 在这个上下文中 UserOrder的每个字段都是平等的，就像是一个领域对象一样。

因此，如果以现有的 领域模型来构建图 是不合理的。 应当自上而下的重新设计。 任何两个领域的对象都可能会融合在一起，只要给定一个合理的上下文。也就是GraphQL 上下文。

2.2场景

为了确定图的上下文，需要引入一个管理员角色，叫图之管理员, 这个角色用来确保 一张图里面要包含 什么。

一张图里包含了该图的 领域知识,这些领域知识 并非由于 图的数据支撑者来决定的。而是基于 图本身来确定的。

因此，可以借DDD来思考，在图的上下文里，领域又是什么？

思考这个问题不仅仅需要 图之管理者，还需要 场景支撑者，场景支撑者 是 领域 的子集。 比如 有10 领域团队， 场景支撑着可能是其中的7个。

可以按照如下的步骤进行筛选：

1. 头脑风暴，沿着场景，模拟行为
2. 行为产生事件，将事件汇总成表
3. 筛选领域团队 明确事件表，进行场景补充

3.1聚合根

GraphQL 仍旧可以按照 DDD 来设计，一个聚合根可以是一个 Query对象，也可以是任何 Type。

聚合根是数据的提供者，即任何的领域实体/值对象 都不能绑定字段解析函数。所有的函数必须收敛到聚合根里。

在GraphQL中，所有Query/Mutation/Subscription 都是根， 他代表的用户的访问入口。

他们的字段（Field) 每一个字段的类型代表了一个聚合根。

比如定义

type Query{
  card(id:String!):Card!

}

任何一个Type 都可以是一个聚合根。聚合根的每一个字段都可以设置一个字段Resolver。

当一个 Type 是聚合根的时候，它可以extend 任意领域的能力。 比如 User 是一个聚合根，则可以扩展 BTC领域的 userBtcAddress.

extend User{
  userBtcAddress:BTCAddressCtxAddress!
}

3.2领域实体

领域实体 代表一种 Pure Busioness Model(纯业务模型)，领域实体本身不包含图的行为(不绑定函数)，除此之外，跟DDD中的领域实体一样。 领域实体明确了当前需要返回的领域模型， 它的领域聚合根负责通过 Resolver函数将数据映射到 模型之上。

领域实体是基于图的，在很多时候，图的场景的支撑域的领域知识可以迁移到图的上下文。但是并不是完全一致，可以是一个子集。

任何领域实体都应该可以被安全的被其他聚合跟依赖。

3.3值对象

值对象 是一些公共的对象和枚举。 如 PageInfo和 Money对象，值对象本身绝对不能绑定Resolver. 值对象必须是无状态的。

4.1Connection

Connection用作分页类型，当一个query 需要分页的时候，必须返回一个Connection。 Connection有如下规约:

1. Connection 必须是一个 Object
2. Connection 命名必须是 {$Domain}Connection 如 UserConnection
3. Connection 对象必须包含 两个字段 edges,pageInfo
4. Node Node 仅仅包含一个字段 id:ID!
5. Edge 所有的Edge 都需要实现Node

{
  "data": {
    "__type": {
      "fields": [
        // May contain other items
        {
          "name": "pageInfo",
          "type": {
            "name": null,
            "kind": "NON_NULL",
            "ofType": {
              "name": "PageInfo",
              "kind": "OBJECT"
            }
          }
        },
        {
          "name": "edges",
          "type": {
            "name": null,
            "kind": "LIST",
            "ofType": {
              "name": "ExampleEdge",
              "kind": "OBJECT"
            }
          }
        }
      ]
    }
  }
}

4.2分页增强

5.1权限的校验

权限的检验应当发生在验证阶段,在执行字段解析函数之前，就应当检查字段的权限。

6.1版本的名称

版本的命名 可以按照时间 的递增序列，如 20220101 ,20220501.递增的版本序列传递了当前版本的迭代周期。有利于开发者在引入版本的时候做决策。

版本的命名 还可以增加自定义的一些属性，用来标识当前版本的某个状态，比如 2022-01-01-BETA。这些描述是可选的。但是，在一个产品里面的版本序列的命名规范是统一的。

6.2版本递增约束

不稳定版本 随着时间的推移和沉淀，会变得稳定，因为他首选成为一个候选版本。 候选版本会变成稳定版本。 稳定版本应该维护一个时间序列的链。 当一个版本变成稳定版本的时候，就要考虑移除掉稳定版本链末端的版本。 控制稳定版本的数量，否则它会越来越庞大。

6.3兼容性

在graphql中，任何一个字段都可以被很轻易的添加在 graph中，当非常难以移除。当一个字段开放出去，要移除这个字段就需要漫长的等待。

7.1Http

7.2业务错误

{
  "errors": [
    {
      "message": "Name for character with ID 1002 could not be fetched.",
      "locations": [ { "line": 6, "column": 7 } ],
      "path": [ "hero", "heroFriends", 1, "name" ],
      "extensions": {
        "code": "CAN_NOT_FETCH_BY_ID",
        "timestamp": "Fri Feb 9 14:33:09 UTC 2018"
      }
    }
  ]
}

8.1Time-based 算法

8.2Scope 算法

每一个对象都有不同的scope,比如 查询一个object 需要花费 1,查询一个分页，返回10个对象，则应该是 1+10 通过设置一个全局最大值，来限制用户的查询和保护系统资源。

下面是一张推荐的表，对于每一种类型的对象成本做了预估。

9.1自省

graphQL 可自省. 这意味着，可以通过graphql 的查询语法来观察自身的结构，包括：字段定义、描述、类型 因此，通过自省指令可以观察schema本身的结构。

比如如下的查询，可以观察到 TypeName 的 kind 信息

{
  __type(name: "TypeName") {
    name
    kind
  }
}

9.2graphiQL

GraphiQL 是一个in-web 的工具，我们可以通过一个endpoint，通过自省就能看到文档。它非常有效，可以发起请求。 因此强烈推荐在开发过程中使用 graphiql 来进行测试。 它也可以部署在外部，当需要将graphql api 开放出去的时候，最好提供一个graphiql。

9.3文档多语言

有些应用需要提供多语言版本的文档.

10.1ID

ID 可以在一个 endpoint 中代表唯一的资源。客户端可以用来做缓存。 有如下两种简单的方式来构建ID

10.2node & nodes

node 可以作为一种最佳实践，用来表达一系列资源的公共抽象。尤其是当子域非常多的时候，我们不可能为每一个子域名都构建一个查询。 因此，可以考虑使用node来构建 graphQL 的核心资源查询能力

interface Node{
    id:ID!
}

{
  node(id:"$productId"){
 	... on Product {
    id
  }   
  }
}

{
  node(id:"$cartId"){
 	... on Cart {
    id
  }   
  }
}

10.3自定义Scalar

Scalar是基本类型，自定义Scalar的时候必须非常小心，切勿包含业务含义。

判断一个类型是否可以被定义成Scalar的要素如下

1. 如果这个Scalar脱离当前graph仍旧有含义，则可以定义，如 JSON HTML
2. 如果这个Scalar在当前graphq中可以被共享且没有ID，则可以定义， 如 Money
3. 这个值本身可以被非JSON的 简单字面量表达

除此之外，不应该将其定义成为Scalar