Strawberry GraphQL 实现 Apollo Federation 2 完全指南

Strawberry GraphQL 实现 Apollo Federation 2 完全指南

strawberry A GraphQL library for Python that leverages type annotations 🍓 项目地址: https://gitcode.com/gh_mirrors/st/strawberry

前言

在现代微服务架构中，GraphQL Federation（联邦）技术允许我们将多个独立的GraphQL服务组合成一个统一的API。本文将深入讲解如何使用Strawberry GraphQL框架实现Apollo Federation 2规范，构建可扩展的分布式GraphQL系统。

什么是Apollo Federation 2？

Apollo Federation 2是GraphQL联邦查询规范的最新版本，相比第一代有以下改进：

• 简化了类型扩展语法
• 移除了不必要的@external指令
• 提供了更灵活的共享类型机制
• 增强了错误处理能力

环境准备

在开始前，请确保：

1. 已安装Python 3.7+
2. 已安装Strawberry GraphQL框架
3. 了解基本的GraphQL概念

实战案例：图书评论系统

我们通过一个图书评论系统的例子来演示联邦实现。系统包含两个服务：

1. 图书服务：管理图书基本信息
2. 评论服务：管理图书评论信息

1. 图书服务实现

创建books/app.py文件：

from typing import List
import strawberry

@strawberry.federation.type(keys=["id"])
class Book:
    id: strawberry.ID
    title: str

def get_all_books() -> List[Book]:
    return [Book(id=strawberry.ID("1"), title="The Dark Tower")]

@strawberry.type
class Query:
    all_books: List[Book] = strawberry.field(resolver=get_all_books)

schema = strawberry.federation.Schema(query=Query, enable_federation_2=True)

关键点说明：

• 使用@strawberry.federation.type而非普通类型装饰器
• keys=["id"]指定实体主键
• enable_federation_2=True启用Federation 2支持

2. 评论服务实现

创建reviews/app.py文件：

from typing import List
import strawberry

@strawberry.type
class Review:
    id: int
    body: str

def get_reviews(root: "Book") -> List[Review]:
    return [
        Review(id=id_, body=f"A review for {root.id}")
        for id_ in range(root.reviews_count)
    ]

@strawberry.federation.type(keys=["id"])
class Book:
    id: strawberry.ID
    reviews_count: int
    reviews: List[Review] = strawberry.field(resolver=get_reviews)

    @classmethod
    def resolve_reference(cls, id: strawberry.ID):
        return Book(id=id, reviews_count=3)

@strawberry.type
class Query:
    _hi: str = strawberry.field(resolver=lambda: "Hello World!")

schema = strawberry.federation.Schema(
    query=Query, 
    types=[Book, Review], 
    enable_federation_2=True
)

核心概念解析：

• 类型扩展：评论服务扩展了图书类型，添加了评论相关字段
• 解析引用：resolve_reference方法用于跨服务解析实体
• 占位查询：GraphQL规范要求必须定义Query类型

联邦架构运行

1. 启动服务

分别启动两个服务：

# 图书服务
strawberry server --port 3500 books/app.py

# 评论服务
strawberry server --port 3000 reviews/app.py

2. 配置联邦网关

使用Apollo Router作为网关，需要：

1. 安装Apollo Router
2. 创建supergraph.yaml配置文件
3. 使用Rover CLI组合模式

组合后的模式将包含来自两个服务的所有类型和字段。

联邦查询示例

通过网关执行查询：

{
  allBooks {
    id
    title
    reviews {
      body
    }
  }
}

响应示例：

{
  "data": {
    "allBooks": [
      {
        "id": "1",
        "title": "The Dark Tower",
        "reviews": [
          {"body": "A review for 1"},
          {"body": "A review for 1"},
          {"body": "A review for 1"}
        ]
      }
    ]
  }
}

高级特性：联邦指令

Strawberry支持所有Federation 2.7规范指令：

• @key：定义实体主键
• @shareable：允许字段在多个服务中定义
• @inaccessible：隐藏字段
• @tag：添加元数据标签
• @override：覆盖来自其他服务的字段

使用示例：

@strawberry.type(directives=[Key(fields="id"), Tag(name="experimental")])
class Product:
    id: strawberry.ID
    name: str

最佳实践

1. 实体设计：合理划分服务边界，避免过度耦合
2. 性能优化：resolve_reference方法应考虑缓存
3. 错误处理：实现健壮的错误返回机制
4. 版本控制：联邦服务应保持向后兼容

常见问题解答

Q：为什么需要resolve_reference方法？ A：当网关需要从其他服务获取关联数据时，会调用此方法实例化实体。

Q：如何调试联邦查询问题？ A：建议先单独测试每个服务，再通过网关测试组合查询。

Q：联邦与普通GraphQL有何不同？ A：联邦允许跨服务引用类型，而普通GraphQL所有类型必须在单一模式中定义。

总结

通过本文，我们学习了如何使用Strawberry GraphQL实现Apollo Federation 2规范。联邦GraphQL是构建大型分布式系统的强大工具，合理使用可以显著提高开发效率和系统可维护性。

strawberry A GraphQL library for Python that leverages type annotations 🍓 项目地址: https://gitcode.com/gh_mirrors/st/strawberry