[GraphQL] 构建 Rust 异步 GraphQL 服务：基于 tide + async-graphql + mongodb（2）- 查询服务
💥 内容涉及著作权，均归属作者本人。若非作者注明，默认欢迎转载：请注明出处，及相关链接。
Summary: 上一篇文章中，我们对后端基础工程进行了初始化。但是未有进行任何开发，本文中，我们将开启基础 GraphQL 服务的历程。包括如下内容： 1、构建 GraphQL Schema； 2、整合 Tide 和 async-graphql； 3、验证 query 服务； 4、连接 MongoDB； 5、提供 query 服务。
Topics: rust graphql async-graphql tide mongodb json-web-token jwt
上一篇文章中，我们对后端基础工程进行了初始化。其中，笔者选择 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 的应用开发，在此，笔者简单提及下选型理由——
- Tide：tide 的定位是最小的、实用的 Rust web 应用服务框架，基于 async-std。其相较于 Rust 社区中火热的 actix-web，确实可以说冷门。至于生态成熟度，也有诸多差距。但我们在提供 GraphQL 服务时，主要需要的是基础的 HTTP 服务器。tide 目前的功能和性能是完全满足的，并且经笔者测试后，对其健壮性也很满意。
- async-graphql：优秀的 crate，性能很棒，以及开发时的简洁性，个人对其喜欢程度胜过 juniper。
- 至于 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 查看详细）：
如图中示例，在左侧输入：
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@budshome.com",
"username": "我是ok",
"cred": "peCwspEaVw3HB05ObIpnGxgK2VSQOCmgxjzFEOY+fk0="
}
_id是由 MongoDB 自动产生的，，与系统时间相关；cred是使用 PBKDF2 对用户密码进行加密（salt）和散列（hash）运算后产生的密码，后面会有详述。此处，请您随意。
提供 query 服务
Schema 中添加 MongoDB 数据源
前文小节我们创建了 MongoDB 数据源，欲在 async-graphql 中是获取和使用 MongoDB 数据源，由如下方法——
- 作为 async-graphql 的全局数据；
- 作为 Tide 的应用状态 State，优势是可以作为 Tide 服务器状态，进行原子操作；
- 使用 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 工程结构，如下图所示：
其中 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 的
derivetrait，因此需要迭代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@budshome.com",
"id": "5ff82b2c0076cc8b00e5cddb",
"username": "我谁24ok32"
},
{
"email": "oka@budshome.com",
"id": "5ff83f4b00e8fda000e5cddc",
"username": "我s谁24ok32"
},
{
"email": "oka2@budshome.com",
"id": "5ffd710400b6b84e000349f8",
"username": "我2s谁24ok32"
},
{
"email": "afasf@budshome.com",
"id": "5ffdb3fa00bbdf3a007a2988",
"username": "哈哈"
},
{
"email": "oka22@budshome.com",
"id": "600b7a2700e7c21500d6cc1e",
"username": "我22s谁24ok32"
},
{
"email": "iok@budshome.com",
"id": "600b7a5300adcd7900d6cc1f",
"username": "我是ok"
},
{
"email": "iok2@budshome.com",
"id": "600b8064000a5ca30024199e",
"username": "我是ok2"
}
]
}
}
好的，以上就是一个完成的 GraphQL 查询服务（此处应有掌声 :-)）。
如果您一步步跟着操作，是很难不成功的，但总有例外，欢迎交流。
下篇摘要
目前我们成功开发了一个基于 Rust 技术栈的 GraphQL 查询服务，但本例代码是不够满意的，如冗长的返回类型 std::result::Result<Vec<User>, async_graphql::Error>，如太多的魔术代码。
下篇中，我们先不进行 GraphQL mutation 的开发。我将对代码进行重构——
- 应用配置文件；
- 代码抽象。
谢谢您的阅读。