用 Rust 编写 RESTful Web API

本文需要用到以下工具/库：

Rust and Cargo toolchain
actix-web web 框架
sea-orm ORM 框架
serde 序列化/反序列化
dotenvy 环境变量配置

项目初始化#

首先 cargo new workspace 创建一个新项目，但该项目只作为workspace工作空间，因此可以将src目录直接删掉，然后编辑Cargo.toml:

1
[workspace]
2
members = ["app"]
3
default-members=["app"]

设置default-members，这样cargo run的默认项目就是app。

然后，cargo new app，新建app crate。接着给app的Cargo.toml添加如下依赖：

1
[dependencies]
2
actix-web="4"
3
sea-orm = { version = "^0", features = [ "sqlx-sqlite", "runtime-actix-native-tls", "macros" ] }
4
serde = { version = "1.0", features = ["derive"] }
5
dotenvy = "0.15.6"

actix 准备#

首先我们到app的 main.rs，把 actix 先跑起来看看。

1
use actix_web::{web, App, HttpServer};
2

3
#[actix_web::main]
4
async fn main() -> Result<(), std::io::Error> {
5
    HttpServer::new(|| App::new().route("/ping", web::get().to(|| async { "pong!" })))
6
        .bind(("127.0.0.1", 5000))?
7
        .run()
8
        .await
9
}

cargo run 然后 curl http://localhost:5000，你会看到一个”pong!”.

用 dotenvy 控制环境变量#

监听选项写死是不太好的，这时可以使用dotenvy包。在workspace目录下创建一个.env文件，内容为：

1
LISTEN=0.0.0.0

然后，我们在main中通过读取环境变量来实现动态配置。

1
use actix_web::{web, App, HttpServer};
2
use dotenvy::dotenv;
3
use std::env;
4

5
#[actix_web::main]
6
async fn main() -> Result<(), std::io::Error> {
7
    dotenv().ok();
8

9
    let listen = env::var("LISTEN").unwrap_or("127.0.0.1".into());
10
    let port = env::var("PORT").unwrap_or("5000".into());
11
    let port = port
12
        .parse()
13
        .expect(format!("Error parsing port number PORT={}", port).as_str());
14

15
    println!("listening on http://{}:{}", listen, port);
16

17
    HttpServer::new(|| App::new().route("/ping", web::get().to(|| async { "pong!" })))
18
        .bind((listen, port))?
19
        .run()
20
        .await
21
}

数据库准备#

本例使用 Sea-Orm 作为 ORM 框架。首先安装 sea-orm-cli 准备数据库迁移。

1
cargo install sea-orm-cli

Schema first 还是 Entity first?#

SeaORM文档也提到了这个问题。

对于涉及数据库的业务，有一个重要的开发流程问题，那就是先有数据库还是先有代码？.NET EntityFrame Core 的文档给了很好的说明。大多数业务框架推荐 Entity First(Code First)。即先有业务模型，然后去生成数据库。这是因为数据库通常是通过 SQL 管理的，而在有ORM框架的情况下，应当尽可能减少原生SQL操作。

但是SeaORM采用了一个折中的工作流程，Schema First。首先，应当写一个迁移逻辑(用Rust而非SQL)，然后根据这个迁移逻辑去调整数据库，最后从迁移过的数据库生成Entity,也就代码中的Model。这一套流程和EF Core的Code First模式是很像的，只不过EF Core会先从Model的变化生成迁移文件(这些推断并不总是准确的，而且可能造成毁灭性的后果)。另一些ORM框架，比如gorm，它们的自动迁移只会新增而不会修改或删除，为了避免不可挽回的数据丢失，但是这种情况下，修改一个现有字段的约束就会变得困难。事实上，SeaORM的工作模式虽然相比之下更麻烦了一点，但是开发者获得了更多的控制权，而且由于迁移文件也是用Rust代码写的，效率并不会很低。

执行sea-orm-cli migrate init,我们会得到一个新的Crate，名叫migration。然后删掉默认的一个示例迁移文件。

添加 migration Crate 到 WorkSpace#

接下来，修改workspace即根目录的Cargo.toml以包含这个 migration Crate.

1
[workspace]
2
members=["app","migration"] #新增一个migration
3
default-members=["app"]

Migration File#

通过sea-orm-cli migrate generate create_todo_table，可以得到一个以当前时间为前缀，名为create_todo_table的迁移文件。修改其内容如下：

1
use sea_orm_migration::prelude::*;
2

3
#[derive(DeriveMigrationName)]
4
pub struct Migration;
5

6
#[async_trait::async_trait]
7
impl MigrationTrait for Migration {
8
    async fn up(&self, manager: &SchemaManager) -> Result<(), DbErr> {
9
        manager
10
            .create_table(
11
                Table::create()
12
                    .table(Todo::Table)
13
                    .if_not_exists()
14
                    .col(
15
                        ColumnDef::new(Todo::Id)
16
                            .integer()
17
                            .not_null()
18
                            .auto_increment()
19
                            .primary_key(),
20
                    )
21
                    .col(ColumnDef::new(Todo::ExpireAt).date_time().not_null())
22
                    .col(ColumnDef::new(Todo::Content).string())
23
                    .col(ColumnDef::new(Todo::IsFinished).boolean().not_null())
24
                    .to_owned(),
25
            )
26
            .await
27
    }
28

29
    async fn down(&self, manager: &SchemaManager) -> Result<(), DbErr> {
30
        manager
31
            .drop_table(Table::drop().table(Todo::Table).to_owned())
32
            .await
33
    }
34
}
35

36
/// Learn more at https://docs.rs/sea-query#iden
37
#[derive(Iden)]
38
enum Todo {
39
    Table,
40
    Id,
41
    ExpireAt,
42
    Content,
43
    IsFinished,
44
}

这样，就定义好了一次迁移的逻辑。up方法新建了一张表，并设置了字段的类型和约束。down方法应当是up的逆过程，由于up是新建表，因此down直接删除表就可以了。

执行迁移#

接下来，我们要将写好的迁移文件应用到数据库。可以在应用程序中完成这一步，也可以使用sea-orm-cli完成。migration Crate是一个 bin crate，它编译的结果就是一个负责执行迁移的程序。sea-orm-cli提供了一个捷径来编译并执行迁移。如果采用sea-orm-cli手动迁移，要注意为migrationcrate配置一个数据库驱动，就像appcrate一样，本文以sqlite为例。需要用到环境变量DATABASE_URL，由于我们已经使用了dotenvy来管理环境变量，而sea-orm-cli也是支持这个的，因此直接在.env文件添加一行：

1
DATABASE_URL="sqlite:./sqlite.db?mode=rwc"

1
[package]
2
name = "migration"
3
# ......
4
[dependencies.sea-orm-migration]
5
version = "^0.10.0"
6
features = [
7
  # Enable at least one `ASYNC_RUNTIME` and `DATABASE_DRIVER` feature if you want to run migration via CLI.
8
  # View the list of supported features at https://www.sea-ql.org/SeaORM/docs/install-and-config/database-and-async-runtime.
9
  # e.g.
10
  # "runtime-tokio-rustls",  # `ASYNC_RUNTIME` feature
11
  "runtime-tokio-rustls",  # de-comment this line so that we have an async runtime
12
  # "sqlx-postgres",         # `DATABASE_DRIVER` feature
13
  "sqlx-sqlite" # Add this line so that we can connect to a sqlite db
14
]

然后，执行sea-orm-cli migrate，等待编译并运行成功后，数据库就迁移完成了！

生成 Entity#

要执行 CRUD，当然还需要 Entity 定义，可以用sea-orm-cli从线上数据库生成。注意是从数据库生成，而不是从前面编写的 migration 文件。因此务必确保所连接到的数据库Schema是最新的！执行sea-orm-cli generate entity，会发现生成了三个文件，默认是一个mod的构造，即mod.rs,prelude.rs以及若干个 Entity 定义，由于我们只有一个todo，因此也只有一个todo.rs。

不过默认生成在了当前目录下，显然不太合理。你可以根据自己的需要调整目录结果，通过-o参数来指定生成位置。

CRUD API#

然后，我们就可以开始进入无聊的CRUD环节了。无聊的代码就不贴了，详见github.com/artiga033/rust_rest_api_demo