基于 actix-web + async-graphql + rbatis + postgresql / mysql 构建异步 Rust GraphQL 服务（2） - 查询服务

上一篇文章中，我们对后端基础工程进行了初始化，未有进行任何代码编写。本文中，我们将不再进行技术选型和优劣对比，直接基于 actix-web 和 async-graphql 构建异步 Rust GraphQL 服务的历程。本章主要是 GraphQL 查询服务，包括如下内容：

1、构建 GraphQL Schema；

2、整合 actix-web 和 async-graphql；

3、验证 query 服务；

4、连接 mysql；

5、提供 query 服务。

构建 GraphQL Schema

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

cd ./actix-web-async-graphql/backend/src
mkdir gql
cd ./gql
touch mod.rs queries.rs mutations.rs

构建一个查询示例

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

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

下面，我们需要编写代码。思路如下：

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

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


pub struct QueryRoot;

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

mod.rs 中：构建 Schema，并编写请求处理（handler）函数

  • 通过 async-graphql SchemaBuilder，构建要在 actix-web 中使用的 GraphQL Schema，并接入我们自己的查询、变更，以及订阅服务。
  • 目前，我们首先要进行 actix-web 和 async-graphql 的集成验证，所以仅有求和作为查询服务，变更和订阅服务都是空的。
  • 同时，我们要进行 actix-web 中的请求处理（handler）函数的编写。

actix-web 的请求处理函数中，请求为 HttpRequest 类型，响应类型则是 HttpResponse。而 async-graphql 在执行 GraphQL 服务时，请求类型和返回类型与 actix-web 的并不同，需要进行封装处理。

async-graphql 官方提供了 actix-web 与 async-graphql 的集成 crate async-graphql-actix-web，功能很全。我们直接使用，通过 cargo add async-graphql-actix-web 命令添加到依赖项。然后，填入具体代码如下：

pub mod mutations;
pub mod queries;

use actix_web::{web, HttpResponse, Result};
use async_graphql::http::{playground_source, GraphQLPlaygroundConfig};
use async_graphql::{EmptyMutation, EmptySubscription, Schema};
use async_graphql_actix_web::{Request, Response};

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

// `ActixSchema` 类型定义，项目中可以统一放置在一个共用文件中。
// 但和 `actix-web` 和 `tide` 框架不同，无需放入应用程序`状态（State）`
// 所以此 `Schema` 类型仅是为了代码清晰易读，使用位置并不多，我们直接和构建函数一起定义。
// 或者，不做此类型定义，直接作为构建函数的返回类型。
type ActixSchema = Schema<
    queries::QueryRoot,
    async_graphql::EmptyMutation,
    async_graphql::EmptySubscription,
>;

pub async fn build_schema() -> ActixSchema {
    // The root object for the query and Mutatio, and use EmptySubscription.
    // Add global sql datasource  in the schema object.
    Schema::build(QueryRoot, EmptyMutation, EmptySubscription).finish()
}

pub async fn graphql(schema: web::Data<ActixSchema>, req: Request) -> Response {
    schema.execute(req.into_inner()).await.into()
}

pub async fn graphiql() -> Result<HttpResponse> {
    Ok(HttpResponse::Ok().content_type("text/html; charset=utf-8").body(
        playground_source(
            GraphQLPlaygroundConfig::new("/graphql").subscription_endpoint("/graphql"),
        ),
    ))
}

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

actix-web 开发本文不是重点，请参阅 actix-web 中文文档，很短时间即可掌握。

整合 actix-web 和 async-graphql

接下来，我们要进行 actix-web 服务器主程序开发和启动。进入 ./backend/src 目录，迭代 main.rs 文件：

mod gql;

use actix_web::{guard, web, App, HttpServer};

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

#[actix_rt::main]
async fn main() -> std::io::Result<()> {
    let schema = build_schema().await;

    println!("GraphQL UI: http://127.0.0.1:8080");

    HttpServer::new(move || {
        App::new()
            .data(schema.clone())
            .service(web::resource("/graphql").guard(guard::Post()).to(graphql))
            .service(web::resource("/graphiql").guard(guard::Get()).to(graphiql))
    })
    .bind("127.0.0.1:8080")?
    .run()
    .await
}

本段代码中，我们直接在 App 构建器中加入 schema，以及对于 graphql 和 graphiql 这两个请求处理函数，我们也是在 App 构建器中逐次注册。这种方式虽然没有问题，但对于一个应用的主程序 main.rs 来讲，精简一些更易于阅读和维护。所以我们下一篇文章中对此迭代，通过 ServiceConfig 进行注册。

验证 query 服务

启动 actix-web 服务

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

cargo run

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

cargo watch -x \"run\"

但遗憾的是——此时，你会发现服务器无法启动，因为上面的代码中，我们使用了 #[actix_rt::main] 此类的 Rust 属性标记。编译器会提示如下错误信息：

error[E0433]: failed to resolve: use of undeclared crate or module `actix_rt`
 --> backend\src\main.rs:7:3
  |
7 | #[actix_rt::main]
  |   ^^^^^^^^ use of undeclared crate or module `actix_rt`
……
……
error[E0752]: `main` function is not allowed to be `async`
 --> backend\src\main.rs:8:1
  |
8 | async fn main() -> std::io::Result<()> {
  | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ `main` function is not allowed to be `async`

error: aborting due to 3 previous errors

Some errors have detailed explanations: E0277, E0433, E0752.
For more information about an error, try `rustc --explain E0277`.
error: could not compile `backend`

根据编译器提示，我们执行 cargo add actix-rt，然后重新运行。但很遗憾，仍然会报错：

thread 'main' panicked at 'System is not running', ……\actix-rt-1.1.1\src\system.rs:78:21
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace

并且，我们查看 backend/Cargo.toml 文件时会发现，我们通过 cargo add 添加的依赖项是最新版，actix-rt = "2.2.0"，但此处错误信息却是 actix-rt-1.1.1\src\system.rs:78:21。这是因为 actix-web 3.3.2，可以一起正常工作的 actix-rt 最高版本是 1.1.1。如果你想使用 actix-rt = "2.2.0"，需要使用 actix-web 的测试版本，如下面配置：

……
actix = "0.11.0-beta.2"
actix-web = "4.0.0-beta.3"
actix-rt = "2.0.2"
……

我们的实践是为了生产环境使用，不尝鲜了。最终，我们更改 backend/Cargo.toml 文件如下：

[package]
name = "backend"
version = "0.1.0"
authors = ["zzy <ask@rusthub.org>"]
edition = "2018"

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

[dependencies]
actix-web = "3.3.2"
actix-rt = "1.1.1"

async-graphql = { version = "2.8.2", features = ["chrono"] }
async-graphql-actix-web = "2.8.2"
rbatis = { version = "1.8.83", default-features = false, features = ["mysql", "postgres"] }

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

再次执行 cargo run 命令，您会发现服务器已经启动成功。

执行 GraphQL 查询

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

graphiql

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

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

右侧的返回结果为：

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

基础的 GraphQL 查询服务成功！

连接 MySql

创建 MySql 数据池

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

cd ./actix-web-async-graphql/backend/src
mkdir dbs
touch ./dbs/mod.rs ./dbs/mysql.rs

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

use rbatis::core::db::DBPoolOptions;
use rbatis::rbatis::Rbatis;

// 对于常量，应当统一放置
// 下一篇重构中，我们再讨论不同的方式
pub const MYSQL_URL: &'static str =
    "mysql://root:mysql@localhost:3306/budshome";

pub async fn my_pool() -> Rbatis {
    let rb = Rbatis::new();

    let mut opts = DBPoolOptions::new();
    opts.max_connections = 100;

    rb.link_opt(MYSQL_URL, &opts).await.unwrap();

    rb
}

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

// pub mod postgres;
pub mod mysql;

创建数据表及数据

在 mysql 中，创建 user 表，并构造几条数据，示例数据如下：

SET NAMES utf8mb4;
SET FOREIGN_KEY_CHECKS = 0;

-- ----------------------------
-- Table structure for user
-- ----------------------------
DROP TABLE IF EXISTS `user`;
CREATE TABLE `user`  (
  `id` int(0) UNSIGNED NOT NULL AUTO_INCREMENT,
  `email` varchar(255) CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci NULL DEFAULT NULL,
  `username` varchar(255) CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci NULL DEFAULT NULL,
  `cred` varchar(255) CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci NULL DEFAULT NULL,
  PRIMARY KEY (`id`) USING BTREE
) ENGINE = InnoDB AUTO_INCREMENT = 4 CHARACTER SET = utf8mb4 COLLATE = utf8mb4_0900_ai_ci ROW_FORMAT = Dynamic;

-- ----------------------------
-- Records of user
-- ----------------------------
INSERT INTO `user` VALUES (1, 'ok@rusthub.org', '我谁24ok32', '5ff82b2c0076cc8b00e5cddb');
INSERT INTO `user` VALUES (2, 'oka@rusthub.org', '我s谁24ok32', '5ff83f4b00e8fda000e5cddc');
INSERT INTO `user` VALUES (3, 'oka2@rusthub.org', '我2s谁24ok32', '5ffd710400b6b84e000349f8');

SET FOREIGN_KEY_CHECKS = 1;
  • id 是由 mysql 自动产生的，且递增；
  • cred 是使用 PBKDF2 对用户密码进行加密（salt）和散列（hash）运算后产生的密码，后面会有详述。此处，请您随意。

提供 query 服务

Schema 中添加 MySql 数据池

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

  1. 作为 async-graphql 的全局数据；
  2. 作为 actix-web 的应用程序数据，优势是可以进行原子操作；
  3. 使用 lazy-static，优势是获取方便，简单易用。

如果不作前后端分离，为了方便前端的数据库操作，那么 2 和 3 是比较推荐的，特别是使用 crate lazy-static，存取方便，简单易用。rbatis 的官方实例，以及笔者看到其它开源 rust-web 项目，都采用 lazy-static。因为 rbatis 实现了 Send + Sync，是线程安全的，无需担心线程竞争。

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

笔者仅是简单使用，如果您有深入的见解，欢迎您指导（微信号 yupen-com，或者页底邮箱）。

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

pub mod mutations;
pub mod queries;

use actix_web::{web, HttpResponse, Result};
use async_graphql::http::{playground_source, GraphQLPlaygroundConfig};
use async_graphql::{EmptyMutation, EmptySubscription, Schema};
use async_graphql_actix_web::{Request, Response};

use crate::dbs::mysql::my_pool;
use crate::gql::queries::QueryRoot;

type ActixSchema = Schema<
    queries::QueryRoot,
    async_graphql::EmptyMutation,
    async_graphql::EmptySubscription,
>;

pub async fn build_schema() -> ActixSchema {
    // 获取 MySql 数据池后，可以将其增加到：
    // 1. 作为 async-graphql 的全局数据；
    // 2. 作为 Tide 的应用状态 State；
    // 3. 使用 lazy-static.rs
    let my_pool = my_pool().await;

    // The root object for the query and Mutatio, and use EmptySubscription.
    // Add global mysql pool  in the schema object.
    Schema::build(QueryRoot, EmptyMutation, EmptySubscription)
        .data(my_pool)
        .finish()
}

pub async fn graphql(schema: web::Data<ActixSchema>, req: Request) -> Response {
    schema.execute(req.into_inner()).await.into()
}

pub async fn graphiql() -> Result<HttpResponse> {
    Ok(HttpResponse::Ok().content_type("text/html; charset=utf-8").body(
        playground_source(
            GraphQLPlaygroundConfig::new("/graphql")
                .subscription_endpoint("/graphql"),
        ),
    ))
}

实现查询服务，自 MySql user 表查询所有用户

增加 users 模块，及分层阐述

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

  • actix-web handler：发起一次 GraphQL 请求，通知 GraphQL 总线执行 GraphQL service 调用，以及接收和处理响应；
  • GraphQL 总线：分发 GraphQL service 调用；
  • services：负责执行具体的查询服务，从 MySql 数据表获取数据，并封装到 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 gql;
mod dbs;
mod users;

use actix_web::{guard, web, App, HttpServer};

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

#[actix_rt::main]
async fn main() -> std::io::Result<()> {
    let schema = build_schema().await;

    println!("GraphQL UI: http://127.0.0.1:8080");

    HttpServer::new(move || {
        App::new()
            .data(schema.clone())
            .service(web::resource("/graphql").guard(guard::Post()).to(graphql))
            .service(
                web::resource("/graphiql").guard(guard::Get()).to(graphiql),
            )
    })
    .bind("127.0.0.1:8080")?
    .run()
    .await
}

编写 User 模型

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

use serde::{Serialize, Deserialize};

#[rbatis::crud_enable]
#[derive(Serialize, Deserialize, Clone, Debug)]
pub struct User {
    pub id: i32,
    pub email: String,
    pub username: String,
    pub cred: String,
}

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

    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 文件中添加代码，这次比 MongoDB 少了很多代码。如下：

use async_graphql::{Error, ErrorExtensions};
use rbatis::rbatis::Rbatis;
use rbatis::crud::CRUD;

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

pub async fn all_users(
    my_pool: &Rbatis,
) -> std::result::Result<Vec<User>, async_graphql::Error> {
    let users = my_pool.fetch_list::<User>("").await.unwrap();

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

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

在 GraphQL 总线中调用 service

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

use async_graphql::Context;
use rbatis::rbatis::Rbatis;

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 my_pool = ctx.data_unchecked::<Rbatis>();
        users::services::all_users(my_pool).await
    }
}

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

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

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

[dependencies]
actix-web = "3.3.2"
actix-rt = "1.1.1"

async-graphql = { version = "2.8.2", features = ["chrono"] }
async-graphql-actix-web = "2.8.2"
rbatis = { version = "1.8.83", default-features = false, features = ["mysql", "postgres"] }

serde = { version = "1.0", features = ["derive"] }

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

最后，我们来执行 GraphQL 查询，看看是否取出了 MySql 中 user 表的所有数据。

左侧输入：

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

右侧返回结果依赖于您在数据表中添加了多少条数据，如我的查询结果为：

{
  "data": {
    "allUsers": [
      {
        "email": "ok@rusthub.org",
        "id": 1,
        "username": "我谁24ok32"
      },
      {
        "email": "oka@rusthub.org",
        "id": 2,
        "username": "我s谁24ok32"
      },
      {
        "email": "oka2@rusthub.org",
        "id": 3,
        "username": "我2s谁24ok32"
      }
      ……
      ……
    ]
  }
}

好的，以上就是一个完成的 GraphQL 查询服务。

此实例源码仓库在 github，欢迎您共同完善。

下篇摘要

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

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

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

谢谢您的阅读，欢迎交流（微信号 yupen-com，或者页底邮箱）。