FastAPI集成Strawberry GraphQL教程

简介

GraphQL是一种高效的API查询语言，与传统的REST API相比，它允许客户端精确指定所需数据。在FastAPI中集成GraphQL可以扩展应用的功能。本教程使用Strawberry，一个简单、现代的GraphQL框架，适合新手学习。

前提条件

在开始之前，确保您具备以下基础知识：

• Python 3.7或更高版本
• 基本理解Python和FastAPI
• 已安装pip（Python包管理器）

安装依赖

首先，安装所需的Python包。打开终端或命令行工具，运行以下命令：

pip install fastapi strawberry-graphql uvicorn

这将安装FastAPI、Strawberry GraphQL和Uvicorn（一个ASGI服务器）。

创建FastAPI应用

创建一个新的Python文件（例如main.py），并导入必要的模块：

from fastapi import FastAPI

app = FastAPI()

这初始化了一个基础的FastAPI应用。

定义GraphQL模式

接下来，使用Strawberry定义GraphQL的类型和查询。在同一个文件中添加：

import strawberry
from typing import List

# 定义一个简单的数据模型：书籍
@strawberry.type
class Book:
    title: str
    author: str

# 定义GraphQL查询
@strawberry.type
class Query:
    @strawberry.field
    def books(self) -> List[Book]:
        # 示例数据，实际中可能来自数据库
        return [
            Book(title="The Great Gatsby", author="F. Scott Fitzgerald"),
            Book(title="1984", author="George Orwell")
        ]

# 创建GraphQL模式
schema = strawberry.Schema(query=Query)

这里，我们定义了一个Book类型和一个查询字段books，它返回一个书籍列表。

集成Strawberry到FastAPI

现在，将GraphQL路由添加到FastAPI应用中。更新main.py：

from fastapi import FastAPI
from strawberry.fastapi import GraphQLRouter

app = FastAPI()

# 导入之前定义的schema（确保在定义后）
# 创建GraphQL路由
graphql_app = GraphQLRouter(schema)

# 将GraphQL端点挂载到应用
app.include_router(graphql_app, prefix="/graphql")

# 可选：添加一个主页路由作为测试
@app.get("/")
def root():
    return {"message": "FastAPI with GraphQL is running. Go to /graphql for GraphQL playground."}

这将GraphQL端点设置为/graphql，并自动提供GraphQL playground界面用于交互测试。

运行和测试应用

保存文件后，使用Uvicorn运行应用：

uvicorn main:app --reload

--reload参数启用热重载，便于开发。服务器启动后，访问以下URL：

• 主页：http://localhost:8000/
• GraphQL playground：http://localhost:8000/graphql

在GraphQL playground中，尝试运行查询：

{
  books {
    title
    author
  }
}

您应该会看到一个JSON响应，包含书籍数据。

扩展功能：添加GraphQL变异

GraphQL不仅支持查询，还支持变异（用于修改数据）。在main.py中添加变异：

# 定义变异
@strawberry.type
class Mutation:
    @strawberry.field
    def add_book(self, title: str, author: str) -> Book:
        # 模拟添加新书籍的逻辑，实际中应保存到数据库
        new_book = Book(title=title, author=author)
        return new_book

# 更新模式以包含查询和变异
schema = strawberry.Schema(query=Query, mutation=Mutation)

在GraphQL playground中，现在可以测试变异：

mutation {
  addBook(title: "The Catcher in the Rye", author: "J.D. Salinger") {
    title
    author
  }
}

这将添加一本新书并返回其详细信息。

常见问题解答

• 问题：安装strawberry-graphql失败
  • 解决方案：检查Python版本是否兼容，或使用pip install --upgrade strawberry-graphql。
• 问题：GraphQL端点不工作
  • 解决方案：确保正确导入GraphQLRouter并添加了前缀，检查FastAPI应用是否正确初始化。
• 问题：如何处理错误或自定义逻辑
  • 提示：Strawberry支持自定义错误处理和中间件，参考官方文档进行高级配置。

总结

通过本教程，您学会了如何在FastAPI中集成Strawberry GraphQL。Strawberry的简洁语法和与FastAPI的紧密集成，使得GraphQL开发变得轻松。下一步，您可以探索更多GraphQL特性，如订阅、联合类型等。

资源推荐

• Strawberry官方文档：https://strawberry.rocks
• FastAPI官方文档：https://fastapi.tiangolo.com

希望本教程帮助您快速上手！如有问题，欢迎参考文档或社区讨论。