[GraphQL] 基于 actix-web + async-graphql + rbatis + postgresql / mysql 构建异步 Rust GraphQL 服务(4) - 变更服务,以及小重构
💥 内容涉及著作权,均归属作者本人。若非作者注明,默认欢迎转载:请注明出处,及相关链接。
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
选项卡查看,将看到查询和变更服务的列表都有了变化。如下图所示:
插入一个新用户(重复插入)
插入的 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,欢迎您共同完善。
下篇计划
变更服务开发完成后,后端我们告一阶段。下篇开始,我们进行前端的开发,仍然使用 Rust 技术栈:actix-web
、rhai
、handlebars-rust
、surf
,以及 graphql_client
。
本次实践,我们称之为 Rust 全栈开发 ;-)
谢谢您的阅读!