NiQin (blog: 泥芹) shared the aphorism --

要成为赢家，诀窍就在于了解自己什么时候是输家。 -- 电影《转轮手枪》

[GraphQL] 基于 actix-web + async-graphql + rbatis + postgresql / mysql 构建异步 Rust GraphQL 服务（4） - 变更服务，以及小重构

2021-05-06 14:11:11+08:00 by - NiQin [blog: 泥芹]

💥 内容涉及著作权，均归属作者本人。若非作者注明，默认欢迎转载：请注明出处，及相关链接。

Summary: 基于 actix-web + async-graphql + rbatis + postgresql / mysql 构建 Rust 异步 GraphQL 服务的变更服务教程，包括依赖项的更新和配置。以及 async-graphql 简单对象类型、复杂对象类型、输入对象类型的迭代和开发。新用户的插入，包括根据用户唯一性标志属性验证。

Topics: rust graphql async-graphql mysql rbatis postgresql

前 3 篇文章中，我们初始化搭建了工程结构，选择了必须的 crate，并成功构建了 GraphQL 查询服务，以及对代码进行了第一次重构。本篇文章，是我们进行 GraphQL 服务后端开发的最后一篇：变更服务。本篇文章之后，GraphQL 服务后端开发第一阶段告一阶段，之后我们进行基于 Rust 的 Web 前端开发。本系列文章中，采用螺旋式思路，Web 前端基础开发之后，再回头进行 GraphQL 后端开发的改进。

自定义表名的小重构

有查阅基于 actix-web + async-graphql + rbatis + postgresql / mysql 构建异步 Rust GraphQL 服务（2） - 查询服务文章的朋友联系笔者，关于文章中 user 表和 User 结构体同名的问题。表名可以自定义的，然后在 rbatis 中指定即可。比如，我们将上一篇中的 user 表改名为 users，那么 async-graphql 简单对象的代码如下：

use serde::{Serialize, Deserialize};

#[rbatis::crud_enable(table_name:"users")]
#[derive(async_graphql::SimpleObject, Serialize, Deserialize, Clone, Debug)]
#[graphql(complex)]
pub struct User {
    pub id: i32,
    pub email: String,
    pub username: String,
    pub cred: String,
}

#[async_graphql::ComplexObject]
impl User {
    pub async fn from(&self) -> String {
        let mut from = String::new();
        from.push_str(&self.username);
        from.push_str("<");
        from.push_str(&self.email);
        from.push_str(">");

        from
    }
}

其中 #[rbatis::crud_enable(table_name:"users")] 中的表名，可以不用双引号包裹。示例代码的引号，仅是笔者习惯。

依赖项更新

自基于 actix-web + async-graphql + rbatis + postgresql / mysql 构建异步 Rust GraphQL 服务（3） - 重构之后，已经大抵过去半个月时间了。这半个月以来，活跃的 Rust 社区生态，进行了诸多更新：Rust 版本即将更新为 1.52.0，Rust 2021 版即将发布……本示例项目中，使用的依赖项 async-graphql / async-graphql-actix-web（感谢孙老师的辛勤奉献，建议看到此文的朋友，star 孙老师的 async-graphql 仓库）、rbatis 等 crate 都有了 1-2 个版本的升级。

你可以使用 cargo upgrade 升级，或者直接修改 Cargo.toml 文件，全部使用最新版本的依赖 crate：

[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]
actix-web = "3.3.2"

dotenv = "0.15.0"
lazy_static = "1.4.0"


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

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

本系列文章中，对于 crate 的依赖，采取非必要不引入的原则。带最终完成，共计依赖项约为 56 个。

变更服务

接下来，我们开发 GraphQL 的变更服务。示例中，我们以模型 -> 服务 -> 总线的顺序来开发。这个顺序并非固定，在实际开发中，可以根据自己习惯进行调整。

定义 `NewUser` 输入对象类型

在此，我们定义一个欲插入 users 集合中的结构体，包含对应字段即可，其为 async-graphql 中的输入对象类型。需要注意的是，mysql 或 postgres 中，id 是自增主键，因此不需要定义此字段。cred 是计划使用 PBKDF2 对密码进行加密（salt）和散列（hash）运算后的鉴权码，需要定义，但无需在新增时填写。因此，在此我们需要介绍一个 async-graphql 中的属性标记 #[graphql(skip)]，其表示此字段不会映射到 GraphQL。

代码较简单，所以我们直接贴 users/models.rs 文件完整代码：

use serde::{Serialize, Deserialize};

#[rbatis::crud_enable(table_name:"users")]
#[derive(async_graphql::SimpleObject, Serialize, Deserialize, Clone, Debug)]
#[graphql(complex)]
pub struct User {
    pub id: i32,
    pub email: String,
    pub username: String,
    pub cred: String,
}

#[async_graphql::ComplexObject]
impl User {
    pub async fn from(&self) -> String {
        let mut from = String::new();
        from.push_str(&self.username);
        from.push_str("<");
        from.push_str(&self.email);
        from.push_str(">");

        from
    }
}

#[rbatis::crud_enable(table_name:"users")]
#[derive(async_graphql::InputObject, Serialize, Deserialize, Clone, Debug)]
pub struct NewUser {
    #[graphql(skip)]
    pub id: i32,
    pub email: String,
    pub username: String,
    #[graphql(skip)]
    pub cred: String,
}

编写服务层代码，将 `NewUser` 结构体插入数据库

服务层 users/services.rs 中，我们仅需定义一个函数，用于将 NewUser 结构体插入 mysql/postgres 数据库。我们从 GraphiQL/playground 中获取 NewUser 结构体时，因为我们使用了标记 #[graphql(skip)]，所以 id、cred 字段不会映射到 GraphQL。对于 mysql/postgres 的文档数据库特性，id 是自增字段；cred 我们设定为非空，所以对于其要写入一个固定值。随着本教程的逐渐深入，我们会迭代为关联用户特定值，使用 PBKDF2 对密码进行加密（salt）和散列（hash）运算后的鉴权码。

同时，实际应用中，插入用户时，我们应当设定一个用户唯一性的标志属性，以用来判断数据库是否已经存在此用户。本实例中，我们使用 email 作为用户的唯一性标志属性。因此，我们需要开发 get_user_by_email 服务。

再者，我们将 NewUser 结构体插入 mysql/postgres 数据库后，应当返回插入结果。因此，我们还需要开发一个根据 username 或者 email 查询用户的 GraphQL 服务。因为我们已经设定 email 为用户的唯一性标志属性，因此直接使用 get_user_by_email 查询已经插入用户即可。

服务层 users/services.rs 文件完整代码如下：

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

use crate::util::constant::GqlResult;
use crate::users::models::{NewUser, User};

// 查询所有用户
pub async fn all_users(my_pool: &Rbatis) -> GqlResult<Vec<User>> {
    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")))
    }
}

// 通过 email 获取用户
pub async fn get_user_by_email(
    my_pool: &Rbatis,
    email: &str,
) -> GqlResult<User> {
    let email_wrapper = my_pool.new_wrapper().eq("email", email);
    let user = my_pool.fetch_by_wrapper::<User>("", &email_wrapper).await;

    if user.is_ok() {
        Ok(user.unwrap())
    } else {
        Err(Error::new("email 不存在")
            .extend_with(|_, e| e.set("details", "1_EMAIL_NOT_EXIStS")))
    }
}

// 插入新用户
pub async fn new_user(
    my_pool: &Rbatis,
    mut new_user: NewUser,
) -> GqlResult<User> {
    new_user.email = new_user.email.to_lowercase();

    if self::get_user_by_email(my_pool, &new_user.email).await.is_ok() {
        Err(Error::new("email 已存在")
            .extend_with(|_, e| e.set("details", "1_EMAIL_EXIStS")))
    } else {
        new_user.cred =
            "P38V7+1Q5sjuKvaZEXnXQqI9SiY6ZMisB8QfUOP91Ao=".to_string();
        my_pool.save("", &new_user).await.expect("插入 user 数据时出错");

        self::get_user_by_email(my_pool, &new_user.email).await
    }
}

将服务添加到服务总线

查询服务对应的服务总线为 gql/queries.rs，变更服务对应的服务总线为 gql/mutations.rs。到目前为止，我们一直未有编写变更服务总线文件 gql/mutations.rs。现在，我们将 new_user 变更服务和 get_user_by_email 查询服务分别添加到变更和查询服务总线。

加上我们查询服务的 all_users 服务，服务总线共计 2 个文件，3 个服务。

查询服务总线 `gql/queries.rs`

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

use crate::util::constant::GqlResult;
use crate::users::{self, models::User};
pub struct QueryRoot;

#[async_graphql::Object]
impl QueryRoot {
    // 获取所有用户
    async fn all_users(&self, ctx: &Context<'_>) -> GqlResult<Vec<User>> {
        let my_pool = ctx.data_unchecked::<Rbatis>();
        users::services::all_users(my_pool).await
    }

    //根据 email 获取用户
    async fn get_user_by_email(
        &self,
        ctx: &Context<'_>,
        email: String,
    ) -> GqlResult<User> {
        let my_pool = ctx.data_unchecked::<Rbatis>();
        users::services::get_user_by_email(my_pool, &email).await
    }
}

变更服务总线 gql/mutations.rs

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

use crate::users::{
    self,
    models::{NewUser, User},
};
use crate::util::constant::GqlResult;

pub struct MutationRoot;

#[async_graphql::Object]
impl MutationRoot {
    // 插入新用户
    async fn new_user(
        &self,
        ctx: &Context<'_>,
        new_user: NewUser,
    ) -> GqlResult<User> {
        let my_pool = ctx.data_unchecked::<Rbatis>();
        users::services::new_user(my_pool, new_user).await
    }
}

第一次验证

查询服务、变更服务均编码完成，我们验证下开发成果。通过 cargo run 或者 cargo watch 启动应用程序，浏览器输入 http://127.0.0.1:8080/v1i，打开 graphiql/playgound 界面。

如果你的配置未跟随教程，请根据你的配置输入正确链接，详见你的 .env 文件配置项。

但是，如果你此时通过 graphiql/playgound 界面的 docs 选项卡查看，仍然仅能看到查询服务下有一个孤零零的 allUsers: [User!]!。这是因为，我们前几篇教程中，仅编写查询服务代码，所以服务器 Schema 构建时使用的是 EmptyMutation。我们需要将我们自己的变更服务总线 gql/mutations.rs，添加到 SchemaBuilder 中。

仅仅涉及 gql/mod.rs 文件。

将变更服务总线添加到 SchemaBuilder

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::{EmptySubscription, Schema};
use async_graphql_actix_web::{Request, Response};

use crate::util::constant::CFG;
use crate::dbs::mysql::my_pool;
use crate::gql::{queries::QueryRoot, mutations::MutationRoot};

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

pub async fn build_schema() -> ActixSchema {
    // 获取 mysql 数据池后，可以将其增加到：
    // 1. 作为 async-graphql 的全局数据；
    // 2. 作为 actix-web 的应用程序数据，优势是可以进行原子操作；
    // 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, MutationRoot, 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(CFG.get("GQL_VER").unwrap())
                .subscription_endpoint(CFG.get("GQL_VER").unwrap()),
        ),
    ))
}

Okay，大功告成，我们进行第二验证。

第二次验证

打开方式和注意事项和第一次验证相同。

正常启动后，如果你此时通过 graphiql/playgound 界面的 docs 选项卡查看，将看到查询和变更服务的列表都有了变化。如下图所示：

actix-graphql 变更服务

插入一个新用户（重复插入）

插入的 newUser 数据为（注意，GraphQL 中自动转换为驼峰命名）：

注意：示例仅为插入对象部分，你需要补充 mutation 声明和 API 方法。

   newUser: { 
      email: "budshome@budshome.com", 
      username: "我是谁" 
    }

第一次插入，然会正确的插入结果：

{
  "data": {
    "newUser": {
        "cred": "P38V7+1Q5sjuKvaZEXnXQqI9SiY6ZMisB8QfUOP91Ao=",
        "email": "budshome@budshome.com",
        "from": "我是谁<budshome@budshome.com>",
        "id": 5,
        "username": "我是谁"
    }
  }
}

第二次重复插入，因为 email 已存在，则返回我们开发中定义的错误信息：

{
  "data": null,
  "errors": [
    {
      "message": "email 已存在",
      "locations": [
        {
          "line": 2,
          "column": 3
        }
      ],
      "path": [
        "newUser"
      ],
      "extensions": {
        "details": "1_EMAIL_EXIStS"
      }
    }
  ]
}

请自己查看你的数据库，已经正常插入了目标数据。

至此，变更服务开发完成。

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