😶‍🌫️ 用 GraphQL 查询你的 Django 应用

什么是 GraphQL ？

GraphQL 是一个开源的，面向 API 而创造出来的数据查询操作语言以及相应的服务端运行环境。

它有什么有意思的特性

Fragments

query HeroComparison($first: Int = 3) {
  leftComparison: hero(episode: EMPIRE) {
    ...comparisonFields
  }
  rightComparison: hero(episode: JEDI) {
    ...comparisonFields
  }
}

fragment comparisonFields on Character {
  name
  friendsConnection(first: $first) {
    totalCount
    edges {
      node {
        name
      }
    }
  }
}

Directives

query Hero($episode: Episode, $withFriends: Boolean!) {
  hero(episode: $episode) {
    name
    friends @include(if: $withFriends) {
      name
    }
  }
}

# variables
{
  "episode": "JEDI",
  "withFriends": false
}

• @include(if: Boolean)

• @skip(if: Boolean)

和 REST 相比较有什么优势和劣势？

TLDR

vs 扩展的 REST 协议

from rest_framework import serializers

class CommentSerializer(serializers.Serializer):
    email = serializers.EmailField()
    content = serializers.CharField(max_length=200)
    logo = serializer.ImageField()
    ...(省略数不清的字段)
    created = serializers.DateTimeField()
    ip_from = serializers.IPAddressField()

# 查询 comment，并限制结果返回字段
/api/comments?fields=email,content

# 返回
{
  "results": [
    {
      "email": "foo@bar.com",
      "content": "I love this blog, simple and good looking.",
    }
  ]
}

query {
  comment {
    email
    content
  }
}

# 查询 users，并限制结果返回字段
/api/users?with_comments=1

# 返回
{
  "results": [
    {
      "username": "foo",
      "telephone": "12345",
      "comments": [
        {
          "email": "foo@bar.com",
          "content": "I love this blog, simple and good looking.",
        }
      ]
    }
  ]
}

• 不够通用，用户有额外的学习成本，增加了额外的文档负担。

• 基于 REST ，单个请求只能针对单个对象进行描述。需要等待需求沉淀，由后端主动封装，迭代节奏会更慢。

什么是 GraphQL 客户端?

• 客户端数据拉取缓存问题（包括缓存一致性、更新缓存等）

• 数据分页、声明式数据获取

• ...

服务端落地：GraphQL → Django

• graphene-django

• django-filter

• Django Model ⇒ Schema

• Query ⇒ Filter Django Model

支持 Relay

from graphene import relay
from graphene_django import DjangoObjectType
from ingredients.models import Category

# Graphene will automatically map the Category model's fields onto the CategoryNode.
# This is configured in the CategoryNode's Meta class (as you can see below)
class CategoryNode(DjangoObjectType):
    class Meta:
        model = Category
        filter_fields = ['name', 'ingredients']
        interfaces = (relay.Node, )

query {
  allIngredients {
    edges {
      node {
        id,
        name
      }
    }
  }
}

query {
  allIngredients {
    id
    name
  }
}

• Fragment \ Directives

• 分页、过滤

• 通过 DRF Serializer 定义 Mutations

引入 graphene-django-extras

from graphene import ObjectType
from graphene_django_extras import DjangoListObjectField, DjangoListObjectType
from graphene_django_extras.paginations import LimitOffsetGraphqlPagination

class CommentListType(DjangoListObjectType):
    class Meta:
        model = Comment
        fields = "__all__"
        pagination = LimitOffsetGraphqlPagination(default_limit=25, ordering="-id")

class Query(ObjectType):
    comments = DjangoListObjectField(CommentListType, description="Query all comments")

class CommentListType(DjangoListObjectType):
    class Meta:
        model = Comment
        filter_fields = {
            "id": ["exact", "in"],
            "content": ["exact", "icontains", "istartswith"]
        }
        pagination = LimitOffsetGraphqlPagination(default_limit=25, ordering="-username")

query {
  comments(id__In: [1, 2, 3] content_Icontains: "Amazing"){
    totalCount
    results(limit: 10 offset: 0){
      id
      email
    }
  } 
}

class Query(ObjectType):
    user = Field(UserType, description="Retrieve certain user", id=Int(), username=String())

		def resolve_user(
        self, context: "GraphQLResolveInfo", id: Optional[int] = None, username: Optional[str] = None
    ) -> User:
        if id is not None:
            return User.objects.get(pk=id)

        if username is None:
            raise ValueError("username or pk at least one is required")

        # do some custom logic
        ...

        return User.objects.get(username=username)

鉴权

from .mixins import AuthNode
from .permissions import AllowSuperuser

class UserNode(AuthNode, DjangoObjectType):
    permission_classes = (AllowAuthenticated,)

    class Meta:
        model = User
        filter_fields = ('username',)
        interfaces = (relay.Node,)

总结

• GraphQL 在前端需求迭代频繁的场景下，比 REST 更符合现代开发节奏

• GraphQL 的语言设计比自定义扩展的 REST 更自然，更具备通用性

• GraphQL 会将比较多的工作放到客户端，适合成熟的客户端开发团队，反之 REST 是更好的选择

• Django 相关的生态建设并不完善，没有一个足够强大、开箱即用的整合方案

• 由于查询并不是基于 Uri 维度，会给周边配套的生态—— 监控、日志等 ——带来一些新的挑战