基于 tide + async-graphql + mongodb 构建 Rust 异步 GraphQL 服务（2）- 查询服务

上一篇文章中，我们对后端基础工程进行了初始化。其中，笔者选择 Rust 生态中的 4 个 crate：tide、async-std、async-graphql、mongodb（bson 主要为 mongodb 应用）。虽然我们不打算对 Rust 生态中的 crate 进行介绍和比较，但想必有朋友对这几个选择有些疑问，比如：tide 相较于 actix-web，可称作冷门、不成熟，postgresql 相较于 mongodb 操作的便利性等。

笔者在 2018-2019 年间，GraphQL 服务后端，一直使用的是 actix-web + juniper + postgresql 的组合，应用前端使用了 typescript + react + apollo-client，有兴趣可以参阅开源项目 actix-graphql-react。

2020 年，笔者才开始了 tide + async-graphql 的应用开发，在此，笔者简单提及下选型理由——

  1. Tide：tide 的定位是最小的、实用的 Rust web 应用服务框架，基于 async-std。其相较于 Rust 社区中火热的 actix-web，确实可以说冷门。至于生态成熟度，也有诸多差距。但我们在提供 GraphQL 服务时，主要需要的是基础的 HTTP 服务器。tide 目前的功能和性能是完全满足的，并且经笔者测试后，对其健壮性也很满意。
  2. async-graphql：优秀的 crate，性能很棒，以及开发时的简洁性，个人对其喜欢程度胜过 juniper。
  3. 至于 postgresql 转为 mongodb，只是一时兴起。本来计划 elasticsearch 的，只是个人服务器跑起来不给力。

Rust 社区生态中，健壮的 web 应用服务框架很多，您可以参考 Rust web 框架比较 一文自行比较选择。

上文中，未有进行任何代码编写。本文中，我们将开启基础 GraphQL 服务的历程。包括如下内容：

1、构建 GraphQL Schema；

2、整合 Tide 和 async-graphql；

3、验证 query 服务；

4、连接 MongoDB；

5、提供 query 服务。

构建 GraphQL Schema

首先，让我们将 GraphQL 服务相关的代码都放到一个模块中。为了避免下文啰嗦，我称其为 GraphQL 总线。

cd ./rust-graphql/backend/src
mkdir gql
cd ./gql
touch mod.rs queries.rs mutations.rs

构建一个查询示例

  • 首先，我们构建一个不连接数据库的查询示例：通过一个函数进行求合运算，将其返回给 graphql 查询服务。此实例改编自 async-graphql 文档，仅用于验证环境配置，实际环境没有意义。

下面代码中，注意变更 EmptyMutation 和订阅 EmptySubscription 都是空的，甚至 mutations.rs 文件都是空白，未有任何代码，仅为验证服务器正确配置。

在 mod.rs 文件中，写入以下代码：


pub mod mutations;
pub mod queries;

use tide::{http::mime, Body, Request, Response, StatusCode};

use async_graphql::{
    http::{playground_source, receive_json, GraphQLPlaygroundConfig},
    EmptyMutation, EmptySubscription, Schema,
};

use crate::State;

use crate::gql::queries::QueryRoot;

pub async fn build_schema() -> Schema<QueryRoot, EmptyMutation, EmptySubscription> {
    // The root object for the query and Mutatio, and use EmptySubscription.
    // Add global mongodb datasource  in the schema object.
    // let mut schema = Schema::new(QueryRoot, MutationRoot, EmptySubscription)
    Schema::build(QueryRoot, EmptyMutation, EmptySubscription).finish()
}

pub async fn graphql(req: Request<State>) -> tide::Result {
    let schema = req.state().schema.clone();
    let gql_resp = schema.execute(receive_json(req).await?).await;

    let mut resp = Response::new(StatusCode::Ok);
    resp.set_body(Body::from_json(&gql_resp)?);

    Ok(resp.into())
}

pub async fn graphiql(_: Request<State>) -> tide::Result {
    let mut resp = Response::new(StatusCode::Ok);
    resp.set_body(playground_source(GraphQLPlaygroundConfig::new("graphql")));
    resp.set_content_type(mime::HTML);

    Ok(resp.into())
}

上面的示例代码中，函数 graphql 和 graphiql 作为 tide 服务器的请求处理程序，因此必须返回 tide::Result。

tide 开发很简便，本文不是重点。请参阅 tide 中文文档，很短时间即可掌握。

编写求和实例，作为 query 服务

在 queries.rs 文件中，写入以下代码：


pub struct QueryRoot;

#[async_graphql::Object]
impl QueryRoot {
    async fn add(&self, a: i32, b: i32) -> i32 {
        a + b
    }
}

整合 Tide 和 async-graphql

终于，我们要进行 tide 服务器主程序开发和启动了。进入 ./backend/src 目录，迭代 main.rs 文件：


mod gql;

use crate::gql::{build_schema, graphiql, graphql};

#[async_std::main]
async fn main() -> Result<(), std::io::Error> {
    // tide logger
    tide::log::start();

    // 初始 Tide 应用程序状态
    let schema = build_schema().await;
    let app_state = State { schema: schema };
    let mut app = tide::with_state(app_state);

    // 路由配置
    app.at("graphql").post(graphql);
    app.at("graphiql").get(graphiql);

    app.listen(format!("{}:{}", "127.0.0.1", "8080")).await?;

    Ok(())
}

//  Tide 应用程序作用域状态 state.
#[derive(Clone)]
pub struct State {
    pub schema: async_graphql::Schema<
        gql::queries::QueryRoot,
        async_graphql::EmptyMutation,
        async_graphql::EmptySubscription,
    >,
}

注1：上面代码中，我们将 schema 放在了 tide 的状态 State 中，其作用域是应用程序级别的，可以很方便地进行原子操作。

注2：另外，关于 tide 和 async-graphql 的整合，async-graphql 提供了整合 crate：async_graphql_tide。但笔者测试后未使用，本文也未涉及，您感兴趣的话可以选择。

验证 query 服务

启动 tide 服务

以上，一个基础的基于 Rust 技术栈的 GraphQL 服务器已经开发成功了。我们验证以下是否正常，请执行——

cargo run

更推荐您使用我们前一篇文章中安装的 cargo watch 来启动服务器，这样后续代码的修改，可以自动部署，无需您反复对服务器进行停止和启动操作。

cargo watch -x "run"

但遗憾的是——此时，你会发现服务器无法启动，因为上面的代码中，我们使用了 #[async_std::main] 此类的 Rust 属性标记。所以，我们还需要稍微更改一下 backend/Cargo.toml 文件。

请注意，不是根目录 rust-graphql/Cargo.toml 文件。

同时，MongoDB 驱动程序中，支持的异步运行时 crate 为 tokio，我们其它如 tide 和 async-graphql 都是基于 async-std 异步库的，所以我们一并修改。最终，backend/Cargo.toml 文件内容如下（有强迫症，也调整了一下顺序，您随意）：

...
[dependencies]
tide = "0.16.0"
async-std = { version = "1.9.0", features = ["attributes"] }

async-graphql = "2.6.0"
mongodb = { version = "1.2.0", default-features = false, features = ["async-std-runtime"] }
bson = "1.2.0"
...

再次执行 cargo run 命令，您会发现服务器已经启动成功，启动成功后的消息为：

tide::log Logger started
    level Info
tide::server Server listening on http://127.0.0.1:8080

执行 GraphQL 查询

请打开您的浏览器，输入 http://127.0.0.1:8080/graphiql，您会看到如下界面（点击右侧卡片 docs 和 schema 查看详细）：

graphiql

如图中示例，在左侧输入：

query {
  add(a: 110, b: 11)
}

右侧的返回结果为：

{
  "data": {
    "add": 121
  }
}

基础的 GraphQL 查询服务成功！

连接 MongoDB

创建 MongoDB 数据源

为了做到代码仓库风格的统一，以及扩展性。目前即使只需要连接 MongoDB 数据库，我们也将其放到一个模块中。

下面的示例中，即使本地连接，我也开启了身份验证。请您自行配置数据库，或者免密访问。

cd ./rust-graphql/backend/src
mkdir dbs
touch ./dbs/mod.rs ./dbs/mongo.rs

在 mongo.rs 中，编写如下代码：


use mongodb::{Client, options::ClientOptions, Database};

pub struct DataSource {
    client: Client,
    pub db_budshome: Database,
}

#[allow(dead_code)]
impl DataSource {
    pub async fn client(&self) -> Client {
        self.client.clone()
    }

    pub async fn init() -> DataSource {
        // 解析 MongoDB 连接字符串到 options 结构体中
        let mut client_options =
            ClientOptions::parse("mongodb://mongo:mongo@localhost:27017")
                .await
                .expect("Failed to parse options!");
        // 可选：自定义一个 options 选项
        client_options.app_name = Some("tide-graphql-mongodb".to_string());

        // 客户端句柄
        let client = Client::with_options(client_options)
            .expect("Failed to initialize database!");

        // 数据库句柄
        let db_budshome = client.database("budshome");

        // 返回值 mongodb datasource
        DataSource { client: client, db_budshome: db_budshome }
    }
}

在 mod.rs 中，编写如下代码：


pub mod mongo;
// pub mod postgres;
// pub mod mysql;

创建集合及文档

在 MongoDB 中，创建集合 users，并构造几个文档，示例数据如下：

{
    "_id": ObjectId("600b7a5300adcd7900d6cc1f"),
    "email": "iok@rusthub.org",
    "username": "我是ok",
    "cred": "peCwspEaVw3HB05ObIpnGxgK2VSQOCmgxjzFEOY+fk0="
}
  • _id 是由 MongoDB 自动产生的，，与系统时间相关；
  • cred 是使用 PBKDF2 对用户密码进行加密（salt）和散列（hash）运算后产生的密码，后面会有详述。此处，请您随意。

提供 query 服务

Schema 中添加 MongoDB 数据源

前文小节我们创建了 MongoDB 数据源，欲在 async-graphql 中是获取和使用 MongoDB 数据源，由如下方法——

  1. 作为 async-graphql 的全局数据；
  2. 作为 Tide 的应用状态 State，优势是可以作为 Tide 服务器状态，进行原子操作；
  3. 使用 lazy-static.rs，优势是获取方便，简单易用。

如果不作前后端分离，为了方便前端的数据库操作，那么 2 和 3 是比较推荐的，特别是使用 crate lazy-static，存取方便。笔者看到很多开源实例和一些成熟的 rust-web 应用都采用 lazy-static。

虽然 2 和 3 方便、简单，以及易用。但是本应用中，我们仅需要 tide 作为一个服务器提供 http 服务，MongoDB 数据源也仅是为 async-graphql 使用。因此，我采用作为 async-graphql 的全局数据，将其构建到 Schema 中。

基于上述思路，我们迭代 backend/src/gql/mod.rs 文件：

pub mod mutations;
pub mod queries;

use tide::{http::mime, Body, Request, Response, StatusCode};

use async_graphql::{
    http::{playground_source, receive_json, GraphQLPlaygroundConfig},
    EmptyMutation, EmptySubscription, Schema,
};

use crate::State;

use crate::dbs::mongo;

use crate::gql::queries::QueryRoot;

pub async fn build_schema() -> Schema<QueryRoot, EmptyMutation, EmptySubscription> {
    // 获取 mongodb datasource 后，可以将其增加到：
    // 1. 作为 async-graphql 的全局数据；
    // 2. 作为 Tide 的应用状态 State；
    // 3. 使用 lazy-static.rs
    let mongo_ds = mongo::DataSource::init().await;

    // The root object for the query and Mutatio, and use EmptySubscription.
    // Add global mongodb datasource  in the schema object.
    // let mut schema = Schema::new(QueryRoot, MutationRoot, EmptySubscription)
    Schema::build(QueryRoot, EmptyMutation, EmptySubscription)
        .data(mongo_ds)
        .finish()
}

pub async fn graphql(req: Request<State>) -> tide::Result {
    let schema = req.state().schema.clone();
    let gql_resp = schema.execute(receive_json(req).await?).await;

    let mut resp = Response::new(StatusCode::Ok);
    resp.set_body(Body::from_json(&gql_resp)?);

    Ok(resp.into())
}

pub async fn graphiql(_: Request<State>) -> tide::Result {
    let mut resp = Response::new(StatusCode::Ok);
    resp.set_body(playground_source(GraphQLPlaygroundConfig::new("graphql")));
    resp.set_content_type(mime::HTML);

    Ok(resp.into())
}

开发一个查询服务，自 MongoDB 集合 users 集合查询所有用户：

增加 users 模块，及分层阐述

一个完整的 GraphQL 查询服务，在本应用项目——注意，非 Tide 或者 GraphQL 技术分层——我们可以简单将其分为三层：

  • tide handle：发起一次 GraphQL 请求，通知 GraphQL 总线执行 GraphQL service 调用，以及接收和处理响应；
  • GraphQL 总线：分发 GraphQL service 调用；
  • service：负责执行具体的查询服务，从 MongoDB 数据获取数据，并封装到 model 中；

基于上述思路，我们想要开发一个查询所有用户的 GraphQL 服务，需要增加 users 模块，并创建如下文件：

cd ./backend/src
mkdir users
cd users
touch mod.rs models.rs services.rs

至此，本篇文章的所有文件已经创建，先让我们查看一下总体的 backend 工程结构，如下图所示：

backend 完成文件结构

其中 users/mod.rs 文件内容为：

pub mod models;
pub mod services;

我们也需要将 users 模块添加到 main.rs 中：

mod dbs;
mod gql;
mod users;

use crate::gql::{build_schema, graphiql, graphql};

#[async_std::main]
async fn main() -> Result<(), std::io::Error> {
    // tide logger
    tide::log::start();

    // 初始 Tide 应用程序状态
    let schema = build_schema().await;
    let app_state = State { schema: schema };
    let mut app = tide::with_state(app_state);

    // 路由配置
    app.at("graphql").post(graphql);
    app.at("graphiql").get(graphiql);

    app.listen(format!("{}:{}", "127.0.0.1", "8080")).await?;

    Ok(())
}

//  Tide 应用程序作用域状态 state.
#[derive(Clone)]
pub struct State {
    pub schema: async_graphql::Schema<
        gql::queries::QueryRoot,
        async_graphql::EmptyMutation,
        async_graphql::EmptySubscription,
    >,
}

编写 User 模型

在 users/models.rs 文件中添加：

use serde::{Serialize, Deserialize};
use bson::oid::ObjectId;

#[derive(Serialize, Deserialize, Clone)]
pub struct User {
    pub _id: ObjectId,
    pub email: String,
    pub username: String,
    pub cred: String,
}

#[async_graphql::Object]
impl User {
    pub async fn id(&self) -> ObjectId {
        self._id.clone()
    }

    pub async fn email(&self) -> &str {
        self.email.as_str()
    }

    pub async fn username(&self) -> &str {
        self.username.as_str()
    }
}

上述代码中，User 结构体中定义的字段类型为 String，但结构体实现中返回为 &str，这是因为 Rust 中 String 未有默认实现 copy trait。如果您希望结构体实现中返回 String，可以通过 clone() 方法实现：

    pub async fn email(&self) -> String {
        self.email.clone()
    }

您使用的 IDE 比较智能，或许会有报错，先不要管，我们后面一并处理。

编写 service

在 users/services.rs 文件中添加代码，如下：

use async_graphql::{Error, ErrorExtensions};
use futures::stream::StreamExt;
use mongodb::Database;

use crate::users::models::User;

pub async fn all_users(db: Database) -> std::result::Result<Vec<User>, async_graphql::Error> {
    let coll = db.collection("users");

    let mut users: Vec<User> = vec![];

    // Query all documents in the collection.
    let mut cursor = coll.find(None, None).await.unwrap();

    // Iterate over the results of the cursor.
    while let Some(result) = cursor.next().await {
        match result {
            Ok(document) => {
                let user = bson::from_bson(bson::Bson::Document(document)).unwrap();
                users.push(user);
            }
            Err(error) => Err(Error::new("6-all-users")
                .extend_with(|_, e| e.set("details", format!("Error to find doc: {}", error))))
            .unwrap(),
        }
    }

    if users.len() > 0 {
        Ok(users)
    } else {
        Err(Error::new("6-all-users").extend_with(|_, e| e.set("details", "No records")))
    }
}

您使用的 IDE 比较智能，或许会有报错，先不要管，我们后面一并处理。

在 GraphQL 总线中调用 service

迭代 gql/queries.rs 文件，最终为：

use async_graphql::Context;

use crate::dbs::mongo::DataSource;
use crate::users::{self, models::User};

pub struct QueryRoot;

#[async_graphql::Object]
impl QueryRoot {
    // Get all Users,
    async fn all_users(
        &self,
        ctx: &Context<'_>,
    ) -> std::result::Result<Vec<User>, async_graphql::Error> {
        let db = ctx.data_unchecked::<DataSource>().db_budshome.clone();
        users::services::all_users(db).await
    }
}

Okay，如果您使用的 IDE 比较智能，可以看到现在已经是满屏的红、黄相配了。代码是没有问题的，我们只是缺少几个使用到的 crate。

  • 首先，执行命令：
cargo add serde futures
  • 其次，因为我们使用到了 serde crate 的 derive trait，因此需要迭代 backend/Cargo.toml 文件，最终版本为：
[package]
name = "backend"
version = "0.1.0"
authors = ["我是谁？"]
edition = "2018"

# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html

[dependencies]
futures = "0.3.13"
tide = "0.16.0"
async-std = { version = "1.9.0", features = ["attributes"] }

serde = { version = "1.0.124", features = ["derive"] }
async-graphql = "2.6.0"
mongodb = { version = "1.2.0", default-features = false, features = ["async-std-runtime"] }
bson = "1.2.0"

现在，重新运行 cargo build，可以发现红、黄错误已经消失殆尽了。执行 cargo watch -x "run" 命令会发现启动成功。

最后，我们来执行 GraphQL 查询，看看是否取出了 MongoDB 中集合 users 中的所有数据。

左侧输入：

# Write your query or mutation here
query {
  allUsers {
    id
    email
    username
  }
}

右侧返回结果依赖于您在集合中添加了多少文档，如我的查询结果为：

{
  "data": {
    "allUsers": [
      {
        "email": "ok@rusthub.org",
        "id": "5ff82b2c0076cc8b00e5cddb",
        "username": "我谁24ok32"
      },
      {
        "email": "oka@rusthub.org",
        "id": "5ff83f4b00e8fda000e5cddc",
        "username": "我s谁24ok32"
      },
      {
        "email": "oka2@rusthub.org",
        "id": "5ffd710400b6b84e000349f8",
        "username": "我2s谁24ok32"
      },
      {
        "email": "afasf@rusthub.org",
        "id": "5ffdb3fa00bbdf3a007a2988",
        "username": "哈哈"
      },
      {
        "email": "oka22@rusthub.org",
        "id": "600b7a2700e7c21500d6cc1e",
        "username": "我22s谁24ok32"
      },
      {
        "email": "iok@rusthub.org",
        "id": "600b7a5300adcd7900d6cc1f",
        "username": "我是ok"
      },
      {
        "email": "iok2@rusthub.org",
        "id": "600b8064000a5ca30024199e",
        "username": "我是ok2"
      }
    ]
  }
}

好的，以上就是一个完成的 GraphQL 查询服务（此处应有掌声 :-)）。

如果您一步步跟着操作，是很难不成功的，但总有例外，欢迎交流。

下篇摘要

目前我们成功开发了一个基于 Rust 技术栈的 GraphQL 查询服务，但本例代码是不够满意的，如冗长的返回类型 std::result::Result<Vec<User>, async_graphql::Error>，如太多的魔术代码。

下篇中，我们先不进行 GraphQL mutation 的开发。我将对代码进行重构——

  • 应用配置文件；
  • 代码抽象。

谢谢您的阅读。