okgoes
🔍
← 目录从零开始学python
✏️ 编辑

Python GraphQL API 开发

2024/8/20

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

bash
pip install graphene

创建基本的 GraphQL Schema

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

创建 Schema 定义
python
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 应用中。

bash
pip install flask graphene flask-graphql
python
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 查询：

graphql
{
  users {
    id
    username
    email
  }
}

添加 Mutations

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

python
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：

graphql
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

bash
pip install ariadne

创建基本的 GraphQL Schema 和 Resolvers

python
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

bash
pip install graphene-django

配置 Django 项目

在 settings.py 中添加 graphene_django 到 INSTALLED_APPS:

python
INSTALLED_APPS = [
    ...
    'graphene_django',
]

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

创建 Django Models 和 GraphQL Schema

python
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 端点：

python
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 可以帮助你构建灵活、高效的数据接口。