基于 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-webasync-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"),
        ),
    ))
}

上面的示例代码中,函数 graphqlgraphiql 作为 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,以及对于 graphqlgraphiql 这两个请求处理函数,我们也是在 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 <linshi@budshome.com>"]
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@budshome.com', '我谁24ok32', '5ff82b2c0076cc8b00e5cddb');
INSERT INTO `user` VALUES (2, 'oka@budshome.com', '我s谁24ok32', '5ff83f4b00e8fda000e5cddc');
INSERT INTO `user` VALUES (3, 'oka2@budshome.com', '我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 <linshi@budshome.com>"]
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@budshome.com",
        "id": 1,
        "username": "我谁24ok32"
      },
      {
        "email": "oka@budshome.com",
        "id": 2,
        "username": "我s谁24ok32"
      },
      {
        "email": "oka2@budshome.com",
        "id": 3,
        "username": "我2s谁24ok32"
      }
      ……
      ……
    ]
  }
}

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

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

下篇摘要

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

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

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

谢谢您的阅读,欢迎交流(微信号 yupen-com,或者页底邮箱)。