2. GraphQL 基础：查询语言、类型系统、SDL 与 RESTful API 对比

在 BFF 架构中，GraphQL 作为聚合层的核心通信协议，其查询语言、类型系统和 Schema 定义语言（SDL）构成了与前端契约的基础。本章将系统讲解 GraphQL 的核心概念，并通过与 RESTful API 的对比，揭示其在 BFF 场景下的优势与适用边界。

2.1 GraphQL 查询语言：声明式数据获取

GraphQL 查询语言的核心思想是“客户端精确声明所需数据”，而非由服务端决定返回结构。这种模式在 BFF 聚合层中尤为关键——前端可以一次性获取多个资源的数据，且只取需要的字段。

2.1.1 查询（Query）与变更（Mutation）

GraphQL 将操作分为两类：Query（读取数据）和 Mutation（写入数据）。以下是一个典型的 BFF 聚合查询示例：

# 查询：获取用户信息及其最近订单
query GetUserWithOrders($userId: ID!) {
  user(id: $userId) {
    id
    name
    email
    orders(limit: 5) {
      id
      totalAmount
      status
      items {
        productName
        quantity
        price
      }
    }
  }
}

对应的响应结构完全匹配查询形状：

{
  "data": {
    "user": {
      "id": "u-1001",
      "name": "张三",
      "email": "zhangsan@example.com",
      "orders": [
        {
          "id": "ord-5001",
          "totalAmount": 299.00,
          "status": "SHIPPED",
          "items": [
            { "productName": "无线耳机", "quantity": 1, "price": 199.00 },
            { "productName": "充电线", "quantity": 2, "price": 50.00 }
          ]
        }
      ]
    }
  }
}

2.1.2 查询参数与变量

GraphQL 支持通过变量动态传递参数，避免客户端拼接字符串：

# 定义变量
variables: {
  "userId": "u-1001",
  "orderStatus": "SHIPPED"
}

# 查询使用变量
query GetFilteredOrders($userId: ID!, $orderStatus: OrderStatus) {
  user(id: $userId) {
    orders(status: $orderStatus) {
      id
      totalAmount
      createdAt
    }
  }
}

2.2 类型系统：GraphQL 的契约基石

GraphQL 的类型系统是 Schema 的核心，它定义了所有可查询的数据结构、字段类型以及操作入口。类型系统确保了客户端与服务端之间的强契约，这在 BFF 多团队协作中尤为重要。

2.2.1 标量类型与对象类型

2.2.2 非空与列表修饰符

GraphQL 使用 ! 和 [] 来定义字段的约束：

type Order {
  id: ID!                # 非空 ID
  totalAmount: Float!    # 非空浮点数
  items: [OrderItem!]!   # 非空列表，列表内元素非空
  discount: Float        # 可为空的折扣
}

2.2.3 枚举与联合类型

枚举类型限定字段的取值范围，联合类型允许一个字段返回多种对象类型：

enum OrderStatus {
  PENDING
  CONFIRMED
  SHIPPED
  DELIVERED
  CANCELLED
}

union SearchResult = User | Order | Product

type Query {
  search(keyword: String!): [SearchResult!]!
}

2.3 Schema 定义语言（SDL）：声明式契约

SDL 是 GraphQL 定义 Schema 的专用语法，它使用人类可读的 DSL 来描述类型、接口、输入类型和操作入口。BFF 团队通过 SDL 文件与前端团队共享契约，实现“契约优先”的开发模式。

2.3.1 完整的 BFF Schema 示例

# 定义输入类型（用于 Mutation 参数）
input CreateOrderInput {
  userId: ID!
  items: [OrderItemInput!]!
  shippingAddress: String!
}

input OrderItemInput {
  productId: ID!
  quantity: Int!
}

# 定义接口
interface Node {
  id: ID!
}

# 实现接口的对象类型
type User implements Node {
  id: ID!
  name: String!
  email: String!
  orders(limit: Int = 10): [Order!]!
}

type Order implements Node {
  id: ID!
  totalAmount: Float!
  status: OrderStatus!
  items: [OrderItem!]!
  createdAt: String!
}

type OrderItem {
  productName: String!
  quantity: Int!
  price: Float!
}

# 查询入口
type Query {
  user(id: ID!): User
  order(id: ID!): Order
  recentOrders(limit: Int = 20): [Order!]!
}

# 变更入口
type Mutation {
  createOrder(input: CreateOrderInput!): Order!
  cancelOrder(id: ID!): Order!
}

2.3.2 SDL 在 BFF 中的角色

• 契约文档：SDL 文件是前后端之间的“活文档”，前端可据此生成类型安全的查询代码。
• 测试依据：契约测试（如 GraphQL-inspector）可检测 Schema 变更是否破坏现有查询。
• Mock 数据生成：基于 SDL 可自动生成 Mock 数据，加速前端开发。

2.4 GraphQL 与 RESTful API 的对比

在 BFF 架构选型时，理解 GraphQL 与 RESTful API 的差异至关重要。以下从多个维度进行对比：

2.4.1 核心差异对比表

2.4.2 场景选择建议

• 适合 GraphQL 的场景：
  • 前端需要灵活组合多个资源的数据（如仪表盘、详情页）
  • 多客户端（Web、iOS、Android）对数据需求差异大
  • 团队希望“契约优先”开发，减少前后端联调成本
• 适合 RESTful API 的场景：
  • 资源模型简单，前端需求稳定（如 CRUD 管理后台）
  • 需要充分利用 HTTP 缓存基础设施
  • 团队对 GraphQL 运维经验不足

2.5 架构对比：GraphQL vs RESTful 在 BFF 中的交互模式

下图展示了 GraphQL 与 RESTful API 在 BFF 层与后端微服务交互时的典型架构差异：

2.6 从 RESTful 迁移到 GraphQL 的常见模式

在 BFF 架构演进中，团队常采用渐进式迁移策略。以下列出三种典型模式：

2.7 本章小结

• GraphQL 查询语言支持客户端精确声明数据需求，单次请求可获取多个关联资源。
• 类型系统（标量、对象、枚举、联合、接口）和修饰符（非空、列表）构成了强契约基础。
• SDL 是 BFF 团队与前端团队共享契约的核心文件，支持“契约优先”开发。
• 与 RESTful API 相比，GraphQL 在灵活性和类型安全方面优势明显，但在缓存和性能控制上需要额外设计。
• 架构选型应根据团队经验、系统规模和前端需求灵活决策，渐进式迁移是降低风险的有效策略。