leancloud-graphql

LeanCloud GraphQL

运行在云引擎上的第三方 GraphQL 支持，允许你用 GraphQL 查询 LeanCloud 云存储中的所有数据。

• 部署到云引擎
• GraphQL
• 获取数据
• 查询
• 关系
• 创建和更新
• 添加到现有项目
  • 作为中间件添加
  • 获取 GraphQLSchema

部署到云引擎

GraphQL

GraphQL 是 FaceBook 开源的一套查询语言，你可以用它定义数据的格式和获取方法（这就是 leancloud-graphql 做的工作，它会自动将你在 LeanCloud 的数据结构转换为 GraphQL 的 Schema），然后便可以在客户端以一种非常灵活的语法来获取数据，甚至也可以用它来创建和更新数据。

在使用 leancloud-graphql 之前，你可能需要先了解一下 GraphQL 的语法 ，下面我们不会过多地介绍 GraphQL 本身。这篇文章将使用 JavaScript SDK 文档中的 示例数据结构 进行讲解。

GraphQL 在客户端几乎不需要什么 SDK，你可以花几行代码封装一个工具函数：

function requestGraphQL(query) {
  return fetch('/', {
    method: 'POST',
    body: query
  }).then( res => {
    return res.json();
  }).then( result => {
    return result.data;
  });
}

我们也在云引擎的根路径（本地调试时为 http://127.0.0.1:3000/）用 GraphiQL 提供了一个支持自动补全等功能的 GraphQL 控制台，你可以在这里测试你的查询。

我们会应用客户端发来的 sessionToken，确保在用户的权限范围内进行查询。你可以从我们的 JavaScript SDK 上获取 sessionToken 并随着请求发送，修改 requestGraphQL：

  headers: {
    'Content-Type': 'application/graphql',
+   'X-LC-Session': AV.User.current() && AV.User.current().getSessionToken()
  },

获取数据

最简单的一个查询：

requestGraphQL(`
  query {
    Todo {
      title, priority
    }
  }
`)

默认会返回最多 100 条数据：

{
  Todo: [
    {title: "紧急 Bug 修复", priority: 0},
    {title: "打电话给 Peter",priority: 5},
    {title: "还信用卡账单", priority: 10},
    {title: "买酸奶", priority: 10},
    {title: "团队会议", priority: 5}
  ]
}

你可以在此基础上添加排序、条数限制等选项：

• ascending 按照指定字段升序
• descending 按照指定字段降序
• limit 条数限制
• skip 跳过指定条数

例如我们按照优先级升序排序，取最重要的两个任务：

query {
  Todo(ascending: "priority", limit: 2) {
    title, priority
  }
}

结果：

{
  Todo: [
    {title: "紧急 Bug 修复", priority: 0},
    {title: "打电话给 Peter",priority: 5}
  ]
}

查询

首先你可以按照 objectId 进行简单的查询：

query {
  Todo(objectId: "5853a0e5128fe1006b5ce449") {
    title, priority
  }
}

结果：

{
  Todo: [
    {title: "还信用卡账单", priority: 10}
  ]
}

关系

如果对象的一个字段是 Relation，那么你就可以在 GraphQL 中将它展开，例如我们可以查询每个 TodoFolder 中包含的 Todo：

query {
  TodoFolder {
    name, containedTodos {
      title, priority
    }
  }
}

结果：

{
  TodoFolder: [{
    name: "工作",
    containedTodos: [
      {title: "紧急 Bug 修复", priority: 0},
      {title: "打电话给 Peter", priority: 5},
      {title: "团队会议", priority: 5}
    ]
  }, {
    name: "购物清单",
    containedTodos: [
      {title: "买酸奶", priority: 10}
    ]
  }]
}

如果一个字段是 Pointer 你也可以将它展开，例如我们可以查询 Todo 的创建者（到用户表的指针）：

query {
  Todo(limit: 1) {
    title, owner {
      username, email
    }
  }
}

结果：

{
  Todo: [
    {
      title: "紧急 Bug 修复",
      owner: {
        username: "someone",
        email: "[e-mail]"
      }
    }
  ]
}

在 GraphQL 中你甚至可以进行多层级的关系查询：

query {
  TodoFolder {
    name,
    containedTodos {
      title, owner {
        username, email
      }
    }
  }
}

结果（省略了一部分）：

{
  TodoFolder: [{
    name: "工作",
    containedTodos: [{
      title: "紧急 Bug 修复",
      owner: {
        username: "someone",
        email: "[e-mail]"
      }
    }, // ...
    ]
  }, // ...
  ]
}

创建和更新

你可以这样创建一个对象，并要求服务器返回 objectId、标题和优先级：

mutation {
  Todo(title: "思考巨石阵是如何修建的") {
    objectId, title, priority
  }
}

结果：

{
  Todo: {
    objectId: "5853adb7b123db006562f83b",
    title: "思考巨石阵是如何修建的",
    priority: 10
  }
}

然后你可以用非常相似的语法来更新这个对象（当你提供了 objectId 便是更新对象）：

mutation {
  Todo(objectId: "5853adb7b123db006562f83b", priority: 5) {
    title, priority
  }
}

结果：

{
  Todo: {
    title: "思考巨石阵是如何修建的",
    priority: 5
  }
}

添加到现有项目

如果要添加到现有项目，需要先将 leancloud-graphql 添加为依赖：

npm install --save leancloud-graphql

请确保 Node.js 版本在 4.0 以上。

作为中间件添加

leancloud-graphql 导出了一个 express 中间件，可以直接添加到现有的 express 项目上：

var leancloudGraphQL = require('leancloud-graphql').express;
var app = express();
app.use('/graphql', leancloudGraphQL());

leancloudGraphQL 有一些选项：

• graphiql 开启调试控制台，默认 true.
• cors 提供跨域支持，默认 true.
• pretty 格式化返回的 JSON。

使用该中间件时请确保环境变量中有 LEANCLOUD_ 系列的环境变量，即需要运行在云引擎上或用 lean up 启动。

获取 GraphQLSchema

leancloud-graphql 默认导出了一个构建 GraphQLSchema 的函数：

var buildSchema = require('leancloud-graphql');
var {printSchema} = require('graphql');

buildSchema({
  appId: process.env.LEANCLOUD_APP_ID,
  appKey: process.env.LEANCLOUD_APP_KEY,
  masterKey: process.env.LEANCLOUD_APP_MASTER_KEY
}).then( schema => {
  console.log(printSchema(schema));
});