GraphQL 是一种用于 API 开发的查询语言，由 Facebook 开发。与传统的 REST API 不同，GraphQL 允许客户端指定所需的数据结构，从而避免了过多的数据传输。使用 Python 开发 GraphQL API 可以利用诸如 Graphene、Ariadne 等库。

1. GraphQL 基本概念

• Schema: 定义了 GraphQL API 的数据模型和操作（查询、变更、订阅）。
• Query: 获取数据的操作，相当于 REST API 中的 GET 请求。
• Mutation: 修改数据的操作，相当于 REST API 中的 POST、PUT、DELETE 请求。
• Resolver: 处理客户端请求的函数，用于从数据库或其他数据源获取数据。

2. 使用 Graphene 开发 GraphQL API

Graphene 是一个流行的 Python 库，用于构建 GraphQL API。

安装 Graphene

pip install graphene

创建基本的 GraphQL Schema

以下示例展示了如何使用 Graphene 创建一个简单的 GraphQL API。

创建 Schema 定义

import graphene

class User(graphene.ObjectType):
    id = graphene.ID()
    username = graphene.String()
    email = graphene.String()

class Query(graphene.ObjectType):
    users = graphene.List(User)

    def resolve_users(self, info):
        return [
            User(id=1, username="alice", email="alice@example.com"),
            User(id=2, username="bob", email="bob@example.com"),
        ]

schema = graphene.Schema(query=Query)

• User: 定义了用户类型（id、username、email）。
• Query: 定义了 users 查询，返回一个用户列表。

创建 GraphQL 视图

接下来，将 GraphQL Schema 暴露为一个可访问的 API 端点。以下示例展示了如何使用 Flask 将 GraphQL 集成到 Web 应用中。

pip install flask graphene flask-graphql

from flask import Flask
from graphene import Schema
from flask_graphql import GraphQLView
import graphene

# 定义 User 类型
class User(graphene.ObjectType):
    id = graphene.ID()
    username = graphene.String()
    email = graphene.String()

# 定义 Query
class Query(graphene.ObjectType):
    users = graphene.List(User)

    def resolve_users(self, info):
        return [
            User(id=1, username="alice", email="alice@example.com"),
            User(id=2, username="bob", email="bob@example.com"),
        ]

# 创建 Flask 应用
app = Flask(__name__)

# 创建 Schema
schema = Schema(query=Query)

# 配置 GraphQL 视图
app.add_url_rule(
    "/graphql", 
    view_func=GraphQLView.as_view("graphql", schema=schema, graphiql=True)
)

if __name__ == "__main__":
    app.run(debug=True)

• Flask-GraphQL: 提供了一个 GraphQLView 类，将 GraphQL Schema 公开为一个 API 端点。
• graphiql=True: 启用了 GraphiQL（GraphQL 的交互式开发工具），方便在浏览器中测试查询。

启动服务器并访问 GraphQL

运行服务器后，可以通过浏览器访问 http://localhost:5000/graphql，使用 GraphiQL 界面测试 GraphQL 查询：

{
  users {
    id
    username
    email
  }
}

添加 Mutations

Mutations 用于修改服务器端数据，例如创建、更新或删除记录。以下示例展示了如何定义和使用 Mutation。

class CreateUser(graphene.Mutation):
    class Arguments:
        username = graphene.String(required=True)
        email = graphene.String(required=True)

    user = graphene.Field(lambda: User)

    def mutate(self, info, username, email):
        user = User(username=username, email=email)
        return CreateUser(user=user)

class Mutation(graphene.ObjectType):
    create_user = CreateUser.Field()

schema = graphene.Schema(query=Query, mutation=Mutation)

• CreateUser: 定义了一个 Mutation，用于创建用户。
• Arguments: 指定了 Mutation 所需的参数。

在 GraphiQL 中测试 Mutation：

mutation {
  createUser(username: "charlie", email: "charlie@example.com") {
    user {
      id
      username
      email
    }
  }
}

3. 使用 Ariadne 开发 GraphQL API

Ariadne 是另一个构建 GraphQL API 的 Python 库，使用 SDL（Schema Definition Language）定义 GraphQL Schema。

安装 Ariadne

pip install ariadne

创建基本的 GraphQL Schema 和 Resolvers

from ariadne import QueryType, make_executable_schema, graphql_sync
from ariadne.constants import PLAYGROUND_HTML
from flask import Flask, request, jsonify

type_defs = """
    type Query {
        hello: String!
    }
"""

query = QueryType()

@query.field("hello")
def resolve_hello(_, info):
    return "Hello, world!"

schema = make_executable_schema(type_defs, query)

app = Flask(__name__)

@app.route("/graphql", methods=["GET"])
def graphql_playground():
    return PLAYGROUND_HTML, 200

@app.route("/graphql", methods=["POST"])
def graphql_server():
    data = request.get_json()
    success, result = graphql_sync(schema, data, context_value=request, debug=app.debug)
    status_code = 200 if success else 400
    return jsonify(result), status_code

if __name__ == "__main__":
    app.run(debug=True)

• type_defs: 定义 GraphQL Schema，使用 SDL 语法。
• QueryType: 定义 Resolver，与 GraphQL 查询进行关联。
• make_executable_schema: 将 SDL 和 Resolver 结合生成可执行的 Schema。

4. 使用 Django 和 Graphene-Django

如果你在使用 Django 开发，可以使用 Graphene-Django 将 GraphQL 集成到 Django 项目中。

安装 Graphene-Django

pip install graphene-django

配置 Django 项目

在 settings.py 中添加 graphene_django 到 INSTALLED_APPS:

INSTALLED_APPS = [
    ...
    'graphene_django',
]

GRAPHENE = {
    'SCHEMA': 'myproject.schema.schema'  # 指向你的 Schema 定义
}

创建 Django Models 和 GraphQL Schema

from django.db import models
import graphene
from graphene_django import DjangoObjectType

class User(models.Model):
    username = models.CharField(max_length=100)
    email = models.EmailField()

class UserType(DjangoObjectType):
    class Meta:
        model = User

class Query(graphene.ObjectType):
    users = graphene.List(UserType)

    def resolve_users(self, info):
        return User.objects.all()

schema = graphene.Schema(query=Query)

在 urls.py 中添加 GraphQL 端点：

from django.urls import path
from graphene_django.views import GraphQLView

urlpatterns = [
    path("graphql", GraphQLView.as_view(graphiql=True)),
]

总结

• Graphene 是 Python 中构建 GraphQL API 的最常用工具，提供了直观的 API 和丰富的功能。
• Ariadne 提供了使用 SDL 语法定义 Schema 的灵活方式，适合更复杂的场景。
• Graphene-Django 让 Django 开发者可以轻松地将 GraphQL 集成到现有项目中。

无论是简单的 API 还是复杂的 Web 应用，使用 GraphQL 可以帮助你构建灵活、高效的数据接口。