Rust WebAPI 作成入門

2024-2025 Shunsuke Watanabe

このチュートリアルについて

このチュートリアルはRustでREST APIを作成する過程を通じて、EventStormingでまとめたドメイン知識をコードに起こす基礎的な内容に触れてもらうことを目的としています。

👨‍💻サンプルコード → https://github.com/craftgear/rust_web_api_tutorial

discord → https://discord.gg/3havwjWGsw

bluesky → https://bsky.app/profile/craftgear.bsky.social

📝 blog → https://craftgear.github.io/posts/

💡このチュートリアルは Web API作成入門の内容をRustで置き換えたものです。

1. 開発資料

EventStorming

https://www.youtube.com/watch?v=mLXQIYEwK24
https://github.com/SAP/curated-resources-for-domain-driven-design/blob/main/detailedinfo/eventstorming.md
イベントストーミングの利点3つ

Big Picture

スクリーンショット 2024-11-03 10.34.08.png

Design Level

design level.png

Onion Architecture

https://jeffreypalermo.com/2008/07/the-onion-architecture-part-1/
オニオンアーキテクチャのルール

オニオンアーキテクチャ.png

その他の3層アーキテクチャ

Clean Architecture
- https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html
Hexagonal Architecture
- https://alistair.cockburn.us/hexagonal-architecture/

◆

2. 開発環境構築

対象環境

macOS
Rust 1.8 〜

Rust

バージョン確認

1
❯ rustc --version
2
rustc 1.84.0 (9fc6b4312 2025-01-07)

SQLite3

sqlite3が使えることを確認

1
❯ sqlite3 --version
2
3.22.0 2018-01-22 18:45:57 0c55d179733b46d8d0ba4d88e01a25e10677046ee3da1d5b1581e86726f2alt2

新しいプロジェクトの作成

初期化
```
1
cargo new rust-web-api
```
コードフォーマッタとLinterのインストール
```
1
rustup component add clippy rustfmt rust-analyzer
```

◆

3. ドメインモデル

必要なcrateをインストール

1
cargo add -F serde/derive serde serde-json
2
cargo add -F chrono/serde chrono
3
cargo add thiserror

/src/todo/domain.rs を作成、型を定義

1
use chrono::{DateTime, Local};
2
use serde::{Deserialize, Serialize};
3

4
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
5
pub struct TodoId(pub usize);
6

7
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
8
pub struct Todo {
9
    pub id: TodoId,
10
    pub title: String,
11
    pub done: bool,
12
    pub done_at: Option<DateTime<Local>>,
13
}

新しく追加するTodoには id がないので、 NewTodo という型を追加する。あわせてこのドメインのエラーを定義する。

1
#[derive(PartialEq, Debug, Serialize, Deserialize)]
2
pub struct NewTodo {
3
    pub title: String,
4
    #[serde(default)]
5
    pub is_done: Option<bool>,
6
    #[serde(default)]
7
    pub done_at: Option<DateTime<Local>>,
8
}
9

10
impl NewTodo {
11
   pub fn parse(title: &str) -> Result<Self, TodoErr> {
12
       let data = format!(
13
           r#"{{
14
               "title": "{}"
15
           }}"#,
16
           title
17
       );
18
       serde_json::from_str(&data).map_err(|e| TodoErr::ParseNewTodoFailure(e.to_string()))
19
   }
20
}
21

22
#[derive(PartialEq, thiserror::Error, Debug)]
23
pub enum TodoErr {
24
   #[error("parse new todo failed: {0}")]
25
   ParseNewTodoFailure(String),
26
}

テスト作成

1
#[cfg(test)]
2
mod tests {
3
    use super::*;
4

5
    #[test]
6
    fn test_parse_new_todo() {
7
        let new_todo = NewTodo::parse("fuga").unwrap();
8

9
        let expected_new_todo = NewTodo {
10
            title: "fuga".to_string(),
11
            is_done: None,
12
            done_at: None,
13
        };
14
        assert_eq!(new_todo, expected_new_todo);
15
    }
16
}

src/todo/domain.rs を src/main.rs でインポートするため、 src/todo.rs を作成
```
1
 pub mod domain;
```

src/main.rs で todoモジュールを読み込み

1
mod todo;
2

3
fn main() {
4
    println!("Hello, world!");
5
}

テスト実行
```
1
cargo test
```

◆

4. ビジネスロジック

タイトルのチェックをNewTodoの parse に追加

1
impl NewTodo {
2
    pub fn parse(title: &str) -> Result<Self, TodoErr> {
3
        if title.trim().is_empty() {
4
            return Err(TodoErr::ParseNewTodoFailure(
5
                "title should have at least one character".to_string(),
6
            ));
7
        }
8
        let data = format!( => String
9
            r#"{{
10
            "title": "{}"
11
        }}"#,
12
            title
13
        );
14
        serde_json::from_str(&data).map_err(|e| TodoErr::ParseNewTodoFailure(e.to_string()))
15
    }
16
}

完了チェックの関数を追加

1
impl Todo {
2
    pub fn is_complete(&self) -> bool {
3
        self.done
4
    }
5
}

テスト追加

1
#[cfg(test)]
2
mod tests {
3
    use super::*;
4

5
...
6

7
    #[test]
8
    fn test_title_should_not_be_empty() {
9
        let err = NewTodo::parse("").unwrap_err();
10

11
        assert_eq!(
12
            err,
13
            TodoErr::ParseNewTodoFailure("title should have at least one character".to_string())
14
        )
15
    }
16

17
    #[test]
18
    fn test_is_complete() {
19
        let todo = Todo {
20
            id: TodoId(1),
21
            title: "this is done".to_string(),
22
            done: true,
23
            done_at: None,
24
        };
25

26
        let result = todo.is_complete();
27
        assert!(result);
28
    }
29
}

◆

5. ユースケース

必要なcrateを追加
```
1
cargo add -F tokio/full tokio
```

/src/todo/usecase.rs を作成

1
use crate::todo::domain::*;
2

3
pub async fn read_todos<T: TodoRepository>(
4
    repository: T,
5
    offset: usize,
6
    limit: usize,
7
) -> Result<Vec<Todo>, TodoErr> {
8
    todo!()
9
}
10

11
pub async fn create_todo<T: TodoRepository>(
12
    repository: T, title: &str
13
) -> Result<Todo, TodoErr> {
14
    todo!()
15
}
16

17
pub async fn complete_todo<T: TodoRepository>(
18
    repository: T, id: TodoId
19
) -> Result<Todo, TodoErr> {
20
    todo!()
21
}

/src/todo/domain.rs にリポジトリのトレイトを追加

1
pub trait TodoRepository {
2
    async fn select_all(&self, offset: usize, limit: usize) -> Result<Vec<Todo>, TodoErr>;
3
    async fn select_by_id(&self, id: TodoId) -> Result<Todo, TodoErr>;
4
    async fn insert(&self, todo: NewTodo) -> Result<Todo, TodoErr>;
5
    async fn set_completed(&self, id: TodoId) -> Result<Todo, TodoErr>;
6
}

/src/todo/domain.rs にユースケースのエラーを追加

1
#[derive(PartialEq, thiserror::Error, Debug)]
2
pub enum TodoErr {
3
    #[error("parse new todo failed: {0}")]
4
    ParseNewTodoFailure(String),
5
    #[error("usecase error: {0}")]
6
    UsecaseErr(String),
7
}

1で定義したユースケースの実装

1
pub async fn read_todos<T: TodoRepository>(
2
    repository: T,
3
    offset: usize,
4
    limit: usize,
5
) -> Result<Vec<Todo>, TodoErr> {
6
    repository.select_all(offset, limit).await
7
}
8

9
pub async fn create_todo<T: TodoRepository>(repository: T, title: &str) -> Result<Todo, TodoErr> {
10
    let new_todo = NewTodo::parse(title)?;
11
    let result = repository.insert(new_todo).await?;
12
    Ok(result)
13
}
14

15
pub async fn complete_todo<T: TodoRepository>(repository: T, id: TodoId) -> Result<Todo, TodoErr> {
16
    let todo = repository.select_by_id(id.clone()).await?;
17
    if todo.is_complete() {
18
        return Ok(todo);
19
    }
20
    repository.set_completed(id).await
21
}

ユースケースのテストを追加

1
mod tests {
2
    use super::*;
3
    use chrono::Local;
4

5
    #[allow(dead_code)]
6
    struct MockRepository {}
7

8
    impl TodoRepository for MockRepository {
9
        #[allow(unused_variables)]
10
        async fn select_all(&self, offset: usize, number: usize) -> Result<Vec<Todo>, TodoErr> {
11
            Ok(vec![Todo {
12
                id: TodoId(1),
13
                title: "Test todo".to_string(),
14
                done: false,
15
                done_at: None,
16
            }])
17
        }
18
        async fn select_by_id(&self, id: TodoId) -> Result<Todo, TodoErr> {
19
            if id.0 == 999 {
20
                return Err(TodoErr::UsecaseErr("Todo not found".to_string()));
21
            }
22
            if id.0 == 2 {
23
                 return Ok(Todo {
24
                     id: id.clone(),
25
                     title: "Test completed todo".to_string(),
26
                     done: true,
27
                     done_at: Some(Local::now()),
28
                 });
29
            }
30
            Ok(Todo {
31
                id: id.clone(),
32
                title: "Test todo".to_string(),
33
                done: false,
34
                done_at: None,
35
            })
36
        }
37
        async fn insert(&self, todo: NewTodo) -> Result<Todo, TodoErr> {
38
            Ok(Todo {
39
                id: TodoId(1),
40
                title: todo.title,
41
                done: false,
42
                done_at: None,
43
            })
44
        }
45
        async fn set_completed(&self, id: TodoId) -> Result<Todo, TodoErr> {
46
            Ok(Todo {
47
                id: id.clone(),
48
                title: "Test todo".to_string(),
49
                done: true,
50
                done_at: Some(Local::now()),
51
            })
52
        }
53
    }
54

55
    #[tokio::test]
56
    async fn test_read_todos() {
57
        let mock_repo = MockRepository {};
58
        let result = read_todos(mock_repo, 1, 10).await;
59
        assert!(result.is_ok());
60
        let todos = result.unwrap();
61
        assert_eq!(todos.len(), 1);
62
        assert_eq!(todos[0].id, TodoId(1));
63
        assert_eq!(todos[0].title, "Test todo");
64
        assert!(!todos[0].done);
65
        assert!(todos[0].done_at.is_none());
66
    }
67

68
    #[tokio::test]
69
    async fn test_create_todo() {
70
        let mock_repo = MockRepository {};
71
        let result = create_todo(mock_repo, "New task").await;
72
        assert!(result.is_ok());
73
        let todo = result.unwrap();
74
        assert_eq!(todo.id, TodoId(1));
75
        assert_eq!(todo.title, "New task");
76
        assert!(!todo.done);
77
        assert!(todo.done_at.is_none());
78
    }
79

80
    #[tokio::test]
81
    async fn test_complete_todo() {
82
        let mock_repo = MockRepository {};
83
        let result = complete_todo(mock_repo, TodoId(1)).await;
84
        assert!(result.is_ok());
85
        let todo = result.unwrap();
86
        assert_eq!(todo.id, TodoId(1));
87
        assert_eq!(todo.title, "Test todo");
88
        assert!(todo.done);
89
        assert!(todo.done_at.is_some());
90
    }
91

92
    #[tokio::test]
93
    async fn test_completed_todo() {
94
        let mock_repo = MockRepository {};
95
        let result = complete_todo(mock_repo, TodoId(2)).await;
96
        assert!(result.is_ok());
97
        let todo = result.unwrap();
98
        assert_eq!(todo.id, TodoId(2));
99
        assert_eq!(todo.title, "Test completed todo");
100
        assert!(todo.done);
101
        assert!(todo.done_at.is_some());
102
    }
103

104
    #[tokio::test]
105
    async fn test_complete_todo_not_found() {
106
        let mock_repo = MockRepository {};
107
        let result = complete_todo(mock_repo, TodoId(999)).await;
108
        assert!(result.is_err());
109
        let err = result.unwrap_err();
110
        assert_eq!(err, TodoErr::UsecaseErr("Todo not found".to_string()));
111
    }
112
}

テストカバレッジを測定する

1
cargo install cargo-tarpaulin
2
cargo tarpaulin --out html

◆

6. Httpサーバー

必要なcrateをインストール
```
1
cargo add -F macros axum
```

/src/todo/route.rs を作成し、Todo一覧取得のエンドポイントを定義

1
use axum::{
2
    extract::{Query},
3
    http::StatusCode,
4
    response::{IntoResponse, Response},
5
    routing::{get},
6
    Json, Router,
7
};
8
use serde::Deserialize;
9

10
use super::domain::{Todo, TodoErr};
11
use super::infra::TodoRepo;
12
use super::usecase::{read_todos};
13

14
impl IntoResponse for TodoErr {
15
    fn into_response(self) -> Response {
16
        let status_code = match &self {
17
            TodoErr::UsecaseErr(msg) if msg.contains("not found") => StatusCode::NOT_FOUND,
18
            _ => StatusCode::INTERNAL_SERVER_ERROR,
19
        };
20
        (status_code, self.to_string()).into_response()
21
    }
22
}
23

24
pub fn get_todo_router() -> Router {
25
    Router::new().route("/", get(list))
26
}
27

28
#[derive(Debug, Deserialize)]
29
struct Pagination {
30
    page: Option<usize>,
31
    limit: Option<usize>,
32
}
33

34
async fn list(
35
    Query(pagination): Query<Pagination>,
36
) -> Result<Json<Vec<Todo>>, TodoErr> {
37
    let page = pagination.page.unwrap_or(1);
38
    let limit = pagination.limit.unwrap_or(10);
39

40
    let offset = if page < 1 { 0 } else { (page - 1) * limit };
41

42
    let repo = TodoRepo::new()?;
43
    let result = read_todos(repo, offset, limit).await?;
44
    Ok(Json(result))
45
}

/src/todo/infra.rs を作成し、TodoRepoのスケルトンを作成

1
use crate::todo::domain::{Todo, TodoErr, TodoId, TodoRepository};
2

3
pub struct TodoRepo {
4
}
5

6
impl TodoRepo {
7
    pub fn new() -> Result<Self, TodoErr> {
8
        Ok(Self { })
9
    }
10
}
11

12
fn create_dummy_todo() -> Todo {
13
    Todo {
14
        id: TodoId(1),
15
        title: "dummy".to_string(),
16
        done: false,
17
        done_at: None,
18
    }
19
}
20

21
impl TodoRepository for TodoRepo {
22
    async fn select_all(&self, offset: usize, limit: usize) -> Result<Vec<Todo>, TodoErr> {
23
        Ok(vec![create_dummy_todo()])
24
    }
25

26
    async fn select_by_id(&self, id: crate::todo::domain::TodoId) -> Result<Todo, TodoErr> {
27
        Ok(create_dummy_todo())
28
    }
29

30
    async fn insert(&self, todo: crate::todo::domain::NewTodo) -> Result<Todo, TodoErr> {
31
        Ok(create_dummy_todo())
32
    }
33

34
    async fn set_completed(
35
        &self,
36
        id: crate::todo::domain::TodoId,
37
    ) -> Result<crate::todo::domain::Todo, TodoErr> {
38
        Ok(create_dummy_todo())
39
    }
40
}

/src/main.rs でaxumを呼び出し

1
mod todo;
2

3
use axum::Router;
4

5
use crate::todo::route::get_todo_router;
6

7
#[tokio::main]
8
async fn main() {
9
    let router = Router::new().nest("/todos", get_todo_router());
10

11
    let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap();
12
    axum::serve(listener, router).await.unwrap()
13
}

cargo run でサーバーを起動

src/route.rs に postとpatchを追加

1
use axum::{
2
    extract::{
3
        Path,
4
        Query,
5
    },
6
    http::StatusCode,
7
    response::{IntoResponse, Response},
8
    routing::{get, patch, post},
9
    Json, Router,
10
};
11

12
...
13

14
use super::usecase::{complete_todo, create_todo, read_todos};
15

16
...
17

18
use super::domain::{NewTodo, Todo, TodoErr, TodoId};
19

20
...
21

22
pub fn get_todo_router() -> Router {
23
    Router::new()
24
        .route("/", get(list))
25
        .route("/", post(create))
26
        .route("/{todo_id}", patch(complete))
27
}
28

29
...
30

31
async fn create(
32
    Json(todo): Json<NewTodo>,
33
) -> Result<Json<Todo>, TodoErr> {
34
    let repo = TodoRepo::new()?;
35
    let result = create_todo(repo, &todo.title).await?;
36
    Ok(Json(result))
37
}
38

39
async fn complete(
40
    Path(todo_id): Path<TodoId>,
41
) -> Result<Json<Todo>, TodoErr> {
42
    let repo = TodoRepo::new()?;
43
    let result = complete_todo(repo, todo_id).await?;
44
    Ok(Json(result))
45
}

cargo run でWebサーバーを立ち上げ、 http://localhost:3000/todos/ にアクセス

◆

7. リポジトリ

必要なcrateのインストール

1
cargo add -F sqlite -F macros -F runtime-tokio sqlx
2
cargo add dotenv

schema.sql を作成

1
CREATE TABLE todo (
2
  id INTEGER PRIMARY KEY AUTOINCREMENT,
3
  title TEXT NOT NULL,
4
  done INTEGER DEFAULT 0,
5
  done_at INTEGER
6
);

.env ファイルを作成
```
1
DATABASE_URL=sqlite:database.sqlite
```

データベースの作成

1
cat schema.sql | sqlite3 database.sqlite

src/db.rs ファイルを作成し、DBに接続

1
use sqlx::{sqlite::SqlitePoolOptions, Pool, Sqlite};
2

3
pub type Db = Pool<Sqlite>;
4

5
pub async fn get_db_connection() -> Db {
6
    let db_path = std::env::var("DATABASE_URL").expect("*** No DATABASE_URL env var");
7

8
    SqlitePoolOptions::new()
9
        .max_connections(5)
10
        .connect(&db_path)
11
        .await
12
        .expect("cannot connect to database")
13
}

src/main.rs でアプリケーションステートにDB接続を保存

1
mod db;
2
mod todo;
3

4
use axum::Router;
5
use dotenv::dotenv;
6

7
use crate::todo::route::get_todo_router;
8
use db::{get_db_connection, Db};
9

10
#[derive(Clone)]
11
struct AppState {
12
    db: Db,
13
}
14

15
#[tokio::main]
16
async fn main() {
17
    dotenv().ok();
18
    let db = get_db_connection().await;
19

20
    let state = AppState { db };
21
    let router = Router::<AppState>::new()
22
        .nest("/todos", get_todo_router())
23
        .with_state(state);
24

25
    let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap();
26
    axum::serve(listener, router).await.unwrap()
27
}

src/todo/route.rs でAppStateを使ってリポジトリを作成

1
use axum::{
2
    extract::{Path, Query, State},
3
    http::StatusCode,
4
    response::{IntoResponse, Response},
5
    routing::{get, patch, post},
6
    Json, Router,
7
};
8
use serde::Deserialize;
9

10
use super::domain::{NewTodo, Todo, TodoErr, TodoId};
11
use super::infra::TodoRepo;
12
use super::usecase::{complete_todo, create_todo, read_todos};
13
use crate::AppState;
14

15
impl IntoResponse for TodoErr {
16
    fn into_response(self) -> Response {
17
        let status_code = match &self {
18
            TodoErr::UsecaseErr(msg) if msg.contains("not found") => StatusCode::NOT_FOUND,
19
            _ => StatusCode::INTERNAL_SERVER_ERROR,
20
        };
21
        (status_code, self.to_string()).into_response()
22
    }
23
}
24

25
pub fn get_todo_router() -> Router<AppState> {
26
    Router::<AppState>::new()
27
        .route("/", get(list))
28
        .route("/", post(create))
29
        .route("/{todo_id}", patch(complete))
30
}
31

32
#[derive(Debug, Deserialize)]
33
struct Pagination {
34
    page: Option<usize>,
35
    limit: Option<usize>,
36
}
37

38
async fn list(
39
    State(state): State<AppState>,
40
    Query(pagination): Query<Pagination>,
41
) -> Result<Json<Vec<Todo>>, TodoErr> {
42
    let page = pagination.page.unwrap_or(1);
43
    let limit = pagination.limit.unwrap_or(10);
44

45
    let offset = if page < 1 { 0 } else { (page - 1) * limit };
46

47
    let repo = TodoRepo::new(state.db)?;
48
    let result = read_todos(repo, offset, limit).await?;
49
    Ok(Json(result))
50
}
51

52
async fn create(
53
    State(state): State<AppState>,
54
    Json(todo): Json<NewTodo>,
55
) -> Result<Json<Todo>, TodoErr> {
56
    let repo = TodoRepo::new(state.db)?;
57
    let result = create_todo(repo, &todo.title).await?;
58
    Ok(Json(result))
59
}
60

61
async fn complete(
62
    State(state): State<AppState>,
63
    Path(todo_id): Path<TodoId>,
64
) -> Result<Json<Todo>, TodoErr> {
65
    let repo = TodoRepo::new(state.db)?;
66
    let result = complete_todo(repo, todo_id).await?;
67
    Ok(Json(result))
68
}

src/todo/infra.rs でDb接続を受け取り、クエリを発行する

1
use crate::db::Db;
2
use crate::todo::domain::{Todo, TodoErr, TodoId, TodoRepository};
3
use chrono::{Local, TimeZone};
4

5
pub struct TodoRepo {
6
    db: Db,
7
}
8

9
impl TodoRepo {
10
    pub fn new(db: Db) -> Result<Self, TodoErr> {
11
        Ok(Self { db })
12
    }
13
}
14

15
#[derive(sqlx::FromRow)]
16
struct TodoRow {
17
    id: i64,
18
    title: String,
19
    done: Option<i64>,
20
    done_at: Option<i64>,
21
}
22

23
impl From<TodoRow> for Todo {
24
    fn from(value: TodoRow) -> Self {
25
        Self {
26
            id: TodoId(value.id as usize),
27
            title: value.title,
28
            done: if let Some(done) = value.done {
29
                done > 0
30
            } else {
31
                false
32
            },
33

34
            done_at: if let Some(timestamp) = value.done_at {
35
                Local.timestamp_opt(timestamp, 0).single()
36
            } else {
37
                None
38
            },
39
        }
40
    }
41
}
42

43
impl TodoRepository for TodoRepo {
44
    async fn select_all(&self, offset: usize, limit: usize) -> Result<Vec<Todo>, TodoErr> {
45
        let offset = offset as i64;
46
        let limit = limit as i64;
47
        let rows = sqlx::query_as!(
48
            TodoRow,
49
            r#"
50
                SELECT id, title, done, done_at
51
                FROM todo
52
                LIMIT ? OFFSET ?
53
                "#,
54
            limit,
55
            offset
56
        )
57
        .fetch_all(&self.db)
58
        .await?;
59

60
        let todos = rows
61
            .into_iter()
62
            .map(|row| row.into())
63
            .collect::<Vec<Todo>>();
64

65
        Ok(todos)
66
    }
67

68
    async fn select_by_id(&self, id: crate::todo::domain::TodoId) -> Result<Todo, TodoErr> {
69
        let id = id.0 as i64;
70
        let row = sqlx::query_as!(
71
            TodoRow,
72
            r#"
73
                SELECT id as "id: _", title, done, done_at
74
                FROM todo
75
                WHERE id = ?
76
                "#,
77
            id
78
        )
79
        .fetch_one(&self.db)
80
        .await?;
81
        Ok(row.into())
82
    }
83

84
    async fn insert(&self, todo: crate::todo::domain::NewTodo) -> Result<Todo, TodoErr> {
85
        let row = sqlx::query_as!(
86
            TodoRow,
87
            r#"
88
                INSERT INTO todo (title)
89
                VALUES (?)
90
                RETURNING id, title, done, done_at
91
                "#,
92
            todo.title
93
        )
94
        .fetch_one(&self.db)
95
        .await?;
96
        Ok(row.into())
97
    }
98

99
    async fn set_completed(
100
        &self,
101
        id: crate::todo::domain::TodoId,
102
    ) -> Result<crate::todo::domain::Todo, TodoErr> {
103
        let id = id.0 as i64;
104
        let now = Local::now().timestamp();
105
        let row = sqlx::query_as!(
106
            TodoRow,
107
            r#"
108
                UPDATE todo
109
                SET done = TRUE, done_at = ?
110
                WHERE id = ?
111
                RETURNING id, title, done, done_at
112
                "#,
113
            now,
114
            id
115
        )
116
        .fetch_one(&self.db)
117
        .await?;
118
        Ok(row.into())
119
    }
120
}

src/todo/domain.rs にエラータイプを追加

1
 #[derive(PartialEq, thiserror::Error, Debug)]
2
 pub enum TodoErr {
3
     #[error("parse new todo failed: {0}")]
4
     ParseNewTodoFailure(String),
5
     #[error("usecase error: {0}")]
6
     UsecaseErr(String),
7
     #[error("failed to query data: {0}")]
8
     QueryErr(String),
9
     #[error("something went wrong: {0}")]
10
     UnknownErr(String),
11
 }

src/todo/infra.rs にエラー変換処理を追加

1
impl From<sqlx::Error> for TodoErr {
2
    fn from(err: sqlx::Error) -> Self {
3
        match err {
4
            sqlx::Error::Database(e) => TodoErr::QueryErr(e.to_string()),
5
            _ => TodoErr::UnknownErr(err.to_string()),
6
        }
7
    }
8
}

◆

8. OpenAPI

必要なクレートをインストール

1
cargo add -F utoipa/axum_extras -F utoipa/chrono utoipa
2
cargo add utoipa-axum
3
cargo add -F axum utoipa-swagger-ui

src/main.rs にOpenAPI定義を追加

1
mod db;
2
mod todo;
3

4
use axum::Router;
5
use dotenv::dotenv;
6
use utoipa::OpenApi;
7
use utoipa_axum::router::OpenApiRouter;
8
use utoipa_swagger_ui::SwaggerUi;
9

10
use db::{get_db_connection, Db};
11
use todo::route::get_todo_router;
12

13
#[derive(Clone)]
14
struct AppState {
15
    db: Db,
16
}
17

18
#[tokio::main]
19
async fn main() {
20
    dotenv().ok();
21
    let db = get_db_connection().await.unwrap();
22

23
    #[derive(OpenApi)]
24
    #[openapi(tags((name = "Awesome Service API")))]
25
    struct ApiDoc;
26

27
    let state = AppState { db };
28
    let (router, api) = OpenApiRouter::with_openapi(ApiDoc::openapi())
29
        .nest("/todo", get_todo_router())
30
        .with_state(state)
31
        .split_for_parts();
32

33
    let router =
34
        router.merge(SwaggerUi::new("/swagger-ui").url("/api-docs/openapi.json", api.clone()));
35

36
    let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap();
37
    axum::serve(listener, router).await.unwrap()
38
}

src/todo/route.rsにOpenAPI定義を追加

1
use axum::{
2
    extract::{Path, Query, State},
3
    http::StatusCode,
4
    response::{IntoResponse, Response},
5
    Json
6
};
7
use serde::Deserialize;
8
use utoipa::IntoParams;
9
use utoipa_axum::{router::OpenApiRouter, routes};
10

11
use super::domain::{NewTodo, Todo, TodoErr, TodoId};
12
use super::infra::TodoRepo;
13
use super::usecase::{complete_todo, create_todo, read_todos};
14
use crate::AppState;
15

16
static TAG_NAME: &str = "Todo";
17

18
impl IntoResponse for TodoErr {
19
    fn into_response(self) -> Response {
20
        let status_code = match &self {
21
            TodoErr::UsecaseErr(msg) if msg.contains("not found") => StatusCode::NOT_FOUND,
22
            _ => StatusCode::INTERNAL_SERVER_ERROR,
23
        };
24
        (status_code, self.to_string()).into_response()
25
    }
26
}
27

28
pub fn get_todo_router() -> OpenApiRouter<AppState> {
29
    OpenApiRouter::<AppState>::new()
30
        .routes(routes!(list, create, complete))
31
}
32

33
#[derive(Debug, Deserialize, IntoParams)]
34
struct Pagination {
35
    page: Option<usize>,
36
    limit: Option<usize>,
37
}
38

39
#[utoipa::path(
40
    tag=TAG_NAME,
41
    get,
42
    path="",
43
    params(
44
        Pagination
45
    ),
46
    responses(
47
        (status=200, description="all todos", body = [Todo])
48
    )
49
)]
50
async fn list(
51
    State(state): State<AppState>,
52
    Query(pagination): Query<Pagination>,
53
) -> Result<Json<Vec<Todo>>, TodoErr> {
54
    let page = pagination.page.unwrap_or(1);
55
    let limit = pagination.limit.unwrap_or(10);
56

57
    let offset = if page < 1 { 0 } else { (page - 1) * limit };
58

59
    let repo = TodoRepo::new(state.db)?;
60
    let result = read_todos(repo, offset, limit).await?;
61
    Ok(Json(result))
62
}
63

64
#[utoipa::path(
65
    tag=TAG_NAME,
66
    post,
67
    path="",
68
    request_body(content=NewTodo),
69
    responses(
70
        (status=200, description="create a todo", body = Todo)
71
    )
72
)]
73
async fn create(
74
    State(state): State<AppState>,
75
    Json(todo): Json<NewTodo>,
76
) -> Result<Json<Todo>, TodoErr> {
77
    let repo = TodoRepo::new(state.db)?;
78
    let result = create_todo(repo, &todo.title).await?;
79
    Ok(Json(result))
80
}
81

82
#[utoipa::path(
83
    tag=TAG_NAME,
84
    patch,
85
    path="/{id}",
86
    params(("id" = TodoId, Path, description = "todo id")),
87
    request_body(content=NewTodo),
88
    responses(
89
        (status=200, description="complete a todo", body = Todo),
90
        (status=404, description="the todo is not found")
91
    )
92
)]
93
async fn complete(
94
    State(state): State<AppState>,
95
    Path(todo_id): Path<TodoId>,
96
) -> Result<Json<Todo>, TodoErr> {
97
    let repo = TodoRepo::new(state.db)?;
98
    let result = complete_todo(repo, todo_id).await?;
99
    Ok(Json(result))
100
}

src/todo/domain.rsにOpenAPI定義を追加

1
use chrono::{DateTime, Local};
2
use serde::{Deserialize, Serialize};
3
use utoipa::ToSchema;
4

5
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize, ToSchema)]
6
pub struct TodoIdpub usize);
7

8
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize, ToSchema)]
9
pub struct Todo {
10
    pub id: TodoId,
11
    pub title: String,
12
    pub done: bool,
13
    pub done_at: Option<DateTime<Local>>,
14
}
15

16
impl Todo {
17
    pub fn is_complete(&self) -> bool {
18
        self.done
19
    }
20
}
21

22
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize, ToSchema)]
23
pub struct NewTodo {
24
    pub title: String,
25
    #[serde(default)]
26
    pub is_done: Option<bool>,
27
    #[serde(default)]
28
    pub done_at: Option<DateTime<Local>>,
29
}
30

31
...

http://localhost:3000/swagger-ui にアクセス