koko_u

<h1 id="%E3%81%93%E3%82%8C%E3%81%8B%E3%82%89%E3%82%84%E3%82%8B%E3%81%93%E3%81%A8" data-line="0" class="code-line">
<a class="header-anchor-link" href="#%E3%81%93%E3%82%8C%E3%81%8B%E3%82%89%E3%82%84%E3%82%8B%E3%81%93%E3%81%A8" aria-hidden="true"></a> これからやること</h1>
<a href="https://actix.rs/" target="_blank" rel="nofollow noopener noreferrer">Actix Web</a> フレームワークを使って簡単な REST API を徐々に作成していきます。
<h2 id="%E4%BB%95%E6%A7%98" data-line="4" class="code-line">
<a class="header-anchor-link" href="#%E4%BB%95%E6%A7%98" aria-hidden="true"></a> 仕様</h2>
仕様は今後変化する。ひとまず書籍を管理するアプリケーションを想定して、最小限次のエントリーポイントを作る
<table data-line="8" class="code-line">
<thead data-line="8" class="code-line">
<tr data-line="8" class="code-line">
<th>method</th>
<th>url</th>
<th>説明</th>
</tr>
</thead>
<tbody data-line="10" class="code-line">
<tr data-line="10" class="code-line">
<td>GET</td>
<td>/api/books</td>
<td>書籍の一覧</td>
</tr>
<tr data-line="11" class="code-line">
<td>GET</td>
<td>/api/books/{id}</td>
<td>指定したIDの書籍</td>
</tr>
<tr data-line="12" class="code-line">
<td>POST</td>
<td>/api/books</td>
<td>書籍を新規に作成</td>
</tr>
<tr data-line="13" class="code-line">
<td>PUT</td>
<td>/api/books/{id}</td>
<td>指定したIDの書籍を更新</td>
</tr>
<tr data-line="14" class="code-line">
<td>DELETE</td>
<td>/api/books/{id}</td>
<td>指定したIDの書籍を削除</td>
</tr>
</tbody>
</table>
よく見かける Web フレームワーク (Laravel とか、Rails とか) であれば、一瞬でできそうな単純なものだが、Rust だと道程は長いぞ。

<h2 id="%E3%81%8A%E3%81%8A%E3%82%88%E3%81%9D%E3%81%AE%E6%AE%B5%E5%8F%96%E3%82%8A%E3%82%92%E6%B1%BA%E3%82%81%E3%82%8B" data-line="0" class="code-line">
<a class="header-anchor-link" href="#%E3%81%8A%E3%81%8A%E3%82%88%E3%81%9D%E3%81%AE%E6%AE%B5%E5%8F%96%E3%82%8A%E3%82%92%E6%B1%BA%E3%82%81%E3%82%8B" aria-hidden="true"></a> おおよその段取りを決める</h2>
<ol data-line="2" class="code-line">
<li data-line="2" class="code-line">Actix Web の雛形を公式サイトなどからコピって動かす</li>
<li data-line="3" class="code-line">ルーティングの設定をして、リクエストを投げたら OK を返す状態にする</li>
<li data-line="4" class="code-line">Swagger UI を設定して、API の仕様が GUI で見えるようにする</li>
<li data-line="5" class="code-line">データベースの準備をして、books テーブルを作る</li>
<li data-line="6" class="code-line">books テーブルに対応した Rust の構造体を作る</li>
<li data-line="7" class="code-line">Rust のコードから books テーブルにアクセスできるようにする</li>
<li data-line="8" class="code-line">ルーティングに対応する実装を順に作成する</li>
<li data-line="9" class="code-line">E2Eテストを書く</li>
</ol>
この順で進む保証はないけど。

<h1 id="%E3%81%BE%E3%81%9A%E3%81%AF%E5%8B%95%E3%81%8F%E9%9B%9B%E5%BD%A2%E3%82%92%E4%BD%9C%E3%82%8B" data-line="0" class="code-line">
<a class="header-anchor-link" href="#%E3%81%BE%E3%81%9A%E3%81%AF%E5%8B%95%E3%81%8F%E9%9B%9B%E5%BD%A2%E3%82%92%E4%BD%9C%E3%82%8B" aria-hidden="true"></a> まずは動く雛形を作る</h1>
アプリケーション名は適当に book-stack とする
<div class="code-block-container"><pre><code class="code-line" data-line="3">$ cargo new --bin book-stack
</code></pre></div><a href="https://actix.rs/docs/getting-started" target="_blank" rel="nofollow noopener noreferrer">Actix Web の Getting Started</a> をそのまま書く
<details><summary>Cargo.toml</summary><div class="details-content"><div class="code-block-container">
<div class="code-block-filename-container">Cargo.toml</div>
<pre class="language-toml"><code class="language-toml code-line" data-line="10">[package]
name = "book-stack"
version = "0.1.0"
edition = "2021"

[dependencies]
actix-web = { version = "4", features = [] }
</code></pre>
</div></div></details>
あとで <code>features</code> は追加するとして、いまは空。
<details><summary>main.rs</summary><div class="details-content"><div class="code-block-container">
<div class="code-block-filename-container">main.rs</div>
<pre class="language-rust"><code class="language-rust code-line" data-line="24">use std::io;

use actix_web::get;
use actix_web::post;
use actix_web::web;
use actix_web::App;
use actix_web::HttpResponse;
use actix_web::HttpServer;
use actix_web::Responder;

#[get("/")]
async fn hello() -&gt; impl Responder {
 HttpResponse::Ok().body("Hello world!")
}

#[post("/echo")]
async fn echo(req_body: String) -&gt; impl Responder {
 HttpResponse::Ok().body(req_body)
}

async fn manual_hello() -&gt; impl Responder {
 HttpResponse::Ok().body("Hey there!")
}

#[actix_web::main]
async fn main() -&gt; io::Result&lt;()&gt; {
 HttpServer::new(|| {
 App::new()
 .service(hello)
 .service(echo)
 .route("/hey", web::get().to(manual_hello))
 })
 .bind(("127.0.0.1", 8080))?
 .run()
 .await?;

 Ok(())
}
</code></pre>
</div></div></details>
基本的には <code>rustfmt</code> のフォーマットそのままで、<code>use</code> を 1行1アイテムに設定している
<code>cargo run</code> で動かして、ためす
<details><summary>リクエストとレスポンス</summary><div class="details-content">
<div class="code-block-container"><pre><code class="code-line" data-line="71">$ xh :8080
HTTP/1.1 200 OK
Content-Length: 12
Date: Fri, 27 Dec 2024 13:20:22 GMT

Hello world!
</code></pre></div>
<div class="code-block-container"><pre><code class="code-line" data-line="80">$ xh POST :8080/echo message="Hello World"
HTTP/1.1 200 OK
Content-Length: 25
Date: Fri, 27 Dec 2024 13:24:52 GMT

{"message":"Hello World"}
</code></pre></div>
<div class="code-block-container"><pre><code class="code-line" data-line="89">$ xh :8080/hey
HTTP/1.1 200 OK
Content-Length: 10
Date: Fri, 27 Dec 2024 13:26:18 GMT

Hey there!
</code></pre></div>
</div></details>

テストでHTTPリクエストを送信する方法は何でもいい。上記では <code>curl</code> の代わりに、rust 製の <a href="https://github.com/ducaale/xh" target="_blank" rel="nofollow noopener noreferrer">xh</a> を使っている
VSCode を使っているのであれば、<a href="https://marketplace.visualstudio.com/items?itemName=humao.rest-client" target="_blank" rel="nofollow noopener noreferrer">Rest Client</a> を使えばよいだろう。リクエストの内容も保存しておけるし。

<h1 id="%E3%82%A8%E3%83%A9%E3%83%BC%E3%82%92%E3%81%BE%E3%81%A8%E3%82%81%E3%82%8B" data-line="0" class="code-line">
<a class="header-anchor-link" href="#%E3%82%A8%E3%83%A9%E3%83%BC%E3%82%92%E3%81%BE%E3%81%A8%E3%82%81%E3%82%8B" aria-hidden="true"></a> エラーをまとめる</h1>
雛形では <code>main</code> の戻り値は <code>io::Result&lt;()&gt;</code> だが、すぐに他のエラーも返却したくなることは明らかなので、エラーをよしなに纏めてくれる crate を足す
定番は <a href="https://github.com/dtolnay/anyhow" target="_blank" rel="nofollow noopener noreferrer">anyhow</a> なんだけど、個人的な趣味により <a href="https://github.com/hashintel/hash/tree/main/libs/error-stack" target="_blank" rel="nofollow noopener noreferrer">error-stack</a> をいつも使っているので、これを使う。
そして標準的なトレイトの実装を肩代りしてくれる <a href="https://github.com/JelteF/derive_more" target="_blank" rel="nofollow noopener noreferrer">derive_more</a> も入れる
<details><summary>Cargo.coml</summary><div class="details-content"><div class="code-block-container">
<div class="code-block-filename-container">Cargo.toml</div>
<pre class="diff-highlight language-diff-rust"><code class="diff-highlight language-diff-rust code-line" data-line="9">actix-web = { version = "4", features = [] }
+ error-stack = { version = "0.5.0", features = [] }
+ derive_more = { version = "1.0.0", features = [
+ "constructor",
+ "display",
+ "error",
+ "from_str",
+ "from",
+ "try_from",
+ "deref_mut",
+ "deref",
+ "into",
+ ] }
</code></pre>
</div></div></details>
<code>derive_more</code> はフィーチャーフラグによって細かく利用する自動実装のコードを絞ることができる。面倒なので最初から沢山入れてるけど、たぶんこんなに要らない。
<details><summary>lib.rs</summary><div class="details-content"><div class="code-block-container">
<div class="code-block-filename-container">lib.rs</div>
<pre class="language-rust"><code class="language-rust code-line" data-line="29">pub mod errors;
</code></pre>
</div></div></details>
<details><summary>errors.rs</summary><div class="details-content"><div class="code-block-container">
<div class="code-block-filename-container">errors.rs</div>
<pre class="language-rust"><code class="language-rust code-line" data-line="35">#[derive(Debug, Copy, Clone, Eq, PartialEq, Default, derive_more::Display)]
#[display("App Error")]
pub struct AppError;

impl error_stack::Context for AppError {}

pub type AppResult&lt;T&gt; = error_stack::Result&lt;T, AppError&gt;;
</code></pre>
</div></div></details>
<ul data-line="46" class="code-line">
<li data-line="46" class="code-line">アプリケーションで発生するエラーの型を纏めるための型を用意する <code>AppError</code>
<ul data-line="47" class="code-line">
<li data-line="47" class="code-line">struct でなくても、enum で作って、最終的なエラーにバリエーションを持たせてもよい</li>
<li data-line="48" class="code-line">最初は <code>AppError</code> ひとつでいいだろ</li>
</ul>
</li>
<li data-line="49" class="code-line">
<code>error_stack::Context</code> を実装することで、任意のエラーを <code>AppError</code> に集約できるようになる</li>
<li data-line="50" class="code-line">
<code>AppResult</code> は毎回エラーの型を書くのが面倒になるので用意したエイリアス</li>
</ul>
<code>main</code> の戻り値を <code>AppResult</code> に変更する
<details><summary>main.rs</summary><div class="details-content"><div class="code-block-container">
<div class="code-block-filename-container">main.rs</div>
<pre class="diff-highlight language-diff-rust"><code class="diff-highlight language-diff-rust code-line" data-line="56">#[actix_web::main]
- async fn main() -&gt; io::Result&lt;()&gt; {
+ async fn main() -&gt; AppResult&lt;()&gt; {
 HttpServer::new(|| {
 App::new()
 .service(hello)
 .service(echo)
 .route("/hey", web::get().to(manual_hello))
 })
- .bind(("127.0.0.1", 8080))?
+ .bind(("127.0.0.1", 8080))
+ .change_context(AppError)?
 .run()
- .await?
+ .await
+ .change_context(AppError)?;

 Ok(())
}
</code></pre>
</div></div></details>
<ul data-line="79" class="code-line">
<li data-line="79" class="code-line">
<a href="https://docs.rs/error-stack/latest/error_stack/trait.ResultExt.html" target="_blank" rel="nofollow noopener noreferrer">error_stack::ResultExt</a> トレイトを <code>Result&lt;T, C&gt;</code> が実装している</li>
<li data-line="80" class="code-line">上記の <code>C</code> は <a href="https://docs.rs/error-stack/latest/error_stack/trait.Context.html" target="_blank" rel="nofollow noopener noreferrer">error_stack::Context</a> を充足しなければならないが、<code>Error</code> で <code>Send</code> で <code>Sync</code> な型なら <code>Context</code> になっているので、おおよその <code>Result</code> 型に対して、<code>change_context</code> が呼び出せて、<code>error_stack::Result&lt;T, AppError&gt;</code> へ変換できる</li>
</ul>

<h2 id="%E3%83%A2%E3%82%B8%E3%83%A5%E3%83%BC%E3%83%AB%E3%81%AE%E5%88%86%E3%81%91%E3%81%8B%E3%81%9F%E3%81%AF%E4%BD%95%E3%81%8C%E3%81%84%E3%81%84%E3%81%AE%E3%81%8B%E5%88%86%E3%81%8B%E3%82%89%E3%82%93%E3%80%82" data-line="0" class="code-line">
<a class="header-anchor-link" href="#%E3%83%A2%E3%82%B8%E3%83%A5%E3%83%BC%E3%83%AB%E3%81%AE%E5%88%86%E3%81%91%E3%81%8B%E3%81%9F%E3%81%AF%E4%BD%95%E3%81%8C%E3%81%84%E3%81%84%E3%81%AE%E3%81%8B%E5%88%86%E3%81%8B%E3%82%89%E3%82%93%E3%80%82" aria-hidden="true"></a> モジュールの分けかたは何がいいのか分からん。</h2>
現状は 1 struct 1 モジュール、1 関数 1 モジュール とめちゃくちゃ細かく分けている
例えば <code>lib.rs</code> の中に <code>models</code> モジュールを作って、さらにその中に <code>book</code> モジュールを作って、その中に <code>Book</code> 構造体を作ったりしている
<div class="code-block-container"><pre><code class="code-line" data-line="6">lib.rs
└ models.rs
 └ book.rs
 (ここに struct Books) 
</code></pre></div>この状態だと、<code>use</code> するとき
<div class="code-block-container"><pre class="language-rust"><code class="language-rust code-line" data-line="15">use crate::models::book::Book;
</code></pre></div>のように長くなるので、models あたりで再エクスポートしている
<div class="code-block-container">
<div class="code-block-filename-container">models.rs</div>
<pre class="language-rust"><code class="language-rust code-line" data-line="21">mod book;
pub use book::Book;

</code></pre>
</div>そうすることで、<code>models</code> に「含まれる」複数のモデル構造体を <code>book.rs</code>, <code>user.rs</code>, <code>category.rs</code> のようなファイルに分けつつ、外側には <code>models::Book</code>, <code>models::User</code>, <code>models::Category</code> のように構造体を公開できる

<h2 id="%E3%83%AB%E3%83%BC%E3%83%86%E3%82%A3%E3%83%B3%E3%82%B0%E3%82%92%E8%A8%AD%E5%AE%9A%E3%81%99%E3%82%8B" data-line="0" class="code-line">
<a class="header-anchor-link" href="#%E3%83%AB%E3%83%BC%E3%83%86%E3%82%A3%E3%83%B3%E3%82%B0%E3%82%92%E8%A8%AD%E5%AE%9A%E3%81%99%E3%82%8B" aria-hidden="true"></a> ルーティングを設定する</h2>
ドキュメントの奥の方にしか書いてないけど、<a href="https://docs.rs/actix-web/latest/actix_web/web/struct.ServiceConfig.html" target="_blank" rel="nofollow noopener noreferrer">ServiceConfig</a> を使うことで、<code>main.rs</code> に記述しているルーティングの設定を外に出せる
<details><summary>main.rs</summary><div class="details-content"><div class="code-block-container">
<div class="code-block-filename-container">main.rs</div>
<pre class="diff-highlight language-diff-rust"><code class="diff-highlight language-diff-rust code-line" data-line="5">#[actix_web::main]
async fn main() -&gt; AppResult&lt;()&gt; {
 HttpServer::new(|| {
 App::new()
 .service(hello)
 .service(echo)
 .route("/hey", web::get().to(manual_hello))
+ .configure(books_route)
 })
 .bind(("127.0.0.1", 8080))
 .change_context(AppError)?
 .run()
 .await
 .change_context(AppError)?;

 Ok(())
}
</code></pre>
</div></div></details>
<details><summary>books_route.rs</summary><div class="details-content"><div class="code-block-container">
<div class="code-block-filename-container">books_route.rs</div>
<pre class="language-rust"><code class="language-rust code-line" data-line="27">pub fn books_route(cfg: &amp;mut web::ServiceConfig) {
 cfg.route("/api/books", web::get().to(list_books));
}

async fn list_books() -&gt; impl Responder {
 "Book List"
}
</code></pre>
</div></div></details>
<code>/api/books</code> のエンドポイントのハンドラはひとまずダミーにして、動作確認を優先。
<div class="code-block-container"><pre><code class="code-line" data-line="40">$ xh :8080/api/books
HTTP/1.1 200 OK
Content-Length: 9
Content-Type: text/plain; charset=utf-8
Date: Fri, 27 Dec 2024 15:07:21 GMT

Book List
</code></pre></div>よさそうなので、残りを書く。ハンドラはぜんぶダミー
<details><summary>books_route.rs</summary><div class="details-content"><div class="code-block-container">
<div class="code-block-filename-container">books_route.rs</div>
<pre class="language-rust"><code class="language-rust code-line" data-line="52">
pub fn books_route(cfg: &amp;mut web::ServiceConfig) {
 cfg.route("/api/books", web::get().to(list_books))
 .route("/api/books/{id}", web::get().to(get_book))
 .route("/api/books", web::post().to(create_book))
 .route("/api/books/{id}", web::put().to(update_book))
 .route("/api/books/{id}", web::delete().to(delete_book));
}

// ハンドラの実装は省略
</code></pre>
</div></div></details>

<h2 id="%E3%83%AB%E3%83%BC%E3%83%86%E3%82%A3%E3%83%B3%E3%82%B0%E3%81%AE%E5%AE%9A%E7%BE%A9%E3%82%92%E3%83%AA%E3%83%95%E3%82%A1%E3%82%AF%E3%82%BF%E3%83%AA%E3%83%B3%E3%82%B0" data-line="0" class="code-line">
<a class="header-anchor-link" href="#%E3%83%AB%E3%83%BC%E3%83%86%E3%82%A3%E3%83%B3%E3%82%B0%E3%81%AE%E5%AE%9A%E7%BE%A9%E3%82%92%E3%83%AA%E3%83%95%E3%82%A1%E3%82%AF%E3%82%BF%E3%83%AA%E3%83%B3%E3%82%B0" aria-hidden="true"></a> ルーティングの定義をリファクタリング</h2>
ルーティングの <code>/api/books</code> 部分の重複を解消する
<a href="https://actix.rs/docs/url-dispatch#scoping-routes" target="_blank" rel="nofollow noopener noreferrer">Scoping Route</a> を参考にして
<details><summary>books_route.rs</summary><div class="details-content"><div class="code-block-container">
<div class="code-block-filename-container">books_route.rs</div>
<pre class="language-rust"><code class="language-rust code-line" data-line="7">pub fn books_route(cfg: &amp;mut web::ServiceConfig) {
 cfg.service(
 web::scope("/api/books")
 .route("", web::get().to(list_books))
 .route("/{id}", web::get().to(get_book))
 .route("", web::post().to(create_book))
 .route("/{id}", web::put().to(update_book))
 .route("/{id}", web::delete().to(delete_book))
 );
}
</code></pre>
</div></div></details>
<code>/api</code> の下に <code>books</code> や <code>categories</code> のようなルーティングが増えたときは、更に <code>api_route.rs</code> を作って
<div class="code-block-container"><pre class="language-rust"><code class="language-rust code-line" data-line="23">pub fn api_route(cfg: &amp;mut web::ServiceConfig) {
 cfg.service(
 web::scope("/api")
 .configure(books_route)
 .configure(categories_route) 
 );
}
</code></pre></div>のようにして、<code>books_route</code> や <code>categories_route</code> では <code>/api</code> の下のルーティングの定義をすることで機能ごとに分割して徐々に実装することができる

<h2 id="%E3%82%B5%E3%83%B3%E3%83%97%E3%83%AB%E3%81%AE%E3%83%AB%E3%83%BC%E3%83%88%E3%82%92%E5%89%8A%E9%99%A4" data-line="0" class="code-line">
<a class="header-anchor-link" href="#%E3%82%B5%E3%83%B3%E3%83%97%E3%83%AB%E3%81%AE%E3%83%AB%E3%83%BC%E3%83%88%E3%82%92%E5%89%8A%E9%99%A4" aria-hidden="true"></a> サンプルのルートを削除</h2>
最初に Actix Web のサイトからコピーした hello ハンドラなどを main.rs から削除する
<details><summary>main.rs</summary><div class="details-content"><div class="code-block-container">
<div class="code-block-filename-container">main.rs</div>
<pre class="language-rust"><code class="language-rust code-line" data-line="5">#[actix_web::main]
async fn main() -&gt; AppResult&lt;()&gt; {
 HttpServer::new(|| App::new().configure(api::api_route))
 .bind(("127.0.0.1", 8080))
 .change_context(AppError)?
 .run()
 .await
 .change_context(AppError)?;

 Ok(())
}

</code></pre>
</div></div></details>

<h2 id="%E3%83%8F%E3%83%B3%E3%83%89%E3%83%A9%E3%81%AE%E3%83%80%E3%83%9F%E3%83%BC%E5%AE%9F%E8%A3%85%E3%81%AE%E3%82%B7%E3%82%B0%E3%83%8D%E3%83%81%E3%83%A3%E3%83%BC%E3%82%92%E6%B1%BA%E5%AE%9A%E3%81%99%E3%82%8B" data-line="0" class="code-line">
<a class="header-anchor-link" href="#%E3%83%8F%E3%83%B3%E3%83%89%E3%83%A9%E3%81%AE%E3%83%80%E3%83%9F%E3%83%BC%E5%AE%9F%E8%A3%85%E3%81%AE%E3%82%B7%E3%82%B0%E3%83%8D%E3%83%81%E3%83%A3%E3%83%BC%E3%82%92%E6%B1%BA%E5%AE%9A%E3%81%99%E3%82%8B" aria-hidden="true"></a> ハンドラのダミー実装のシグネチャーを決定する</h2>
<code>books_route.rs</code> になぐり書きしたダミーのハンドラを別ファイルに出す
<details><summary>モジュール構成</summary><div class="details-content"><div class="code-block-container"><pre><code class="code-line" data-line="5">lib.rs
└ handlers.rs
 └ books.rs
 └ list.rs ( list_books ハンドラをコピー)
 └ get.rs ( get_book ハンドラをコピー)
 └ post.rs ( create_book ハンドラをコピー)
 └ put.rs ( update_book ハンドラをコピー)
 └ delete.rs ( delete_book ハンドラをコピー)
</code></pre></div></div></details>
<code>books_routes.rs</code> は上記のハンドラを use するように変更
<details><summary>books_route.rs</summary><div class="details-content"><div class="code-block-container">
<div class="code-block-filename-container">books_route.rs</div>
<pre class="diff-highlight language-diff-rust"><code class="diff-highlight language-diff-rust code-line" data-line="20">use actix_web::web;

+ use crate::handlers::books::*;

pub fn books_route(cfg: &amp;mut web::ServiceConfig) {

</code></pre>
</div></div></details>

<h2 id="list_books" data-line="0" class="code-line">
<a class="header-anchor-link" href="#list_books" aria-hidden="true"></a> list_books</h2>
書籍の一覧は URL パスのパラメータもないし、リクエストボディも空なので、シグネチャーはそのまま。
戻り値が書籍の一覧なので、<code>Book</code> 構造体を用意しよう
<details><summary>book.rs</summary><div class="details-content"><div class="code-block-container">
<div class="code-block-filename-container">book.rs</div>
<pre class="language-rust"><code class="language-rust code-line" data-line="7">#[derive(Debug, Clone, Eq, PartialEq)]
pub struct Book {
 pub id: i64,
 pub title: String,
 pub author: String,
 pub published_on: time::Date,
}
</code></pre>
</div></div></details>
日付を扱いたいので <a href="https://time-rs.github.io/" target="_blank" rel="nofollow noopener noreferrer">time</a> クレートを使う。<a href="https://crates.io/crates/chrono" target="_blank" rel="nofollow noopener noreferrer">chrono</a>でもいいけど、ISO8601 形式の書式をサポートしているので <code>time</code> を使っている
<details><summary>Cargo.toml</summary><div class="details-content"><div class="code-block-container">
<div class="code-block-filename-container">Cargo.toml</div>
<pre class="diff-highlight language-diff-toml"><code class="diff-highlight language-diff-toml code-line" data-line="21"> "deref",
 "into",
] }
+ time = { version = "0.3.37", features = [] }
</code></pre>
</div></div></details>
<code>list_books</code> ハンドラでダミーの書籍一覧を返却する
<details><summary>list.rs</summary><div class="details-content"><div class="code-block-container">
<div class="code-block-filename-container">list.rs</div>
<pre class="language-rust"><code class="language-rust code-line" data-line="32">pub async fn list_books() -&gt; impl Responder {
 let books = vec![
 Book {
 id: 1,
 title: "Programming Rust".to_string(),
 author: "Jim Blandy, Jason Orendorff, Leonora F. S. Tindall".to_string(),
 published_on: date!(2021-06-11),
 },
 Book {
 id: 2,
 title: "The Rust Programming Language, 2nd Edition".to_string(),
 author: "Steve Klabnik, Carol Nichols".to_string(),
 published_on: date!(2023-02-28),
 },
 ];

 HttpResponse::Ok().json(books)
}
</code></pre>
</div></div></details>
コンパイルエラー
<details><summary>cargo check</summary><div class="details-content"><div class="code-block-container"><pre><code class="code-line" data-line="57">$ cargo check
 Checking book-stack v0.1.0 (/home/kozaki/rust-projects/book-stack)
error[E0277]: the trait bound `Book: serde::ser::Serialize` is not satisfied
 --&gt; src/handlers/books/list.rs:23:29
 |
23 | HttpResponse::Ok().json(books)
 | ---- ^^^^^ the trait `serde::ser::Serialize` is not implemented for `Book`, which is required by `Vec&lt;Book&gt;: serde::ser::Serialize`
 | |
 | required by a bound introduced by this call
 |
 = note: for local types consider adding `#[derive(serde::Serialize)]` to your `Book` type
 = note: for types from other crates check whether the crate offers a `serde` feature flag
 = help: the following other types implement trait `serde::ser::Serialize`:
 &amp;'a T
 &amp;'a mut T
 ()
 (T,)
 (T0, T1)
 (T0, T1, T2)
 (T0, T1, T2, T3)
 (T0, T1, T2, T3, T4)
 and 134 others
 = note: required for `Vec&lt;Book&gt;` to implement `serde::ser::Serialize`
note: required by a bound in `HttpResponseBuilder::json`
 --&gt; /home/kozaki/.cargo/registry/src/index.crates.io-6f17d22bba15001f/actix-web-4.9.0/src/response/builder.rs:333:40
 |
333 | pub fn json(&amp;mut self, value: impl Serialize) -&gt; HttpResponse {
 | ^^^^^^^^^ required by this bound in `HttpResponseBuilder::json`

For more information about this error, try `rustc --explain E0277`.
error: could not compile `book-stack` (lib) due to 1 previous error

</code></pre></div></div></details>
<code>Book</code> がシリアライズできないといけないので、<a href="https://serde.rs/" target="_blank" rel="nofollow noopener noreferrer">serde</a> クレートを足す
<details><summary>Cargo.toml</summary><div class="details-content"><div class="code-block-container">
<div class="code-block-filename-container">Cargo.toml</div>
<pre class="diff-highlight language-diff-toml"><code class="diff-highlight language-diff-toml code-line" data-line="96"> "into",
] }
- time = { version = "0.3.37", features = [] }
+ time = { version = "0.3.37", features = ["macros", "serde"] }
+ serde = { version = "1.0", features = ["derive"] }
</code></pre>
</div></div></details>
<ul data-line="105" class="code-line">
<li data-line="105" class="code-line">
<code>derive</code> フィーチャーは <code>#[derive(Serialize)]</code> と書くためにいる</li>
<li data-line="106" class="code-line">
<code>time</code> クレートが提供する型をシリアライズできるように <code>serde</code> フィーチャーを追加している</li>
<li data-line="107" class="code-line">先になにげに <code>date!</code> マクロで <code>published_on</code> に日付をいれていたので <code>macro</code> フィーチャーも追加</li>
</ul>
<code>Book</code> にシリアライズを指定
<details><summary>book.rs</summary><div class="details-content"><div class="code-block-container">
<div class="code-block-filename-container">book.rs</div>
<pre class="diff-highlight language-diff-rust"><code class="diff-highlight language-diff-rust code-line" data-line="112">- #[derive(Debug, Clone, Eq, PartialEq)]
+ #[derive(Debug, Clone, Eq, PartialEq, Serialize, Deserialize)]
pub struct Book {
 pub id: i64,

</code></pre>
</div></div></details>
ダミーの書籍一覧を返却できるようになった
<details><summary>xh :8080/api/books</summary><div class="details-content"><div class="code-block-container"><pre><code class="code-line" data-line="124">$ xh :8080/api/books
HTTP/1.1 200 OK
Content-Length: 252
Content-Type: application/json
Date: Sat, 28 Dec 2024 00:47:30 GMT

[
 {
 "id": 1,
 "title": "Programming Rust",
 "author": "Jim Blandy, Jason Orendorff, Leonora F. S. Tindall",
 "published_on": [
 2021,
 162
 ]
 },
 {
 "id": 2,
 "title": "The Rust Programming Language, 2nd Edition",
 "author": "Steve Klabnik, Carol Nichols",
 "published_on": [
 2023,
 59
 ]
 }
]

</code></pre></div></div></details>
が、<code>published_on</code> のシリアライズの結果がよくない。<code>time</code> クレートの <code>serde-human-readable</code> フィーチャーを有効にする
<details><summary>Cargo.toml</summary><div class="details-content"><div class="code-block-container">
<div class="code-block-filename-container">Cargo.toml</div>
<pre class="diff-highlight language-diff-toml"><code class="diff-highlight language-diff-toml code-line" data-line="158"> "deref",
 "into",
] }
time = { version = "0.3.37", features = [
 "macros",
 "serde",
+ "serde-human-readable"
] }
serde = { version = "1.0", features = ["derive"] }
</code></pre>
</div></div></details>
できた
<details><summary>xh :8080/api/books</summary><div class="details-content"><div class="code-block-container"><pre><code class="code-line" data-line="174">xh :8080/api/books
HTTP/1.1 200 OK
Content-Length: 257
Content-Type: application/json
Date: Sat, 28 Dec 2024 00:53:59 GMT

[
 {
 "id": 1,
 "title": "Programming Rust",
 "author": "Jim Blandy, Jason Orendorff, Leonora F. S. Tindall",
 "published_on": "2021-06-11"
 },
 {
 "id": 2,
 "title": "The Rust Programming Language, 2nd Edition",
 "author": "Steve Klabnik, Carol Nichols",
 "published_on": "2023-02-28"
 }
]

</code></pre></div></div></details>

<h2 id="get_book" data-line="0" class="code-line">
<a class="header-anchor-link" href="#get_book" aria-hidden="true"></a> get_book</h2>
指定した <code>id</code> を持つ書籍を取得する。
これまで <code>id</code> は素の <code>i64</code> にしていたが、<code>BookId</code> という個別の名前をつける。これは良く知られた<a href="https://rust-unofficial.github.io/patterns/patterns/behavioural/newtype.html" target="_blank" rel="nofollow noopener noreferrer">NewTypeパターン</a>というやつ
<details><summary>book_id.rs</summary><div class="details-content"><div class="code-block-container">
<div class="code-block-filename-container">book_id.rs</div>
<pre class="language-rust"><code class="language-rust code-line" data-line="7">#[derive(
 Debug,
 Copy,
 Clone,
 Eq,
 PartialEq,
 Default,
 derive_more::Display,
 derive_more::Constructor,
 derive_more::From,
 derive_more::FromStr,
 derive_more::Into,
 Serialize,
 Deserialize,
)]
#[display("{0}", _0)]
pub struct BookId(i64);
</code></pre>
</div></div></details>
<code>derive_more</code> によってボイラープレートコードが減る
そして、<code>Book</code> の <code>id</code> の型を変更する
<details><summary>book.rs</summary><div class="details-content"><div class="code-block-container">
<div class="code-block-filename-container">book.rs</div>
<pre class="diff-highlight language-diff-rust"><code class="diff-highlight language-diff-rust code-line" data-line="33">#[derive(Debug, Clone, Eq, PartialEq, Serialize, Deserialize)]
pub struct Book {
+ pub id: i64,
- pub id: BookId,
 pub title: String,

</code></pre>
</div></div></details>
<code>list_books</code> に書いたダミーデータの <code>id</code> の値も修正する
<details><summary>修正の例</summary><div class="details-content"><div class="code-block-container">
<div class="code-block-filename-container">list.rs</div>
<pre class="diff-highlight language-diff-rust"><code class="diff-highlight language-diff-rust code-line" data-line="46"> let books = vec![
 Book {
- id: 1,
+ id: 1.into(),
 title: "Programming Rust".to_string(),
 author: "Jim Blandy, Jason Orendorff, Leonora F. S. Tindall".to_string(),

</code></pre>
</div></div></details>
<code>BookId</code> は <code>From&lt;i64&gt;</code> を実装しているので、<code>i64</code> から <code>into()</code> メソッドで <code>BookId</code> になる
<aside class="msg message">!<div class="msg-content">
Rust には暗黙的な型変換がないので、「明示的」な記述が求められるが他の言語に見られるような冗長な明示( 例えば C++ の static_cast&lt;&gt;)でないのが良い。
</div></aside>
<code>get_book</code> ハンドラが URL パスに指定した <code>id</code> を受け取れるようにするには <a href="https://actix.rs/docs/extractors#path" target="_blank" rel="nofollow noopener noreferrer">Extractors &gt; Path</a> を参照しつつ
<details><summary>books/get.rs</summary><div class="details-content"><div class="code-block-container">
<div class="code-block-filename-container">books/get.rs</div>
<pre class="language-rust"><code class="language-rust code-line" data-line="66">pub async fn get_book(path: web::Path&lt;BookId&gt;) -&gt; impl Responder {
 let book = Book {
 id: path.into_inner(),
 title: "Programming Rust".to_string(),
 author: "Jim Blandy, Jason Orendorff, Leonora F. S. Tindall".to_string(),
 published_on: date!(2021-06-11),
 };

 HttpResponse::Ok().json(book)
}
</code></pre>
</div></div></details>
<a href="https://docs.rs/actix-web/latest/actix_web/web/struct.Path.html" target="_blank" rel="nofollow noopener noreferrer">web::Path</a> によれば、<code>Path&lt;T&gt;</code> に入る <code>T</code> は文字列からデシリアライズして <code>T</code> になるものなら何でもよい。このため、<code>BookId</code> をそのまま使える
できた
<details><summary>GET /api/books/5</summary><div class="details-content"><div class="code-block-container"><pre><code class="code-line" data-line="85">$ xh :8080/api/books/5
HTTP/1.1 200 OK
Content-Length: 125
Content-Type: application/json
Date: Sat, 28 Dec 2024 01:30:50 GMT

{
 "id": 5,
 "title": "Programming Rust",
 "author": "Jim Blandy, Jason Orendorff, Leonora F. S. Tindall",
 "published_on": "2021-06-11"
}

</code></pre></div></div></details>

<h2 id="create_book" data-line="0" class="code-line">
<a class="header-anchor-link" href="#create_book" aria-hidden="true"></a> create_book</h2>
書籍を新規に作成するには <a href="https://actix.rs/docs/extractors#json" target="_blank" rel="nofollow noopener noreferrer">Extractors &gt; Json</a> を参考に、<code>POST</code> リクエストのリクエストボディに相当する struct を用意する
<details><summary>payloads/create_book.rs</summary><div class="details-content"><div class="code-block-container">
<div class="code-block-filename-container">payloads/create_book.rs</div>
<pre class="language-rust"><code class="language-rust code-line" data-line="5">#[derive(Debug, Clone, Eq, PartialEq, Serialize, Deserialize)]
pub struct CreateBook {
 pub title: String,
 pub author: String,
 pub published_on: time::Date,
}
</code></pre>
</div></div></details>
<code>Book</code> から <code>id</code> を抜いただけ。
<details><summary>post.rs</summary><div class="details-content"><div class="code-block-container">
<div class="code-block-filename-container">post.rs</div>
<pre class="language-rust"><code class="language-rust code-line" data-line="18">pub async fn create_book(payload: web::Json&lt;CreateBook&gt;) -&gt; impl Responder {
 let CreateBook {
 title,
 author,
 published_on,
 } = payload.into_inner();
 let book = Book {
 id: 6.into(),
 title,
 author,
 published_on,
 };

 HttpResponse::Created()
 .insert_header((header::LOCATION, "/api/books/6"))
 .json(book)
}

</code></pre>
</div></div></details>
できた
<details><summary>xh PUT :8080/api/books/7 title="Updated Title"</summary><div class="details-content"><div class="code-block-container"><pre><code class="code-line" data-line="44">$ xh PUT :8080/api/books/7 title="Updated Title"
HTTP/1.1 200 OK
Content-Length: 80
Content-Type: application/json
Date: Sat, 28 Dec 2024 02:40:13 GMT

{
 "id": 7,
 "title": "Updated Title",
 "author": "Author W",
 "published_on": "2024-01-17"
}

</code></pre></div></div></details>

<h2 id="update_book" data-line="0" class="code-line">
<a class="header-anchor-link" href="#update_book" aria-hidden="true"></a> update_book</h2>
同じく更新のための struct を用意する
<details><summary>payloads/update_book.rs</summary><div class="details-content"><div class="code-block-container">
<div class="code-block-filename-container">payloads/update_book.rs</div>
<pre class="language-rust"><code class="language-rust code-line" data-line="5">#[derive(Debug, Clone, Eq, PartialEq, Serialize, Deserialize)]
pub struct UpdateBook {
 #[serde(skip_serializing_if = "Option::is_none")]
 pub title: Option&lt;String&gt;,
 #[serde(skip_serializing_if = "Option::is_none")]
 pub author: Option&lt;String&gt;,
 #[serde(skip_serializing_if = "Option::is_none")]
 pub published_on: Option&lt;time::Date&gt;,
}
</code></pre>
</div></div></details>
シリアライズする予定はいまないけどいちおう <code>Serialize</code> もつけている <code>Option::None</code> のスキップは <a href="https://serde.rs/field-attrs.html#skip_serializing_if" target="_blank" rel="nofollow noopener noreferrer">serde.rs &gt; field attributes</a> を参照
<details><summary>books/put.rs</summary><div class="details-content"><div class="code-block-container">
<div class="code-block-filename-container">books/put.rs</div>
<pre class="language-rust"><code class="language-rust code-line" data-line="21">pub async fn update_book(
 path: web::Path&lt;BookId&gt;,
 payload: web::Json&lt;UpdateBook&gt;,
) -&gt; impl Responder {
 let book_id = path.into_inner();
 let UpdateBook {
 title,
 author,
 published_on,
 } = payload.into_inner();

 let book = Book {
 id: book_id,
 title: title.unwrap_or("Title A".into()),
 author: author.unwrap_or("Author W".into()),
 published_on: published_on.unwrap_or(date!(2024 - 01 - 17)),
 };

 HttpResponse::Ok().json(book)
}

</code></pre>
</div></div></details>
できた
<details><summary>POST /api/books</summary><div class="details-content"><div class="code-block-container"><pre><code class="code-line" data-line="50">$ xh POST :8080/api/books title="Title A" author="Author X" published_on="2024-10-01"
HTTP/1.1 201 Created
Content-Length: 74
Content-Type: application/json
Date: Sat, 28 Dec 2024 02:21:56 GMT
Location: /api/books/6

{
 "id": 6,
 "title": "Title A",
 "author": "Author X",
 "published_on": "2024-10-01"
}

</code></pre></div></div></details>

<h2 id="delete_book" data-line="0" class="code-line">
<a class="header-anchor-link" href="#delete_book" aria-hidden="true"></a> delete_book</h2>
特に新しいことはない
<details><summary>books/delete.rs</summary><div class="details-content"><div class="code-block-container">
<div class="code-block-filename-container">books/delete.rs</div>
<pre class="language-rust"><code class="language-rust code-line" data-line="5">pub async fn delete_book(path: web::Path&lt;BookId&gt;) -&gt; impl Responder {
 let book_id = path.into_inner();

 let book = Book {
 id: book_id,
 title: "Deleted Title".into(),
 author: "Author Z".into(),
 published_on: date!(2023 - 10 - 06),
 };

 HttpResponse::Ok().json(book)
}

</code></pre>
</div></div></details>

<h2 id="books-%E3%81%AE%E3%83%8F%E3%83%B3%E3%83%89%E3%83%A9%E3%81%AB-utoipa-%E3%82%92%E9%81%A9%E7%94%A8%E3%81%99%E3%82%8B" data-line="0" class="code-line">
<a class="header-anchor-link" href="#books-%E3%81%AE%E3%83%8F%E3%83%B3%E3%83%89%E3%83%A9%E3%81%AB-utoipa-%E3%82%92%E9%81%A9%E7%94%A8%E3%81%99%E3%82%8B" aria-hidden="true"></a> books のハンドラに utoipa を適用する</h2>
<a href="https://docs.rs/utoipa/latest/utoipa/attr.path.html#path-attributes" target="_blank" rel="nofollow noopener noreferrer">path attribute</a> の説明をがんばって読む
<details><summary>books/delete.rs</summary><div class="details-content"><div class="code-block-container">
<div class="code-block-filename-container">books/delete.rs</div>
<pre class="diff-highlight language-diff-rust"><code class="diff-highlight language-diff-rust code-line" data-line="5">+ /// Delete the Book of Id
+ #[utoipa::path(
+ delete,
+ context_path = "/api/books",
+ path = "/{id}",
+ tag = "Books",
+ params(
+ ("id" = BookId, Path),
+ ),
+ responses(
+ (status = 200, body = Book),
+ (status = NOT_FOUND, description = "The Book is not found")
+ ),
+ )]
pub async fn delete_book(path: web::Path&lt;BookId&gt;) -&gt; impl Responder {
 let book_id = path.into_inner();

</code></pre>
</div></div></details>
<code>BookId</code> や <code>Book</code> に <code>ToSchema</code> トレイトをつける
<details><summary>models/book_id.rs</summary><div class="details-content"><div class="code-block-container">
<div class="code-block-filename-container">models/book_id.rs</div>
<pre class="diff-highlight language-diff-rust"><code class="diff-highlight language-diff-rust code-line" data-line="29"> Deserialize,
+ ToSchema,
)]
#[display("{0}", _0)]
pub struct BookId(i64);

</code></pre>
</div></div></details>
<details><summary>models/book.rs</summary><div class="details-content"><div class="code-block-container">
<div class="code-block-filename-container">models/book.rs</div>
<pre class="diff-highlight language-diff-rust"><code class="diff-highlight language-diff-rust code-line" data-line="40">- #[derive(Debug, Clone, Eq, PartialEq, Serialize, Deserialize)]
+ #[derive(Debug, Clone, Eq, PartialEq, Serialize, Deserialize, ToSchema)]
pub struct Book {
 pub id: BookId,
 pub title: String,

</code></pre>
</div></div></details>
<code>main.rs</code> にある <code>ApiDoc</code> を別モジュールに切り出す
<details><summary>api_doc.rs</summary><div class="details-content"><div class="code-block-container"><pre class="language-rust"><code class="language-rust code-line" data-line="53">// get_pet_by_id のサンプルルートもとりあえずコピーする

#[derive(OpenApi)]
#[openapi(paths(get_pet_by_id))]
pub struct ApiDoc;

</code></pre></div></div></details>
この <code>ApiDoc</code> にいま作った <code>delete_book</code> を追加する
<details><summary>api_docs.rs</summary><div class="details-content"><div class="code-block-container">
<div class="code-block-filename-container">api_docs.rs</div>
<pre class="diff-highlight language-diff-rust"><code class="diff-highlight language-diff-rust code-line" data-line="66">+ use crate::handlers::books::__path_delete_book;

#[derive(OpenApi)]
- #[openapi(paths(get_pet_by_id))]
+ #[openapi(paths(get_pet_by_id, delete_book))]
pub struct ApiDoc;

</code></pre>
</div></div></details>
<code>ApiDoc</code> の <code>openapi</code> 属性には <code>delete_book</code> を指定するが、マクロを展開した時に必要なのは、<code>path</code>属性を展開して生成された構造体 <code>__path_delete_book</code> なので、これを use していることに注意する
<details><summary>ふえた</summary><div class="details-content">
<img src="https://storage.googleapis.com/zenn-user-upload/beb3e915cfd0-20241228.png" loading="lazy" class="md-img">
</div></details>

<h2 id="%E6%B0%97%E5%90%88%E3%81%84%E3%81%A7%E6%AE%8B%E3%82%8A%E3%81%AE%E3%83%8F%E3%83%B3%E3%83%89%E3%83%A9%E3%81%AB%E3%82%82-utoipa%3A%3Apath-%E3%82%92%E8%BF%BD%E5%8A%A0%E3%81%99%E3%82%8B" data-line="0" class="code-line">
<a class="header-anchor-link" href="#%E6%B0%97%E5%90%88%E3%81%84%E3%81%A7%E6%AE%8B%E3%82%8A%E3%81%AE%E3%83%8F%E3%83%B3%E3%83%89%E3%83%A9%E3%81%AB%E3%82%82-utoipa%3A%3Apath-%E3%82%92%E8%BF%BD%E5%8A%A0%E3%81%99%E3%82%8B" aria-hidden="true"></a> 気合いで残りのハンドラにも utoipa::path を追加する</h2>
<details><summary>books/get.rs</summary><div class="details-content"><div class="code-block-container">
<div class="code-block-filename-container">books/get.rs</div>
<pre class="diff-highlight language-diff-rust"><code class="diff-highlight language-diff-rust code-line" data-line="3">+ /// Get the Book of Id
+ #[utoipa::path(
+ get,
+ context_path = "/api/books",
+ path = "/{id}",
+ tag = "Books",
+ params(
+ ("id" = BookId, Path),
+ ),
+ responses(
+ (status = 200, body = Book),
+ (status = NOT_FOUND, description = "The Book is not found")
+ ),
+ )]
pub async fn get_book(path: web::Path&lt;BookId&gt;) -&gt; impl Responder {
 let book = Book {

</code></pre>
</div></div></details>
<details><summary>books/list.rs</summary><div class="details-content"><div class="code-block-container">
<div class="code-block-filename-container">books/list.rs</div>
<pre class="diff-highlight language-diff-rust"><code class="diff-highlight language-diff-rust code-line" data-line="25">+ /// Get All Books
+ #[utoipa::path(
+ get,
+ context_path = "/api/books",
+ path = "",
+ tag = "Books",
+ responses(
+ (status = 200, body = Vec&lt;Book&gt;)
+ ),
+ )]
pub async fn list_books() -&gt; impl Responder {
 let books = vec![
 Book {
</code></pre>
</div></div></details>
<details><summary>books/post.rs</summary><div class="details-content"><div class="code-block-container">
<div class="code-block-filename-container">books/post.rs</div>
<pre class="diff-highlight language-diff-rust"><code class="diff-highlight language-diff-rust code-line" data-line="43">+ /// Create a new Book
+ #[utoipa::path(
+ post,
+ context_path = "/api/books",
+ path = "",
+ tag = "Books",
+ request_body = CreateBook,
+ responses(
+ (status = 201, body = Book),
+ ),
+ )]
pub async fn create_book(payload: web::Json&lt;CreateBook&gt;) -&gt; impl Responder {
 let CreateBook {
 title,
</code></pre>
</div></div></details>
<details><summary>books/put.rs</summary><div class="details-content"><div class="code-block-container">
<div class="code-block-filename-container">books/put.rs</div>
<pre class="diff-highlight language-diff-rust"><code class="diff-highlight language-diff-rust code-line" data-line="62">+ /// Update the Book of Id
+ #[utoipa::path(
+ put,
+ context_path = "/api/books",
+ path = "/{id}",
+ tag = "Books",
+ params(
+ ("id" = BookId, Path),
+ ),
+ request_body = UpdateBook,
+ responses(
+ (status = 200, body = Book),
+ (status = NOT_FOUND, description = "The Book is not found")
+ ),
+ )]
pub async fn update_book(
 path: web::Path&lt;BookId&gt;,
 payload: web::Json&lt;UpdateBook&gt;,
) -&gt; impl Responder {
 let book_id = path.into_inner();

</code></pre>
</div></div></details>
<code>ApiDoc</code> の use は面倒なので <code>*</code> にして
<details><summary>api_doc.rs</summary><div class="details-content"><div class="code-block-container">
<div class="code-block-filename-container">api_doc.rs</div>
<pre class="diff-highlight language-diff-rust"><code class="diff-highlight language-diff-rust code-line" data-line="90">- use crate::handlers::books::__path_delete_book;
+ use crate::handlers::books::*;

#[derive(OpenApi)]
- #[openapi(get_pet_by_id, delete_book)]
+ #[openapi(
+ paths(list_books, get_book, create_book, update_book, delete_book, get_pet_by_id)
+ )]
pub struct ApiDoc;

</code></pre>
</div></div></details>
Swagger UI はこうじゃ
<details><summary>ふえた</summary><div class="details-content">
<img src="https://storage.googleapis.com/zenn-user-upload/b6d019593258-20241228.png" loading="lazy" class="md-img">
</div></details>

<h2 id="swagger-ui-%E3%81%AE%E3%83%AB%E3%83%BC%E3%83%86%E3%82%A3%E3%83%B3%E3%82%B0%E5%AE%9A%E7%BE%A9%E3%82%82%E5%88%87%E3%82%8A%E5%87%BA%E3%81%99" data-line="0" class="code-line">
<a class="header-anchor-link" href="#swagger-ui-%E3%81%AE%E3%83%AB%E3%83%BC%E3%83%86%E3%82%A3%E3%83%B3%E3%82%B0%E5%AE%9A%E7%BE%A9%E3%82%82%E5%88%87%E3%82%8A%E5%87%BA%E3%81%99" aria-hidden="true"></a> Swagger UI のルーティング定義も切り出す</h2>
<code>routes</code> モジュールに <code>swagger</code> サブモジュールを作って、この中に Swagger UI のルーティング定義を書く
<div class="code-block-container"><pre class="diff-highlight "><code class="diff-highlight code-line" data-line="4">lib.rs
└ routes.rs
 └ api.rs
 └ books_routes.rs
+ └ swagger.rs
</code></pre></div><details><summary>routes/swagger.rs</summary><div class="details-content"><div class="code-block-container">
<div class="code-block-filename-container">routes/swagger.rs</div>
<pre class="language-rust"><code class="language-rust code-line" data-line="13">use actix_web::web;
use utoipa::OpenApi as _;
use utoipa_swagger_ui::SwaggerUi;

use crate::ApiDoc;

pub fn swagger_route(cfg: &amp;mut web::ServiceConfig) {
 cfg.service(
 SwaggerUi::new("/swagger-ui/{_:.*}").url("/api-docs/openapi.json", ApiDoc::openapi()),
 );
}

</code></pre>
</div></div></details>
これを <code>main.rs</code> に入れる
<details><summary>main.rs</summary><div class="details-content"><div class="code-block-container">
<div class="code-block-filename-container">main.rs</div>
<pre class="diff-highlight language-diff-rust"><code class="diff-highlight language-diff-rust code-line" data-line="32">#[actix_web::main]
async fn main() -&gt; AppResult&lt;()&gt; {
 HttpServer::new(|| {
 App::new()
 .configure(api::api_route)
 .route("/pets/{id}", web::get().to(get_pet_by_id))
- .service(
- SwaggerUi::new("/swagger-ui/{_:.*}")
- .url("/api-docs/openapi.json", ApiDoc::openapi()),
- )
+ .configure(swagger_route)
 })
</code></pre>
</div></div></details>
utoipa のサイトからはりつけたサンプルのルーティングはもう不要なので削除しておく

<h1 id="%E3%83%AD%E3%82%AC%E3%83%BC%E3%82%92%E3%81%84%E3%82%8C%E3%82%8B" data-line="0" class="code-line">
<a class="header-anchor-link" href="#%E3%83%AD%E3%82%AC%E3%83%BC%E3%82%92%E3%81%84%E3%82%8C%E3%82%8B" aria-hidden="true"></a> ロガーをいれる</h1>
<a href="https://docs.rs/actix-web/latest/actix_web/middleware/struct.Logger.html" target="_blank" rel="nofollow noopener noreferrer">Logger Middleware</a> を設定する
<details><summary>Cargo.toml</summary><div class="details-content"><div class="code-block-container">
<div class="code-block-filename-container">Cargo.toml</div>
<pre class="diff-highlight language-diff-toml"><code class="diff-highlight language-diff-toml code-line" data-line="5"> "preserve_path_order",
] }
utoipa-swagger-ui = { version = "8.1.0", features = ["actix-web"] }
+ log = { version = "0.4.22", features = [] }
+ env_logger = { version = "0.11.6", features = [] }
</code></pre>
</div></div></details>
<details><summary>main.rs</summary><div class="details-content"><div class="code-block-container">
<div class="code-block-filename-container">main.rs</div>
<pre class="diff-highlight language-diff-rust"><code class="diff-highlight language-diff-rust code-line" data-line="16">#[actix_web::main]
async fn main() -&gt; AppResult&lt;()&gt; {
+ env_logger::init_from_env(env_logger::Env::new().default_filter_or("info"));

 HttpServer::new(|| {
 App::new()
+ .wrap(middleware::Logger::default())
 .configure(api::api_route)
 .configure(swagger_route)
 })
 .bind(("127.0.0.1", 8080))
 .change_context(AppError)?
 .run()
 .await
 .change_context(AppError)?;

 Ok(())
}

</code></pre>
</div></div></details>
何も環境変数を指定しなければ <code>RUST_LOG=info</code> で動作する
<details><summary>ログ出力の例</summary><div class="details-content"><div class="code-block-container"><pre><code class="code-line" data-line="42"> Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.13s
 Running `target/debug/book-stack`
[2024-12-28T09:29:35Z INFO actix_server::builder] starting 4 workers
[2024-12-28T09:29:35Z INFO actix_server::server] Actix runtime found; starting in Actix runtime
[2024-12-28T09:29:35Z INFO actix_server::server] starting service: "actix-web-service-127.0.0.1:8080", workers: 4, listening on: 127.0.0.1:8080

</code></pre></div></div></details>

<h2 id="direnv-%E3%81%A7%E7%92%B0%E5%A2%83%E5%A4%89%E6%95%B0%E3%82%92%E8%A8%AD%E5%AE%9A%E3%81%99%E3%82%8B" data-line="0" class="code-line">
<a class="header-anchor-link" href="#direnv-%E3%81%A7%E7%92%B0%E5%A2%83%E5%A4%89%E6%95%B0%E3%82%92%E8%A8%AD%E5%AE%9A%E3%81%99%E3%82%8B" aria-hidden="true"></a> direnv で環境変数を設定する</h2>
<a href="https://github.com/direnv/direnv" target="_blank" rel="nofollow noopener noreferrer">direnv</a> の説明は省略
プロジェクトフォルダに <code>.envrc</code> ファイルを作成して、ここに必要な環境変数の設定を記載することにする。今はログレベルしか書いていないが、この後データベースの接続文字列などを書く
<details><summary>.envrc</summary><div class="details-content"><div class="code-block-container"><pre><code class="code-line" data-line="7">export RUST_LOG=debug
</code></pre></div></div></details>
環境変数を設定するのに <code>.env</code> ファイルがよく使われるが、プログラムから <code>.env</code> を使うための <a href="https://crates.io/crates/dotenv" target="_blank" rel="nofollow noopener noreferrer">dotenv</a> はもう 5年ほどメンテされていない。その代替として登場した <a href="https://crates.io/crates/dotenvy" target="_blank" rel="nofollow noopener noreferrer">dotenvy</a> も 2年動きがないので、そもそも <code>.env</code> を使わない。
<code>direnv allow</code> で環境変数をシェルに追加
<div class="code-block-container"><pre><code class="code-line" data-line="15">$ direnv allow
direnv: loading ~/rust-projects/book-stack/.envrc
direnv: export +RUST_LOG

</code></pre></div>環境変数を便利に取り出すクレートも色々あって困る。オーバースペックだけど <a href="https://crates.io/crates/clap" target="_blank" rel="nofollow noopener noreferrer">clap</a> がよくメンテナンスされているのでこれを使う。
<details><summary>Cargo.toml</summary><div class="details-content"><div class="code-block-container">
<div class="code-block-filename-container">Cargo.toml</div>
<pre class="diff-highlight language-diff-toml"><code class="diff-highlight language-diff-toml code-line" data-line="25">log = { version = "0.4.22", features = [] }
env_logger = { version = "0.11.6", features = [] }
+ clap = { version = "4.5.23", features = ["derive", "env"] }
</code></pre>
</div></div></details>
'env' フィーチャーを追加することで、環境変数 <code>DATABASE_URL</code> とコマンドライン引数 <code>--database-url</code> が透過的に扱えるのでほとんどのユースケースをカバーできる。
環境変数を保持する構造体を作る
<details><summary>env_args.rs</summary><div class="details-content"><div class="code-block-container">
<div class="code-block-filename-container">env_args</div>
<pre class="language-rust"><code class="language-rust code-line" data-line="37">#[derive(Debug, Clone, Eq, PartialEq)]
pub struct EnvArgs {
 pub rust_log: String,
}

</code></pre>
</div></div></details>
<code>clap</code> は機能が非常に多いので初見だとたいへん。<a href="https://docs.rs/clap/latest/clap/_derive/_tutorial/chapter_0/index.html" target="_blank" rel="nofollow noopener noreferrer">Tutorial</a> と <a href="https://docs.rs/clap/latest/clap/_derive/index.html" target="_blank" rel="nofollow noopener noreferrer">Reference</a> をがんばって読む
<details><summary>env_args.rs</summary><div class="details-content"><div class="code-block-container">
<div class="code-block-filename-container">env_args</div>
<pre class="diff-highlight language-diff-rust"><code class="diff-highlight language-diff-rust code-line" data-line="49">- #[derive(Debug, Clone, Eq, PartialEq)]
+ #[derive(Debug, Clone, Eq, PartialEq, clap::Parser)]
pub struct EnvArgs {
+ #[arg(long, env, default_value = "info")]
 pub rust_log: String,
}

</code></pre>
</div></div></details>
<code>clap::Parser</code> を実装することで、<code>EnvArgs</code> に <code>parse</code> メソッドが生えるので、これで環境変数を読める。
<details><summary>env_args.rs</summary><div class="details-content"><div class="code-block-container">
<div class="code-block-filename-container">env_args</div>
<pre class="diff-highlight language-diff-rust"><code class="diff-highlight language-diff-rust code-line" data-line="63">+ impl EnvArgs {
+ pub fn init() -&gt; AppResult&lt;Self&gt; {
+ use clap::Parser;
+ Self::try_parse().change_context(AppError)
+ }
+ }

</code></pre>
</div></div></details>
ロガーの初期化を変更する
<details><summary>main.rs</summary><div class="details-content"><div class="code-block-container">
<div class="code-block-filename-container">main.rs</div>
<pre class="diff-highlight language-diff-rust"><code class="diff-highlight language-diff-rust code-line" data-line="77">#[actix_web::main]
async fn main() -&gt; AppResult&lt;()&gt; {
+ let EnvArgs { rust_log } = EnvArgs::init()?;
- env_logger::init_from_env(env_logger::Env::new().default_filter_or("info"));
+ env_logger::init_from_env(env_logger::Env::new().default_filter_or(rust_log));
</code></pre>
</div></div></details>
<aside class="msg message">!<div class="msg-content">
コマンドライン引数 <code>--rust-log</code> にログレベルが渡された場合はこれをロガーの設定で使うことを意図しているが、もしかすると環境変数 <code>RUST_LOG</code> とコマンドライン引数 <code>--rust-log</code> が両方指定された場合にコマンドライン引数が優先されないかもしれない (未検証)
</div></aside>

<h2 id="%E3%83%9D%E3%83%BC%E3%83%88%E3%82%82%E5%8F%AF%E5%A4%89%E3%81%AB%E3%81%99%E3%82%8B" data-line="0" class="code-line">
<a class="header-anchor-link" href="#%E3%83%9D%E3%83%BC%E3%83%88%E3%82%82%E5%8F%AF%E5%A4%89%E3%81%AB%E3%81%99%E3%82%8B" aria-hidden="true"></a> ポートも可変にする</h2>
<details><summary>env_args.rs</summary><div class="details-content"><div class="code-block-container">
<div class="code-block-filename-container">env_args.rs</div>
<pre class="diff-highlight language-diff-rust"><code class="diff-highlight language-diff-rust code-line" data-line="3">#[derive(Debug, Clone, Eq, PartialEq, clap::Parser)]
pub struct EnvArgs {
 #[arg(long, env, default_value = "info")]
 pub rust_log: String,
+
+ #[arg(long, env, default_value = "127.0.0.1")]
+ pub host: net::IpAddr,
+
+ #[arg(long, env, default_value_t = 8080)]
+ pub port: u16,
}

</code></pre>
</div></div></details>
環境変数を格納する <code>EnvArgs</code> のフィールドには単純な文字列や数値だけでなく、<code>&amp;str</code> から <code>FromStr</code> で変換可能な型は何でも指定できて、その型に適合しなければ <code>try_parse</code> がエラーを返す
<a href="https://docs.rs/clap/latest/clap/struct.Arg.html#method.value_parser" target="_blank" rel="nofollow noopener noreferrer">この辺</a> をごにょごにょ見ながら試すとわかる。多分。。。
<details><summary>main.rs</summary><div class="details-content"><div class="code-block-container">
<div class="code-block-filename-container">main.rs</div>
<pre class="diff-highlight language-diff-rust"><code class="diff-highlight language-diff-rust code-line" data-line="24">#[actix_web::main]
async fn main() -&gt; AppResult&lt;()&gt; {
- let EnvArgs { rust_log } = EnvArgs::init()?;
+ let EnvArgs {
+ rust_log,
+ host,
+ port,
+ } = EnvArgs::init()?;
 env_logger::init_from_env(env_logger::Env::new().default_filter_or(rust_log));

+ let addrs = net::SocketAddr::from((host, port));

 HttpServer::new(|| {
 App::new()
 .wrap(middleware::Logger::default())
 .configure(api::api_route)
 .configure(swagger_route)
 })
- .bind(("127.0.0.1", 8080))
+ .bind(addrs)
 .change_context(AppError)?
 .run()
 .await
 .change_context(AppError)?;

 Ok(())
}

</code></pre>
</div></div></details>

<h1 id="%E3%83%87%E3%83%BC%E3%82%BF%E3%83%99%E3%83%BC%E3%82%B9%E3%82%92%E7%94%A8%E6%84%8F%E3%81%99%E3%82%8B" data-line="0" class="code-line">
<a class="header-anchor-link" href="#%E3%83%87%E3%83%BC%E3%82%BF%E3%83%99%E3%83%BC%E3%82%B9%E3%82%92%E7%94%A8%E6%84%8F%E3%81%99%E3%82%8B" aria-hidden="true"></a> データベースを用意する</h1>
Postgres をデータベースとして使う (単に慣れているから) 
好きに用意すればいいけど、Docker で動かすのが定番かな ( どうせ後から Redis が欲しくなったりするし )
すぐ古くなるけど、いちおうサンプル載せとくか
<details><summary>docker-compose.yml</summary><div class="details-content"><div class="code-block-container">
<div class="code-block-filename-container">docker-compose.yml</div>
<pre class="language-yml"><code class="language-yml code-line" data-line="8">name: 'postgres'

services:
 db:
 image: postgres:17.2-bookworm
 container_name: postgres
 environment:
 POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
 POSTGRES_USER: ${POSTGRES_USER}
 POSTGRES_DB: ${POSTGRES_DB}
 restart: always
 volumes:
 - type: volume
 source: db-data
 target: /var/lib/postgresql/data
 volume:
 nocopy: true
 ports:
 - "5432:5432"
 ui:
 image: dpage/pgadmin4:8
 container_name: pgadmin
 environment:
 PGADMIN_DEFAULT_EMAIL: ${PGADMIN_EMAIL}
 PGADMIN_DEFAULT_PASSWORD: ${PGADMIN_PASSWORD}
 PGADMIN_CONFIG_SERVER_MODE: "False"
 PGADMIN_CONFIG_MASTER_PASSWORD_REQUIRED: "False"
 ports:
 - "8000:80"
 volumes:
 - pgadmin-data:/var/lib/pgadmin
 - ./config/servers.json:/pgadmin4/servers.json
 depends_on:
 - db
volumes:
 db-data:
 pgadmin-data:

</code></pre>
</div></div></details>
stackdb を用意
<div class="code-block-container"><pre class="language-sql"><code class="language-sql code-line" data-line="51">CREATE DATABASE stackdb;
</code></pre></div>後述の <code>sqlx-cli</code> でも作れるが、データベース未作成の状態だと環境変数 <code>DATABASE_URL</code> の指定でななく、<code>--database-url</code> をコマンドライン引数で <code>postgresdb</code> に接続するように指定するなど面倒が増えるだけ。cli ベースでも web ベースでも postgresql に接続して作った方が早い。

<h1 id="sqlx-%E3%82%92%E3%82%BB%E3%83%83%E3%83%88%E3%82%A2%E3%83%83%E3%83%97%E3%81%99%E3%82%8B" data-line="0" class="code-line">
<a class="header-anchor-link" href="#sqlx-%E3%82%92%E3%82%BB%E3%83%83%E3%83%88%E3%82%A2%E3%83%83%E3%83%97%E3%81%99%E3%82%8B" aria-hidden="true"></a> sqlx をセットアップする</h1>
データベースに接続するクレートとしては下記があるが(ほかにもあるが)、<code>sqlx</code> が定番かな？
<ul data-line="4" class="code-line">
<li data-line="4" class="code-line"><a href="https://crates.io/crates/sqlx" target="_blank" rel="nofollow noopener noreferrer">sqlx</a></li>
<li data-line="5" class="code-line"><a href="https://www.sea-ql.org/SeaORM/" target="_blank" rel="nofollow noopener noreferrer">SeaORM</a></li>
<li data-line="6" class="code-line"><a href="https://diesel.rs/" target="_blank" rel="nofollow noopener noreferrer">Diesel</a></li>
</ul>
まずは Cargo.toml に追記
<details><summary>Cargo.toml</summary><div class="details-content"><div class="code-block-container">
<div class="code-block-filename-container">Cargo.toml</div>
<pre class="diff-highlight language-diff-toml"><code class="diff-highlight language-diff-toml code-line" data-line="11">env_logger = { version = "0.11.6", features = [] }
clap = { version = "4.5.23", features = ["derive", "env"] }
+ sqlx = { version = "0.8.2", features = [
+ "runtime-tokio",
+ "postgres",
+ "macros",
+ "time"
+] }
</code></pre>
</div></div></details>
<ul data-line="23" class="code-line">
<li data-line="23" class="code-line">非同期処理を <code>tokio</code> ランタイムで実行する</li>
<li data-line="24" class="code-line">PostgreSQL サポート</li>
<li data-line="25" class="code-line">マクロを使って実行前に SQL を解析する</li>
<li data-line="26" class="code-line">時刻をサポートする</li>
</ul>
<a href="https://crates.io/crates/sqlx" target="_blank" rel="nofollow noopener noreferrer">Quick Start</a> の実装をまずはコピー
<details><summary>main.rs</summary><div class="details-content"><div class="code-block-container">
<div class="code-block-filename-container">main.rs</div>
<pre class="diff-highlight language-diff-rust"><code class="diff-highlight language-diff-rust code-line" data-line="31">#[actix_web::main]
async fn main() -&gt; AppResult&lt;()&gt; {
 let EnvArgs {
 rust_log,
 host,
 port,
 } = EnvArgs::init()?;
 env_logger::init_from_env(env_logger::Env::new().default_filter_or(rust_log));

+ let pool = PgPoolOptions::new()
+ .max_connections(5)
+ .connect("postgres://xxxx:yyyy@localhost:5432/stackdb")
+ .await
+ .change_context(AppError)?;
+ let version: (String,) = sqlx::query_as("SELECT version()")
+ .fetch_one(&amp;pool)
+ .await
+ .change_context(AppError)?;
+ log::info!("{0}", version.0);

 let addrs = net::SocketAddr::from((host, port));

 HttpServer::new(|| {
 App::new()

</code></pre>
</div></div></details>
データベースの接続 URL はソースコードに直接書くわけにはいかないので、環境変数 <code>DATABASE_URL</code> を追加する ( あとで <code>sqlx-cli</code> でも使う )
<details><summary>.envrc</summary><div class="details-content"><div class="code-block-container"><pre class="diff-highlight "><code class="diff-highlight code-line" data-line="63">export RUST_LOG=debug
export PORT=3000
+ export DATABASE_URL=postgres://xxxx:yyyy@localhost:5432/stackdb

</code></pre></div></div></details>
受け手のフィールドも増やす
<details><summary>env_args.rs</summary><div class="details-content"><div class="code-block-container">
<div class="code-block-filename-container">env_args.rs</div>
<pre class="diff-highlight language-diff-rust"><code class="diff-highlight language-diff-rust code-line" data-line="74">#[derive(Debug, Clone, Eq, PartialEq, clap::Parser)]
pub struct EnvArgs {
 #[arg(long, env, default_value = "info")]
 pub rust_log: String,

 #[arg(long, env, default_value = "127.0.0.1")]
 pub host: net::IpAddr,

 #[arg(long, env, default_value_t = 8080)]
 pub port: u16,
 
+ #[arg(long, env)]
+ pub database_url: String,
}

</code></pre>
</div></div></details>
これを <code>main.rs</code> で使う
<details><summary>main.rs</summary><div class="details-content"><div class="code-block-container">
<div class="code-block-filename-container">main.rs</div>
<pre class="diff-highlight language-diff-rust"><code class="diff-highlight language-diff-rust code-line" data-line="96">#[actix_web::main]
async fn main() -&gt; AppResult&lt;()&gt; {
 let EnvArgs {
 rust_log,
 host,
 port,
+ database_url,
 } = EnvArgs::init()?;
 env_logger::init_from_env(env_logger::Env::new().default_filter_or(rust_log));

 let pool = PgPoolOptions::new()
 .max_connections(5)
- .connect("postgres://xxxx:yyyy@localhost:5432/stackdb")
+ .connect(&amp;database_url)
 .await
 .change_context(AppError)?;
 let version: (String,) = sqlx::query_as("SELECT version()")
 .fetch_one(&amp;pool)
 .await
 .change_context(AppError)?;
 log::info!("{0}", version.0);

</code></pre>
</div></div></details>

<h2 id="sqlx%3A%3Apgpool-%E3%82%92-main.rs-%E3%81%8B%E3%82%89%E5%A4%96%E3%81%AB%E5%87%BA%E3%81%99" data-line="0" class="code-line">
<a class="header-anchor-link" href="#sqlx%3A%3Apgpool-%E3%82%92-main.rs-%E3%81%8B%E3%82%89%E5%A4%96%E3%81%AB%E5%87%BA%E3%81%99" aria-hidden="true"></a> sqlx::PgPool を main.rs から外に出す</h2>
<code>main.rs</code> にサンプルコードがコピーされていると煩いので <code>let pool</code> を他のモジュールに外だしする。 
<code>pool</code> は <code>sqlx::PgPool</code> 型なので、これを包む構造体を作ることで、機能をカプセル化する
<details><summary>db.rs</summary><div class="details-content"><div class="code-block-container">
<div class="code-block-filename-container">db.rs</div>
<pre class="language-rust"><code class="language-rust code-line" data-line="6">#[derive(Debug, Clone, derive_more::Deref, derive_more::DerefMut)]
pub struct Db(sqlx::PgPool);

impl Db {
 pub async fn init(database_url: &amp;str) -&gt; AppResult&lt;Self&gt; {
 let pool = PgPoolOptions::new()
 .max_connections(5)
 .connect(database_url)
 .await
 .change_context(AppError)?;

 Ok(Db(pool))
 }
}

</code></pre>
</div></div></details>
<ul data-line="25" class="code-line">
<li data-line="25" class="code-line">
<code>derive_more</code> を使って <code>Deref</code> , <code>DerefMut</code> トレイトを実装。
<ul data-line="26" class="code-line">
<li data-line="26" class="code-line">Rust の型強制の仕組みによって <code>Db</code> 型の変数の参照 (<code>let db: &amp;Db</code>) に対して、<code>&amp;Db</code> ➡️ <code>&amp;PgPool</code> と自動的に解釈されて、<code>PgPool</code> に生えているメソッドが <code>Db</code> でも使える</li>
</ul>
</li>
<li data-line="27" class="code-line">
<code>main.rs</code> に書いていた <code>let pool </code> の初期化の記述をそのまま <code>init</code> メソッドに移動して <code>Db</code> を構築
<ul data-line="28" class="code-line">
<li data-line="28" class="code-line">Java などのコンストラクタとは違い、Rust には特段コンストラクタの文法はないので自由にメソッド名も決められるし、戻り値の型も <code>Self</code> でなくてもよい</li>
</ul>
</li>
</ul>
たとえば、こんな風に <code>PgPool</code> の <code>acquire</code> メソッドを呼び出して使える
<details><summary>db.rs</summary><div class="details-content"><div class="code-block-container"><pre><code class="code-line" data-line="33">impl Db {
 pub async fn init(database_url: &amp;str) -&gt; AppResult&lt;Self&gt; {
 let pool = PgPoolOptions::new()
 .max_connections(5)
 .connect(database_url)
 .await
 .change_context(AppError)?;

 Ok(Db(pool))
 }

+ pub async fn version(&amp;self) -&gt; AppResult&lt;String&gt; {
+ let mut conn = self.acquire().await.change_context(AppError)?;
+
+ let version: (String,) = sqlx::query_as("SELECT version()")
+ .fetch_one(conn.as_mut())
+ .await
+ .change_context(AppError)?;
+
+ Ok(version.0)
+ }
+}

</code></pre></div></div></details>
ひとまず <code>main.rs</code> の記述を置き換える (あとで消えるけど)
<details><summary>main.rs</summary><div class="details-content"><div class="code-block-container">
<div class="code-block-filename-container">main.rs</div>
<pre class="diff-highlight language-diff-rust"><code class="diff-highlight language-diff-rust code-line" data-line="63">#[actix_web::main]
async fn main() -&gt; AppResult&lt;()&gt; {
 let EnvArgs {
 rust_log,
 host,
 port,
 database_url,
 } = EnvArgs::init()?;
 env_logger::init_from_env(env_logger::Env::new().default_filter_or(rust_log));

- let pool = PgPoolOptions::new()
- .max_connections(5)
- .connect(&amp;database_url)
- .await
- .change_context(AppError)?;
- let version: (String,) = sqlx::query_as("SELECT version()")
- .fetch_one(&amp;pool)
- .await
- .change_context(AppError)?;
- log::info!("{0}", version.0);
+ let db = Db::init(&amp;database_url).await?;
+ let version = db.version().await?;
+ log::info!("{0}", version);

 let addrs = net::SocketAddr::from((host, port));


</code></pre>
</div></div></details>

<h2 id="sqlx%3A%3Apgpool-%E3%82%92-actix-web-%E3%81%A7%E4%BD%BF%E3%81%86" data-line="0" class="code-line">
<a class="header-anchor-link" href="#sqlx%3A%3Apgpool-%E3%82%92-actix-web-%E3%81%A7%E4%BD%BF%E3%81%86" aria-hidden="true"></a> sqlx::PgPool を Actix Web で使う</h2>
Actix Web でデータベースを使う方法はドキュメントには <a href="https://actix.rs/docs/databases" target="_blank" rel="nofollow noopener noreferrer">サンプルを見よ</a> としか書いていない
そしてサンプルは <code>sqlx</code> を使ったものではないので、かすかに参考になる程度
<details><summary>サンプル</summary><div class="details-content"><div class="code-block-container">
<div class="code-block-filename-container">main.rs</div>
<pre class="language-rust"><code class="language-rust code-line" data-line="7">#[actix_web::main]
async fn main() -&gt; std::io::Result&lt;()&gt; {
 dotenv().ok();

 let config = ExampleConfig::builder()
 .override_with(EnvSource::new())
 .try_build()
 .unwrap();

 let pool = config.pg.create_pool(None, NoTls).unwrap();

 let server = HttpServer::new(move || {
 App::new().app_data(web::Data::new(pool.clone())).service(
 web::resource("/users")
 .route(web::post().to(add_user))
 .route(web::get().to(get_users)),
 )
 })
 .bind(config.server_addr.clone())?
 .run();
 println!("Server running at http://{}/", config.server_addr);

 server.await
}
</code></pre>
</div></div></details>
<ul data-line="35" class="code-line">
<li data-line="35" class="code-line">アプリケーションを起動するときに <a href="https://docs.rs/actix-web/latest/actix_web/struct.App.html#method.app_data" target="_blank" rel="nofollow noopener noreferrer">app_data</a> でデータベースプールを渡している</li>
<li data-line="36" class="code-line">データベースの例ではないが、<a href="https://actix.rs/docs/application#shared-mutable-state" target="_blank" rel="nofollow noopener noreferrer">Shared Mutable State</a> に説明がある</li>
</ul>
というわけで、ひとまずこれで
<details><summary>main.rs</summary><div class="details-content"><div class="code-block-container">
<div class="code-block-filename-container">main.rs</div>
<pre class="diff-highlight language-diff-rust"><code class="diff-highlight language-diff-rust code-line" data-line="41">#[actix_web::main]
async fn main() -&gt; AppResult&lt;()&gt; {
 let EnvArgs {
 rust_log,
 host,
 port,
 database_url,
 } = EnvArgs::init()?;
 env_logger::init_from_env(env_logger::Env::new().default_filter_or(rust_log));

 let db = Db::init(&amp;database_url).await?;
- let version = db.version().await?;
- log::info!("{0}", version);
 
+ let data = web::Data::new(db);

 let addrs = net::SocketAddr::from((host, port));

- HttpServer::new(|| {
+ HttpServer::new(move || {
 App::new()
+ .app_data(data.clone())
 .wrap(middleware::Logger::default())
 .configure(api::api_route)
 .configure(swagger_route)
 })
 .bind(addrs)
 .change_context(AppError)?
 .run()
 .await
 .change_context(AppError)?;

 Ok(())
}

</code></pre>
</div></div></details>
<ul data-line="80" class="code-line">
<li data-line="80" class="code-line">
<code>data: web::Data&lt;Db&gt;</code> は <code>main.rs</code> で作られて、<code>main.rs</code> が所有している</li>
<li data-line="81" class="code-line">
<code>HttpServer</code> は複数スレッド ( CPU のスレッド数による？) に分かれて各々 <code>App</code> を作って、クライアントからのリクエストをどこかのスレッドで処理する</li>
<li data-line="82" class="code-line">クロージャーに <code>move</code> 修飾子がついているので、ここで <code>main.rs</code> が所有していた <code>data</code> が <code>HttpServer::new</code> の引数に渡されたクロージャーの環境中に move する</li>
<li data-line="83" class="code-line">
<code>App::new()</code> が <code>HttpServer</code> のクロージャーから複数個作成される。<code>App::new().app_data(data.clone())</code> とすることで、<code>data</code> がクロージャーの環境からクローンされて、各々のスレッドにある <code>App</code> に渡される</li>
<li data-line="84" class="code-line">
<a href="https://github.com/actix/actix-web/blob/master/actix-web/src/data.rs#L88" target="_blank" rel="nofollow noopener noreferrer">Data</a> は渡した <code>Db</code> を <code>Arc</code> に包んで保持していて <code>data.clone()</code> は中身の <code>Arc</code> をクローンするので複数スレッド間でおなじ <code>Db</code> を共有する</li>
</ul>

<h1 id="sqlx-cli-%E3%81%A7-books-%E3%83%86%E3%83%BC%E3%83%96%E3%83%AB%E3%82%92%E4%BD%9C%E3%82%8B" data-line="0" class="code-line">
<a class="header-anchor-link" href="#sqlx-cli-%E3%81%A7-books-%E3%83%86%E3%83%BC%E3%83%96%E3%83%AB%E3%82%92%E4%BD%9C%E3%82%8B" aria-hidden="true"></a> sqlx-cli で books テーブルを作る</h1>
<a href="https://crates.io/crates/sqlx-cli" target="_blank" rel="nofollow noopener noreferrer">sqlx-cli</a> をインストールして、マイグレーションファイルを作成する
<code>.envrc</code> ファイルに <code>DATABASE_URL</code> 環境変数が設定されているので、そこにテーブルが作成される
<details><summary>sqlx migrate add -r create_books</summary><div class="details-content"><div class="code-block-container"><pre><code class="code-line" data-line="7">$ sqlx migrate add -r init
Creating migrations/20241228224929_init.up.sql
Creating migrations/20241228224929_init.down.sql

$ sqlx migrate add -r create_books
Creating migrations/20241228224948_create_books.up.sql
Creating migrations/20241228224948_create_books.down.sql

</code></pre></div></div></details>
普通に SQL で CREATE TABLE を書く
<details><summary>init.up</summary><div class="details-content"><div class="code-block-container"><pre class="language-sql"><code class="language-sql code-line" data-line="22">CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
CREATE EXTENSION IF NOT EXISTS "moddatetime";

</code></pre></div></div></details>
<ul data-line="29" class="code-line">
<li data-line="29" class="code-line">uuid 使わないけど追加</li>
<li data-line="30" class="code-line">updated_at カラムを更新するために moddatetime</li>
</ul>
<details><summary>create_books.up</summary><div class="details-content"><div class="code-block-container"><pre class="language-sql"><code class="language-sql code-line" data-line="33">CREATE TABLE IF NOT EXISTS books
(
 id BIGINT GENERATED ALWAYS AS IDENTITY,
 title VARCHAR(256) NOT NULL,
 author VARCHAR(256) NOT NULL,
 published_on DATE NOT NULL,
 created_at TIMESTAMP WITH TIME ZONE DEFAULT (current_timestamp),
 updated_at TIMESTAMP WITH TIME ZONE DEFAULT (current_timestamp),
 CONSTRAINT pk_books PRIMARY KEY (id)
);

CREATE TRIGGER tgr_books_updated_at
 AFTER UPDATE
 ON books
 FOR EACH ROW
EXECUTE PROCEDURE moddatetime(updated_at);
</code></pre></div></div></details>
マイグレーションを適用する
<details><summary>sqlx migrate run</summary><div class="details-content"><div class="code-block-container"><pre><code class="code-line" data-line="56">$ sqlx migrate run
Applied 20241228224929/migrate init (13.700543ms)
Applied 20241228224948/migrate create books (4.793553ms)

</code></pre></div></div></details>

<h1 id="books-%E3%83%86%E3%83%BC%E3%83%96%E3%83%AB%E3%81%AB%E3%82%A2%E3%82%AF%E3%82%BB%E3%82%B9%E3%81%99%E3%82%8B" data-line="0" class="code-line">
<a class="header-anchor-link" href="#books-%E3%83%86%E3%83%BC%E3%83%96%E3%83%AB%E3%81%AB%E3%82%A2%E3%82%AF%E3%82%BB%E3%82%B9%E3%81%99%E3%82%8B" aria-hidden="true"></a> books テーブルにアクセスする</h1>
<a href="https://docs.rs/sqlx/0.8.2/sqlx/macro.query_file_as.html" target="_blank" rel="nofollow noopener noreferrer">query_file_as</a> などのマクロを使う。
まずはプロジェクトのルートに sql/books/get_all.sql を用意する
<details><summary>books/get_all.sql</summary><div class="details-content"><div class="code-block-container">
<div class="code-block-filename-container">books/get_all.sql</div>
<pre class="language-sql"><code class="language-sql code-line" data-line="7">SELECT id,
 title,
 author,
 published_on
FROM books
ORDER BY published_on DESC;
</code></pre>
</div></div></details>
この sql を <code>Db</code> が保持する <code>sqlx::PgPool</code> を使って実行するメソッドを用意する
<details><summary>db.rs</summary><div class="details-content"><div class="code-block-container">
<div class="code-block-filename-container">db.rs</div>
<pre class="language-rust"><code class="language-rust code-line" data-line="20">
impl Db {
 // 略

 pub async fn get_all_books(&amp;self) -&gt; AppResult&lt;Vec&lt;Book&gt;&gt; {
 let mut conn = self.acquire().await.change_context(AppError)?;

 let books = sqlx::query_file_as!(Book, "sql/books/get_all.sql")
 .fetch_all(conn.as_mut())
 .await
 .change_context(AppError)?;

 Ok(books)
 }
}

</code></pre>
</div></div></details>
<code>query_file_as!</code> マクロ (ほかのマクロも)は環境変数 <code>DATABASE_URL</code> を参照して、指定のデータベースに対してクエリが正当であり、返却されるカラムが指定された <code>Book</code> と合致していて問題なくマッピングされることを裏で確認してくれる。

<h2 id="%E3%82%AF%E3%82%A8%E3%83%AA%E3%81%8C%E6%AD%A3%E5%B8%B8%E5%8B%95%E4%BD%9C%E3%81%99%E3%82%8B%E3%81%93%E3%81%A8%E3%82%92%E7%A2%BA%E8%AA%8D%E3%81%99%E3%82%8B" data-line="0" class="code-line">
<a class="header-anchor-link" href="#%E3%82%AF%E3%82%A8%E3%83%AA%E3%81%8C%E6%AD%A3%E5%B8%B8%E5%8B%95%E4%BD%9C%E3%81%99%E3%82%8B%E3%81%93%E3%81%A8%E3%82%92%E7%A2%BA%E8%AA%8D%E3%81%99%E3%82%8B" aria-hidden="true"></a> クエリが正常動作することを確認する</h2>
<code>books</code> テーブルに適当にテストデータを入れる
<details><summary>テストデータ投入</summary><div class="details-content"><div class="code-block-container"><pre class="language-sql"><code class="language-sql code-line" data-line="5">INSERT INTO books (title, author, published_on)
VALUES
('The Great Gatsby', 'F. Scott Fitzgerald', '1925-04-10'),
('To Kill a Mockingbird', 'Harper Lee', '1960-07-11'),
('1984', 'George Orwell', '1949-06-08');

</code></pre></div></div></details>
<code>src/bin/t1.rs</code> のように適当なバイナリクレートを作る。ユニットテストを作るよりも簡単
<details><summary>src/bin/t1.rs</summary><div class="details-content"><div class="code-block-container"><pre class="language-rust"><code class="language-rust code-line" data-line="18">#[actix_web::main]
async fn main() -&gt; AppResult&lt;()&gt; {
 let EnvArgs { database_url, .. } = EnvArgs::init()?;
 let db = Db::init(&amp;database_url).await?;
 
 let books = db.get_all_books().await?;
 
 println!("{books:#?}");
 
 Ok(())
}
</code></pre></div></div></details>
これで試しに実行
<details><summary>cargo run --bin t1</summary><div class="details-content"><div class="code-block-container"><pre><code class="code-line" data-line="36">$ cargo run --bin t1
 Compiling book-stack v0.1.0 (/home/kozaki/rust-projects/book-stack)
 Finished `dev` profile [unoptimized + debuginfo] target(s) in 6.09s
 Running `target/debug/t1`
[
 Book {
 id: BookId(
 2,
 ),
 title: "To Kill a Mockingbird",
 author: "Harper Lee",
 published_on: 1960-07-11,
 },
 Book {
 id: BookId(
 3,
 ),
 title: "1984",
 author: "George Orwell",
 published_on: 1949-06-08,
 },
 Book {
 id: BookId(
 1,
 ),
 title: "The Great Gatsby",
 author: "F. Scott Fitzgerald",
 published_on: 1925-04-10,
 },
]

</code></pre></div></div></details>

<h2 id="post-%2Fapi%2Fbooks" data-line="0" class="code-line">
<a class="header-anchor-link" href="#post-%2Fapi%2Fbooks" aria-hidden="true"></a> POST /api/books</h2>
書籍を作成する SQL
<details><summary>books/create.sql</summary><div class="details-content"><div class="code-block-container">
<div class="code-block-filename-container">books/create.sql</div>
<pre class="language-sql"><code class="language-sql code-line" data-line="5">INSERT INTO books (title, author, published_on)
VALUES ($1, $2, $3)
RETURNING id, title, author, published_on;
</code></pre>
</div></div></details>
作成した <code>book</code> を返却するようにして、これを <code>db.rs</code> に入れこむ
<details><summary>db.rs</summary><div class="details-content"><div class="code-block-container">
<div class="code-block-filename-container">db.rs</div>
<pre class="language-rust"><code class="language-rust code-line" data-line="15">impl Db {
 // 略

 pub async fn create(&amp;self, create_book: &amp;CreateBook) -&gt; AppResult&lt;Book&gt; {
 let CreateBook {
 title,
 author,
 published_on,
 } = create_book;
 let book: Book;
 let mut tx = self.begin().await.change_context(AppError)?;
 {
 book = sqlx::query_file_as!(Book, "sql/books/create.sql", title, author, published_on)
 .fetch_one(tx.as_mut())
 .await
 .change_context(AppError)?;
 tx.commit().await.change_context(AppError)?;
 }
 Ok(book)
 }
}
</code></pre>
</div></div></details>
更新系のクエリは <code>pool.begin()</code> でトランザクションを開始して、<code>pool.commit()</code> でコミットするように書いているが、クエリが 1本なのであまり関係ないと思う。
ハンドラに組み込んで
<details><summary>books/post.rs</summary><div class="details-content"><div class="code-block-container">
<div class="code-block-filename-container">books/post.rs</div>
<pre class="language-rust"><code class="language-rust code-line" data-line="46">pub async fn create_book(
 payload: web::Json&lt;CreateBook&gt;,
 db: web::Data&lt;Db&gt;,
) -&gt; Result&lt;impl Responder, ServerError&gt; {
 let create_book = payload.into_inner();
 let book = db.create(&amp;create_book).await?;

 let location = format!("/api/books/{id}", id = book.id);
 Ok(HttpResponse::Created()
 .insert_header((header::LOCATION, location))
 .json(book))
}

</code></pre>
</div></div></details>
できた
<details><summary>xh POST :3000/api/books title="Async Rust" author="Maxwell Flitton, Caroline Morton" published_on="2024-11-12"</summary><div class="details-content"><div class="code-block-container"><pre><code class="code-line" data-line="66">$ xh POST :3000/api/books title="Async Rust" author="Maxwell Flitton, Caroline Morton" published_on="2024-11-12"
HTTP/1.1 201 Created
Content-Length: 101
Content-Type: application/json
Date: Sun, 29 Dec 2024 03:55:06 GMT
Location: /api/books/4

{
 "id": 4,
 "title": "Async Rust",
 "author": "Maxwell Flitton, Caroline Morton",
 "published_on": "2024-11-12"
}

</code></pre></div></div></details>

<h2 id="put-%2Fapi%2Fbooks%2F%7Bid%7D" data-line="0" class="code-line">
<a class="header-anchor-link" href="#put-%2Fapi%2Fbooks%2F%7Bid%7D" aria-hidden="true"></a> PUT /api/books/{id}</h2>
書籍を更新する SQL
<details><summary>books/update.sql</summary><div class="details-content"><div class="code-block-container"><pre class="language-sql"><code class="language-sql code-line" data-line="5">WITH
 updator (id, title, author, published_on) AS (
 VALUES
 ($1::bigint, $2::varchar, $3::varchar, $4::date)
 )
UPDATE books B
SET
 title = CASE
 WHEN updator.title IS NULL THEN B.title
 ELSE updator.title
 END,
 author = CASE
 WHEN updator.author IS NULL THEN B.author
 ELSE updator.author
 END,
 published_on = CASE
 WHEN updator.published_on IS NULL THEN B.published_on
 ELSE updator.published_on
 END
FROM
 updator
WHERE
 B.id = updator.id
RETURNING
 B.id,
 B.title,
 B.author,
 B.published_on
;
</code></pre></div></div></details>
<code>Option::None</code> は <code>NULL</code> としてSQLに渡されるので、その時は値を更新しない 
パラメータ <code>$1</code> などに型を指定しないと <code>query_file_as</code> がうまく動作しない
<code>db.rs</code> も似たようなもの
<details><summary>db.rs</summary><div class="details-content"><div class="code-block-container">
<div class="code-block-filename-container">db.rs</div>
<pre class="language-rust"><code class="language-rust code-line" data-line="44">impl Db {
 // 略

 pub async fn update(
 &amp;self,
 book_id: BookId,
 update_book: &amp;UpdateBook,
 ) -&gt; AppResult&lt;Option&lt;Book&gt;&gt; {
 let UpdateBook {
 title,
 author,
 published_on,
 } = update_book;
 let book: Option&lt;Book&gt;;
 let mut tx = self.begin().await.change_context(AppError)?;
 {
 book = sqlx::query_file_as!(
 Book,
 "sql/books/update.sql",
 book_id as BookId,
 title.as_ref(),
 author.as_ref(),
 published_on.as_ref()
 )
 .fetch_optional(tx.as_mut())
 .await
 .change_context(AppError)?;

 tx.commit().await.change_context(AppError)?;
 }
 Ok(book)
 }
}
</code></pre>
</div></div></details>
パラメータとして渡された <code>&amp;UpdateBook</code> から取り出した <code>title</code> や <code>author</code> は <code>&amp;Option&lt;T&gt;</code> 型なので、<code>as_ref()</code> を当てて <code>Option&lt;&amp;T&gt;</code> に変換してクエリに渡していることに注意
んでハンドラに入れる
<details><summary>books/put.rs</summary><div class="details-content"><div class="code-block-container">
<div class="code-block-filename-container">books/put.rs</div>
<pre class="language-rust"><code class="language-rust code-line" data-line="87">pub async fn update_book(
 path: web::Path&lt;BookId&gt;,
 payload: web::Json&lt;UpdateBook&gt;,
 db: web::Data&lt;Db&gt;,
) -&gt; Result&lt;impl Responder, ServerError&gt; {
 let book_id = path.into_inner();
 let update_book = payload.into_inner();
 let book = db.update(book_id, &amp;update_book).await?;

 match book {
 Some(book) =&gt; Ok(HttpResponse::Ok().json(book)),
 None =&gt; Ok(HttpResponse::NotFound().finish()),
 }
}

</code></pre>
</div></div></details>
できた
<details><summary>xh PUT :3000/api/books/4 title="Async Rust: Unleashing the Power of Fearless Concurrency"</summary><div class="details-content"><div class="code-block-container"><pre><code class="code-line" data-line="109">$ xh PUT :3000/api/books/4 title="Async Rust: Unleashing the Power of Fearless Concurrency"
HTTP/1.1 200 OK
Content-Length: 147
Content-Type: application/json
Date: Sun, 29 Dec 2024 06:24:22 GMT

{
 "id": 4,
 "title": "Async Rust: Unleashing the Power of Fearless Concurrency",
 "author": "Maxwell Flitton, Caroline Morton",
 "published_on": "2024-11-12"
}

</code></pre></div></div></details>

<h2 id="delete-%2Fapi%2Fbooks%2F%7Bid%7D" data-line="0" class="code-line">
<a class="header-anchor-link" href="#delete-%2Fapi%2Fbooks%2F%7Bid%7D" aria-hidden="true"></a> DELETE /api/books/{id}</h2>
削除のやつも同じ
<details><summary>books/delete.sql</summary><div class="details-content"><div class="code-block-container">
<div class="code-block-filename-container">books/delete.sql</div>
<pre class="language-sql"><code class="language-sql code-line" data-line="5">DELETE FROM books
WHERE
 id = $1
RETURNING
 id,
 title,
 author,
 published_on
;
</code></pre>
</div></div></details>
<details><summary>db.rs</summary><div class="details-content"><div class="code-block-container">
<div class="code-block-filename-container">db.rs</div>
<pre class="language-rust"><code class="language-rust code-line" data-line="19">impl Db {
 // 略

 pub async fn delete(&amp;self, book_id: BookId) -&gt; AppResult&lt;Option&lt;Book&gt;&gt; {
 let book: Option&lt;Book&gt;;
 let mut tx = self.begin().await.change_context(AppError)?;
 {
 book = sqlx::query_file_as!(Book, "sql/books/delete.sql", book_id as BookId)
 .fetch_optional(tx.as_mut())
 .await
 .change_context(AppError)?;

 tx.commit().await.change_context(AppError)?;
 }

 Ok(book)
 }
}
</code></pre>
</div></div></details>
<details><summary>books/delete.rs</summary><div class="details-content"><div class="code-block-container">
<div class="code-block-filename-container">books/delete.rs</div>
<pre class="language-rust"><code class="language-rust code-line" data-line="42">pub async fn delete_book(
 path: web::Path&lt;BookId&gt;,
 db: web::Data&lt;Db&gt;,
) -&gt; Result&lt;impl Responder, ServerError&gt; {
 let book_id = path.into_inner();
 let book = db.delete(book_id).await?;

 match book {
 Some(book) =&gt; Ok(HttpResponse::Ok().json(book)),
 None =&gt; Ok(HttpResponse::NotFound().finish()),
 }
}

</code></pre>
</div></div></details>
できた
<details><summary>xh DELETE :3000/api/books/4</summary><div class="details-content"><div class="code-block-container"><pre><code class="code-line" data-line="62">$ xh DELETE :3000/api/books/4
HTTP/1.1 200 OK
Content-Length: 147
Content-Type: application/json
Date: Sun, 29 Dec 2024 06:33:30 GMT

{
 "id": 4,
 "title": "Async Rust: Unleashing the Power of Fearless Concurrency",
 "author": "Maxwell Flitton, Caroline Morton",
 "published_on": "2024-11-12"
}


</code></pre></div></div></details>

<h1 id="%E3%83%86%E3%82%B9%E3%83%88%E3%82%92%E6%9B%B8%E3%81%8F" data-line="0" class="code-line">
<a class="header-anchor-link" href="#%E3%83%86%E3%82%B9%E3%83%88%E3%82%92%E6%9B%B8%E3%81%8F" aria-hidden="true"></a> テストを書く</h1>
テストランナーとしては標準で <code>cargo test</code> があるが、<a href="https://nexte.st/" target="_blank" rel="nofollow noopener noreferrer">cargo-nextest</a> を使う。公式サイトにいろいろ書いてあるけど、テストレポートの見た目がよいので使っている。
ひとまず何もしないテストを作って動作を確認する
<details><summary>directory structure</summary><div class="details-content"><div class="code-block-container"><pre><code class="code-line" data-line="7">/
└ migrations
└ sql
└ src
└ tests
 └ shared
 └ mod.rs
 └ list_books_test.rs
 └ get_book_test.rs
</code></pre></div></div></details>
インテグレーションテストのディレクトリ <code>tests</code> の中のファイルは個別のクレートとしてコンパイルされるので、上の例だと <code>list_books_test</code> と <code>get_book_test</code> クレートが個別に作られる
<code>shared</code> に共通のロジックを入れるが、これは <code>list_books_test</code> や <code>get_book_tests</code> クレートに重複して差し込まれて動作する
<details><summary>tests/list_books_test.rs</summary><div class="details-content"><div class="code-block-container">
<div class="code-block-filename-container">tests/list_books_test.rs</div>
<pre class="language-rust"><code class="language-rust code-line" data-line="25">mod shared;

#[test]
fn it_works() {
 shared::setup();
 assert_eq!(1 + 1, 2);
}

</code></pre>
</div></div></details>
<details><summary>tests/get_book_test.rs</summary><div class="details-content"><div class="code-block-container">
<div class="code-block-filename-container">tests/get_book_test.rs</div>
<pre class="language-rust"><code class="language-rust code-line" data-line="38">mod shared;

#[test]
fn it_also_works() {
 shared::setup();
 assert_ne!(1 + 2, 1);
}
</code></pre>
</div></div></details>
<details><summary>tests/shared/mod.rs</summary><div class="details-content"><div class="code-block-container">
<div class="code-block-filename-container">tests/shared/mod.rs</div>
<pre class="language-rust"><code class="language-rust code-line" data-line="50">pub fn setup() {
 println!("Setup");
}
</code></pre>
</div></div></details>
実行する
<details><summary>cargo textest run</summary><div class="details-content"><div class="code-block-container"><pre><code class="code-line" data-line="60">$ cargo nextest run
 Compiling book-stack v0.1.0 (/home/kozaki/rust-projects/book-stack)
 Finished `test` profile [unoptimized + debuginfo] target(s) in 0.66s
────────────
 Nextest run ID 3e328e0c-b508-4391-b95f-7f29ff5693ff with nextest profile: default
 Starting 2 tests across 5 binaries
 PASS [ 0.013s] book-stack::list_books_test it_works
 PASS [ 0.014s] book-stack::get_book_test it_also_works
────────────
 Summary [ 0.015s] 2 tests run: 2 passed, 0 skipped

</code></pre></div></div></details>

<h2 id="actix-web-%E3%81%AE%E3%83%86%E3%82%B9%E3%83%88%E3%82%92%E6%9B%B8%E3%81%8F" data-line="0" class="code-line">
<a class="header-anchor-link" href="#actix-web-%E3%81%AE%E3%83%86%E3%82%B9%E3%83%88%E3%82%92%E6%9B%B8%E3%81%8F" aria-hidden="true"></a> Actix Web のテストを書く</h2>
<a href="https://actix.rs/docs/testing#integration-testing-for-applications" target="_blank" rel="nofollow noopener noreferrer">Integration Testing For Applications</a> のコードを <code>list_books_test.rs</code> にコピる
<details><summary>tests/list_books_test.rs</summary><div class="details-content"><div class="code-block-container">
<div class="code-block-filename-container">tests/list_books_test.rs</div>
<pre class="language-rust"><code class="language-rust code-line" data-line="5">#[actix_web::test]
async fn list_books_test() -&gt; AppResult&lt;()&gt; {
 let db = Db::init("postgres://xxxx:yyyy@localhost:5432/stackdb").await?;
 let data = web::Data::new(db);

 let app = test::init_service(
 App::new()
 .app_data(data.clone())
 .wrap(middleware::Logger::default())
 .configure(api::api_route),
 )
 .await;
 let req = test::TestRequest::get().uri("/api/books").to_request();
 let books = test::call_and_read_body_json::&lt;_, _, Vec&lt;Book&gt;&gt;(&amp;app, req).await;

 assert_eq!(books.len(), 4);

 Ok(())
}

</code></pre>
</div></div></details>
非常に脆いテストだが、最初のステップとしてはこれで
<ul data-line="30" class="code-line">
<li data-line="30" class="code-line">データベースへの接続もそのままハードコーディング。</li>
<li data-line="31" class="code-line">戻り値の書籍の件数もデータベースに実際に入っている件数をハードコーディング。</li>
</ul>
<details><summary>cargo nextest run</summary><div class="details-content"><div class="code-block-container"><pre><code class="code-line" data-line="34"> Finished `test` profile [unoptimized + debuginfo] target(s) in 6.16s
────────────
 Nextest run ID 94c6ec36-0862-4f8f-bc96-d2a1dcb82298 with nextest profile: default
 Starting 2 tests across 5 binaries
 PASS [ 0.013s] book-stack::get_book_test it_also_works
 PASS [ 0.089s] book-stack::list_books_test list_books_test
────────────
 Summary [ 0.092s] 2 tests run: 2 passed, 0 skipped

</code></pre></div></div></details>
0.089秒か。

<h2 id="%E3%81%95%E3%82%89%E3%81%AB-tests-%E3%81%AE%E9%9A%8E%E5%B1%A4%E3%82%92%E6%95%B4%E7%90%86%E3%81%99%E3%82%8B" data-line="0" class="code-line">
<a class="header-anchor-link" href="#%E3%81%95%E3%82%89%E3%81%AB-tests-%E3%81%AE%E9%9A%8E%E5%B1%A4%E3%82%92%E6%95%B4%E7%90%86%E3%81%99%E3%82%8B" aria-hidden="true"></a> さらに tests の階層を整理する</h2>
<code>tests</code> ディレクトリに <code>integration_tests.rs</code> を 1ファイル作って、ここにテストのクレートを集約する
<details><summary>階層</summary><div class="details-content"><div class="code-block-container"><pre><code class="code-line" data-line="5">tests
└ books
 └ mod.rs
 └ get_book_test.rs (書籍を取得するテスト)
 └ list_books_test.rs (書籍を一覧するテスト)
└ shared
 └ mod.rs (共通の機能を実装する起点)
└ integration_tests.rs
</code></pre></div></div></details>

<h2 id="main.rs-%E3%82%92%E4%BF%AE%E6%AD%A3%E3%81%99%E3%82%8B" data-line="0" class="code-line">
<a class="header-anchor-link" href="#main.rs-%E3%82%92%E4%BF%AE%E6%AD%A3%E3%81%99%E3%82%8B" aria-hidden="true"></a> main.rs を修正する</h2>
<code>main.rs</code> で <code>api_route</code> を使うところで、『実際の』<code>Db</code> を渡す
<details><summary>main.rs</summary><div class="details-content"><div class="code-block-container">
<div class="code-block-filename-container">main.rs</div>
<pre class="diff-highlight language-diff-rust"><code class="diff-highlight language-diff-rust code-line" data-line="5"> HttpServer::new(move || {
 App::new()
 .app_data(data.clone())
 .wrap(middleware::Logger::default())
- .configure(api::api_route)
+ .configure(api::api_route::&lt;Db&gt;)
 .configure(swagger_route)
 })
 .bind(addrs)
 .change_context(AppError)?
 .run()
 .await
 .change_context(AppError)?;

</code></pre>
</div></div></details>
ここに指定している <code>Db</code> だけ、ジェネリックパラメータではなくて、実際の構造体
ついでに <code>App</code> ではなく、<code>api_route</code> の側に <code>Db</code> を寄せることにする ( swagger のルーティングはデータベース使わないので )
こんな風に使いたい
<div class="code-block-container"><pre class="diff-highlight language-diff-rust"><code class="diff-highlight language-diff-rust code-line" data-line="29"> HttpServer::new(move || {
 App::new()
- .app_data(data.clone())
 .wrap(middleware::Logger::default())
- .configure(api::api_route::&lt;Db&gt;)
+ .configure(api::api_route_with(data.clone()))
 .configure(swagger_route)
 })
 .bind(addrs)
 .change_context(AppError)?
 .run()
 .await
 .change_context(AppError)?;

</code></pre></div><code>api_route_with</code> 関数を <code>web::Data&lt;Db&gt;</code> を受け取って、<code>api::api_route::&lt;Db&gt;</code> に相当するクロージャーを返却するようにすればよさそう
<details><summary>routes/api.rs</summary><div class="details-content"><div class="code-block-container">
<div class="code-block-filename-container">routes/api.rs</div>
<pre class="diff-highlight language-diff-rust"><code class="diff-highlight language-diff-rust code-line" data-line="49">pub fn api_route&lt;Db&gt;(cfg: &amp;mut web::ServiceConfig)
where
 Db: repositories::BooksRepository + 'static,
{
 cfg.service(web::scope("/api").configure(books_route::&lt;Db&gt;));
}

+ pub fn api_route_with&lt;Db&gt;(db: web::Data&lt;Db&gt;) -&gt; impl FnOnce(&amp;mut web::ServiceConfig)
+ where
+ Db: repositories::BooksRepository + 'static,
+ {
+ move |cfg: &amp;mut web::ServiceConfig| {
+ cfg.app_data(db)
+ .service(web::scope("/api").configure(books_route::&lt;Db&gt;));
+ }
+ }

</code></pre>
</div></div></details>
<code>api_route</code> 関数に相当するクロージャーは <code>FnOnce(&amp;mut web::ServiceConfig)</code> を実装しているので、これを impl Trait で返却する関数を実装すればよい。
これで <code>main</code> 関数では <code>api_route_with</code> に渡した <code>data</code>の型によってジェネリックパラメータが推論されるので明示的に指定する必要がなくなる。

<h2 id="tests%2Fbooks%2Fget_book_test.rs" data-line="0" class="code-line">
<a class="header-anchor-link" href="#tests%2Fbooks%2Fget_book_test.rs" aria-hidden="true"></a> tests/books/get_book_test.rs</h2>
書籍を ID を指定して取得するテスト
<details><summary>tests/books/get_book_test.rs</summary><div class="details-content"><div class="code-block-container">
<div class="code-block-filename-container">tests/books/get_book_test.rs</div>
<pre class="language-rust"><code class="language-rust code-line" data-line="5">#[actix_web::test]
async fn get_book_found_test() -&gt; AppResult&lt;()&gt; {
 let db = setup_db();
 let data = web::Data::new(db);

 let app = test::init_service(
 App::new()
 .wrap(middleware::Logger::default())
 .configure(api::api_route_with(data.clone())),
 )
 .await;
 let req = test::TestRequest::get().uri("/api/books/1").to_request();
 let book = test::call_and_read_body_json::&lt;_, _, Book&gt;(&amp;app, req).await;

 assert_eq!(
 book,
 Book {
 id: 1.into(),
 title: "Title 1".into(),
 author: "Author 1".into(),
 published_on: date!(2024 - 01 - 01),
 }
 );

 Ok(())
}

#[actix_web::test]
async fn get_book_not_found_test() -&gt; AppResult&lt;()&gt; {
 let db = setup_db();
 let data = web::Data::new(db);

 let app = test::init_service(
 App::new()
 .wrap(middleware::Logger::default())
 .configure(api::api_route_with(data.clone())),
 )
 .await;
 let req = test::TestRequest::get().uri("/api/books/100").to_request();
 let res = test::call_service(&amp;app, req).await;

 assert_eq!(res.status(), StatusCode::NOT_FOUND);

 Ok(())
}

fn setup_db() -&gt; impl BooksRepository {
 let book = Book {
 id: 1.into(),
 title: "Title 1".into(),
 author: "Author 1".into(),
 published_on: date!(2024 - 01 - 01),
 };

 let mut db = MockBooksRepository::new();
 db.expect_get_book_by_id()
 .with(predicate::eq(BookId::new(1)))
 .returning(move |_| {
 let book = book.clone();
 Box::pin(async move { Ok(Some(book)) })
 });
 db.expect_get_book_by_id()
 .with(predicate::ne(BookId::new(1)))
 .returning(move |_| Box::pin(async { Ok(None) }));

 db
}
</code></pre>
</div></div></details>

<h2 id="assert2-%E5%B0%8E%E5%85%A5" data-line="0" class="code-line">
<a class="header-anchor-link" href="#assert2-%E5%B0%8E%E5%85%A5" aria-hidden="true"></a> assert2 導入</h2>
テストのアサーションライブラリ <a href="https://crates.io/crates/assert2" target="_blank" rel="nofollow noopener noreferrer">assert2</a> を導入する
<details><summary>Cargo.toml</summary><div class="details-content"><div class="code-block-container">
<div class="code-block-filename-container">Cargo.toml</div>
<pre class="diff-highlight language-diff-toml"><code class="diff-highlight language-diff-toml code-line" data-line="5">[dev-dependencies]
mockall = { version = "0.13.1", features = [] }
+ assert2 = { version = "0.3.15", features = [] }

</code></pre>
</div></div></details>
テストを修正
<details><summary>tests/books/list_books_test.rs</summary><div class="details-content"><div class="code-block-container">
<div class="code-block-filename-container">tests/books/list_books_test.rs</div>
<pre class="diff-highlight language-diff-rust"><code class="diff-highlight language-diff-rust code-line" data-line="16">
- let mut db = MockBooksRepository::new();
- db.expect_get_all_books().returning(move || {
- let books = books.clone();
- Box::pin(async move { Ok(books) })
- });
-
+ let db = setup_db(&amp;books);
 let data = web::Data::new(db);

 let app = test::init_service(
 App::new()
 .wrap(middleware::Logger::default())
 .configure(api::api_route_with(data.clone())),
 )
 .await;
 let req = test::TestRequest::get().uri("/api/books").to_request();
 let res = test::call_and_read_body_json::&lt;_, _, Vec&lt;Book&gt;&gt;(&amp;app, req).await;

- assert_eq!(res.len(), 3);
+ check!(res == books);

 Ok(())
}

+ fn setup_db(books: &amp;[Book]) -&gt; impl BooksRepository {
+ let mut db = MockBooksRepository::new();
+ let books = books.to_vec();
+ db.expect_get_all_books().returning(move || {
+ let books = books.clone();
+ Box::pin(async move { Ok(books) })
+ });
+
+ db
+ }
</code></pre>
</div></div></details>
nightly の方がよいのかな？ <a href="https://docs.rs/assert2/0.3.15/assert2/#difference-between-stable-and-nightly" target="_blank" rel="nofollow noopener noreferrer">Difference between stable and nightly.</a>
<details><summary>cargo +nightly nextest run</summary><div class="details-content"><div class="code-block-container"><pre><code class="code-line" data-line="58">$ cargo +nightly nextest run
 Finished `test` profile [unoptimized + debuginfo] target(s) in 0.26s
────────────
 Nextest run ID 502a7133-9dca-4e2e-a50e-85f8f3a20dc0 with nextest profile: default
 Starting 3 tests across 3 binaries
 PASS [ 0.023s] book-stack tests::books::get_book_test::get_book_not_found_test
 PASS [ 0.024s] book-stack tests::books::list_books_test::list_books_test
 PASS [ 0.026s] book-stack tests::books::get_book_test::get_book_found_test
────────────
 Summary [ 0.029s] 3 tests run: 3 passed, 0 skipped

</code></pre></div></div></details>

<h1 id="%E3%83%90%E3%83%AA%E3%83%87%E3%83%BC%E3%82%B7%E3%83%A7%E3%83%B3%E3%82%92%E8%BF%BD%E5%8A%A0%E3%81%99%E3%82%8B" data-line="0" class="code-line">
<a class="header-anchor-link" href="#%E3%83%90%E3%83%AA%E3%83%87%E3%83%BC%E3%82%B7%E3%83%A7%E3%83%B3%E3%82%92%E8%BF%BD%E5%8A%A0%E3%81%99%E3%82%8B" aria-hidden="true"></a> バリデーションを追加する</h1>
<a href="https://docs.rs/actix-web-validation/latest/actix_web_validation/" target="_blank" rel="nofollow noopener noreferrer">actix_web_validation</a> を使うことで、Actix Web の <a href="https://actix.rs/docs/extractors" target="_blank" rel="nofollow noopener noreferrer">Extractors</a> にバリデーションチェックを組込める
非常によく似た <a href="https://docs.rs/actix-web-validator/latest/actix_web_validator/" target="_blank" rel="nofollow noopener noreferrer">actix_web_validator</a> というクレートもあるが、Actix Web の標準の <code>Path</code> エクストラクタなどを上書きしてしまうので個人的には好みでないので使わない。
まずは クレートをインストール
<details><summary>Cargo.toml</summary><div class="details-content"><div class="code-block-container">
<div class="code-block-filename-container">Cargo.toml</div>
<pre class="diff-highlight language-diff-toml"><code class="diff-highlight language-diff-toml code-line" data-line="9">[dependencies]
actix-web = { version = "4", features = [] }
+ actix-web-validation = { version = "0.7.0", features = ["validator"] }
+ validator = { version = "0.19.0", features = ["derive"] }
clap = { version = "4.5.23", features = ["derive", "env"] }
derive_more = { version = "1.0.0", features = [
 "constructor",

</code></pre>
</div></div></details>
<code>create_book.rs</code> にバリデーションを追加する
<details><summary>payloads/create_book.rs</summary><div class="details-content"><div class="code-block-container">
<div class="code-block-filename-container">payloads/create_book.rs</div>
<pre class="diff-highlight language-diff-rust"><code class="diff-highlight language-diff-rust code-line" data-line="24">- #[derive(Debug, Clone, Eq, PartialEq, Serialize, Deserialize, ToSchema)]
+ #[derive(Debug, Clone, Eq, PartialEq, Serialize, Deserialize, ToSchema, Validate)]
pub struct CreateBook {
+ #[validate(length(max = 256))]
 pub title: String,
+ #[validate(length(max = 256))]
 pub author: String,
 pub published_on: time::Date,
}

</code></pre>
</div></div></details>
リクエストハンドラのエクストラクタを変更する
<details><summary>handlers/books/post.rs</summary><div class="details-content"><div class="code-block-container">
<div class="code-block-filename-container">handlers/books/post.rs</div>
<pre class="diff-highlight language-diff-rust"><code class="diff-highlight language-diff-rust code-line" data-line="41">pub async fn create_book&lt;Db&gt;(
+ Validated(payload): Validated&lt;web::Json&lt;CreateBook&gt;&gt;,
 db: web::Data&lt;Db&gt;,
) -&gt; Result&lt;impl Responder, ServerError&gt;
where
 Db: repositories::BooksRepository,
{
 let create_book = payload.into_inner();
 let book = db.create(&amp;create_book).await?;

 let location = format!("/api/books/{id}", id = book.id);
 Ok(HttpResponse::Created()
 .insert_header((header::LOCATION, location))
 .json(book))
}
</code></pre>
</div></div></details>
テストも追加する
<details><summary>tests/books/create_book_test.rs</summary><div class="details-content"><div class="code-block-container">
<div class="code-block-filename-container">tests/books/create_book_test.rs</div>
<pre class="language-rust"><code class="language-rust code-line" data-line="63">#[actix_web::test]
async fn validation_error_create_book_test() -&gt; AppResult&lt;()&gt; {
 let new_id = BookId::new(42);

 let db = setup_db(new_id);
 let data = web::Data::new(db);

 let app = test::init_service(
 App::new()
 .wrap(middleware::Logger::default())
 .configure(api::api_route_with(data.clone())),
 )
 .await;
 let create_book = CreateBook {
 title: "Title 1".into(),
 author: "a".repeat(257),
 published_on: date!(2024 - 02 - 07),
 };
 let req = test::TestRequest::post()
 .uri("/api/books")
 .set_json(create_book.clone())
 .to_request();
 let res = test::call_service(&amp;app, req).await;
 let status = res.status();
 let body = test::read_body(res).await;
 let body = String::from_utf8(body.to_vec()).unwrap_or_default();

 check!(status == StatusCode::BAD_REQUEST);
 check!(body.contains("Validation error: length"));

 Ok(())
}
</code></pre>
</div></div></details>

<h1 id="%E8%AA%8D%E8%A8%BC%E3%83%BB%E8%AA%8D%E5%8F%AF%E3%81%AE%E5%AE%9F%E8%A3%85%E3%82%92%E3%81%99%E3%82%8B" data-line="0" class="code-line">
<a class="header-anchor-link" href="#%E8%AA%8D%E8%A8%BC%E3%83%BB%E8%AA%8D%E5%8F%AF%E3%81%AE%E5%AE%9F%E8%A3%85%E3%82%92%E3%81%99%E3%82%8B" aria-hidden="true"></a> 認証・認可の実装をする</h1>
<ul data-line="2" class="code-line">
<li data-line="2" class="code-line">単純なトークンベースの認証を行うこととする</li>
<li data-line="3" class="code-line">認証されている / されていない だけの区別でそれ以上の User権限、Admin権限のような区別はなし</li>
</ul>
<iframe id="zenn-embedded__6f6976c0c29f9" src="https://embed.zenn.studio/mermaid#zenn-embedded__6f6976c0c29f9" data-content="sequenceDiagram%0A%20%20%20%20participant%20Client%20as%20%E3%82%AF%E3%83%A9%E3%82%A4%E3%82%A2%E3%83%B3%E3%83%88%0A%20%20%20%20box%20Cornsilk%20%E7%90%86%E8%A7%A3%E3%81%AE%E3%81%9F%E3%82%81%E3%81%AB%E5%88%86%E3%81%91%E3%81%A6%E6%9B%B8%E3%81%8F%0A%20%20%20%20%20%20%20%20participant%20AuthServer%20as%20%E8%AA%8D%E8%A8%BC%E3%82%B5%E3%83%BC%E3%83%90%E3%83%BC%0A%20%20%20%20%20%20%20%20participant%20Server%20as%20AP%E3%82%B5%E3%83%BC%E3%83%90%E3%83%BC%0A%20%20%20%20end%0A%20%20%20%20participant%20DB%20as%20%E3%83%87%E3%83%BC%E3%82%BF%E3%83%99%E3%83%BC%E3%82%B9%0A%20%20%20%20Client%20-%3E%3E%20AuthServer%3A%20POST%20%2Fauth%2Flogin%0A%20%20%20%20activate%20AuthServer%0A%20%20%20%20AuthServer%20-%3E%3E%20DB%3A%20email%20%26%20password%0A%20%20%20%20activate%20DB%0A%20%20%20%20Note%20right%20of%20AuthServer%3A%20authenticate%0A%20%20%20%20DB%20--%3E%3E%20AuthServer%3A%20valid%20user%0A%20%20%20%20deactivate%20DB%0A%20%20%20%20AuthServer%20--%3E%3E%20Client%3A%20Response%20JWT%20token%0A%20%20%20%20deactivate%20AuthServer%0A%20%20%20%20Client%20-%3E%3E%20Server%3A%20POST%20%2Fapi%2Fbooks%20with%20JTW%20header%0A%20%20%20%20activate%20Server%0A%20%20%20%20Server%20-%3E%3E%20AuthServer%3A%20JWT%20token%0A%20%20%20%20activate%20AuthServer%0A%20%20%20%20Note%20right%20of%20AuthServer%3A%20validate%0A%20%20%20%20AuthServer%20--%3E%3E%20Server%3A%20valid%20token%0A%20%20%20%20deactivate%20AuthServer%0A%20%20%20%20Server%20-%3E%3E%20Server%3A%20Only%20valid%20or%20not%0A%20%20%20%20Note%20right%20of%20Server%3A%20Authorize%0A%20%20%20%20Server%20-%3E%3E%20DB%3A%20create%20new%20book%0A%20%20%20%20activate%20DB%0A%20%20%20%20DB%20--%3E%3E%20Server%3A%20successfully%20created%0A%20%20%20%20deactivate%20DB%0A%20%20%20%20Server%20--%3E%3E%20Client%3A%20created%20book%20Response%0A%20%20%20%20deactivate%20Server" frameborder="0" scrolling="no" loading="lazy"></iframe>

<h2 id="%E4%BD%BF%E7%94%A8%E3%81%99%E3%82%8B%E3%82%AF%E3%83%AC%E3%83%BC%E3%83%88%E3%82%92%E9%81%B8%E5%AE%9A%E3%81%99%E3%82%8B" data-line="0" class="code-line">
<a class="header-anchor-link" href="#%E4%BD%BF%E7%94%A8%E3%81%99%E3%82%8B%E3%82%AF%E3%83%AC%E3%83%BC%E3%83%88%E3%82%92%E9%81%B8%E5%AE%9A%E3%81%99%E3%82%8B" aria-hidden="true"></a> 使用するクレートを選定する</h2>
<ul data-line="2" class="code-line">
<li data-line="2" class="code-line">
<a href="https://crates.io/crates/actix-web-grants" target="_blank" rel="nofollow noopener noreferrer">actix-web-grants</a>
<ul data-line="3" class="code-line">
<li data-line="3" class="code-line">リクエストヘッダからトークンを取り出して URL ごとに認可をする</li>
</ul>
</li>
<li data-line="4" class="code-line">
<a href="https://crates.io/crates/actix-web-httpauth" target="_blank" rel="nofollow noopener noreferrer">actix-web-httpauth</a>
<ul data-line="5" class="code-line">
<li data-line="5" class="code-line">actix-web-grants で使う(？)</li>
</ul>
</li>
<li data-line="6" class="code-line">
<a href="https://crates.io/crates/jsonwebtoken" target="_blank" rel="nofollow noopener noreferrer">jsonwebtoken</a>
<ul data-line="7" class="code-line">
<li data-line="7" class="code-line">JWTトークンを生成する</li>
</ul>
</li>
<li data-line="8" class="code-line">
<a href="https://crates.io/crates/bcrypt" target="_blank" rel="nofollow noopener noreferrer">bcrypt</a>
<ul data-line="9" class="code-line">
<li data-line="9" class="code-line">パスワードをハッシュ化する</li>
</ul>
</li>
</ul>

<h1 id="users-%E3%83%86%E3%83%BC%E3%83%96%E3%83%AB%E3%82%92%E4%BD%9C%E3%82%8B" data-line="0" class="code-line">
<a class="header-anchor-link" href="#users-%E3%83%86%E3%83%BC%E3%83%96%E3%83%AB%E3%82%92%E4%BD%9C%E3%82%8B" aria-hidden="true"></a> users テーブルを作る</h1>
認証につかう <code>users</code>テーブルを用意
<details><summary>users table</summary><div class="details-content"><div class="code-block-container"><pre class="language-sql"><code class="language-sql code-line" data-line="5">CREATE TABLE IF NOT EXISTS users
(
 id BIGINT GENERATED ALWAYS AS IDENTITY,
 email VARCHAR(256) NOT NULL,
 password_hash VARCHAR(256) NOT NULL,
 display_name VARCHAR(256) NULL,
 created_at TIMESTAMP WITH TIME ZONE DEFAULT (current_timestamp),
 updated_at TIMESTAMP WITH TIME ZONE DEFAULT (current_timestamp),
 CONSTRAINT pk_users PRIMARY KEY (id)
);
</code></pre></div></div></details>

<h1 id="%E8%AA%8D%E8%A8%BC%E3%81%AE-url-%E3%82%92%E8%A8%AD%E8%A8%88%E3%81%99%E3%82%8B" data-line="0" class="code-line">
<a class="header-anchor-link" href="#%E8%AA%8D%E8%A8%BC%E3%81%AE-url-%E3%82%92%E8%A8%AD%E8%A8%88%E3%81%99%E3%82%8B" aria-hidden="true"></a> 認証の URL を設計する</h1>
<table data-line="2" class="code-line">
<thead data-line="2" class="code-line">
<tr data-line="2" class="code-line">
<th>method</th>
<th>url</th>
<th>説明</th>
</tr>
</thead>
<tbody data-line="4" class="code-line">
<tr data-line="4" class="code-line">
<td>POST</td>
<td>/auth/register</td>
<td>ユーザーを登録する</td>
</tr>
<tr data-line="5" class="code-line">
<td>POST</td>
<td>/auth/login</td>
<td>ユーザーを認証する</td>
</tr>
</tbody>
</table>
いずれのリクエストに対しても、認証に成功すれば <code>/api</code> にアクセスするための JWT トークンを返却する
<details><summary>JWTトークンレスポンス</summary><div class="details-content"><div class="code-block-container"><pre class="language-json"><code class="language-json code-line" data-line="10">{
 "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX2lkIjoxMjM0NTY3ODkwLCJ1c2VybmFtZSI6IkpvaG5Eb2UiLCJleHBpcmVkIjoxNjIxMjM3NjAwfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
}
</code></pre></div></div></details>

<h2 id="%E3%83%91%E3%82%B9%E3%83%AF%E3%83%BC%E3%83%89%E3%82%92%E3%83%8F%E3%83%83%E3%82%B7%E3%83%A5%E5%8C%96%E3%81%97%E3%81%A6%E4%BF%9D%E5%AD%98%E3%81%99%E3%82%8B" data-line="0" class="code-line">
<a class="header-anchor-link" href="#%E3%83%91%E3%82%B9%E3%83%AF%E3%83%BC%E3%83%89%E3%82%92%E3%83%8F%E3%83%83%E3%82%B7%E3%83%A5%E5%8C%96%E3%81%97%E3%81%A6%E4%BF%9D%E5%AD%98%E3%81%99%E3%82%8B" aria-hidden="true"></a> パスワードをハッシュ化して保存する</h2>
<a href="https://crates.io/crates/bcrypt" target="_blank" rel="nofollow noopener noreferrer">bcrypt の Usage</a> に使い方が書いてあるので、これを <code>auth_repository.rs</code> に追加する
パスワードのハッシュ化には <a href="https://docs.rs/argon2/0.5.3/argon2/" target="_blank" rel="nofollow noopener noreferrer">argon2</a> もあるけど、使い方が複雑すぎる。とりあえずこんなに要らない
<details><summary>db/auth_repository.rs</summary><div class="details-content"><div class="code-block-container">
<div class="code-block-filename-container">db/auth_repository.rs</div>
<pre class="diff-highlight language-diff-rust"><code class="diff-highlight language-diff-rust code-line" data-line="7">
impl AuthRepository for super::Db {
 async fn register(&amp;self, register_user: &amp;RegisterUser) -&gt; AppResult&lt;Maybe&lt;User&gt;&gt; {
 let RegisterUser { email, password, display_name } = register_user;

+ let password_hash = bcrypt::hash(password.as_bytes(), bcrypt::DEFAULT_COST).change_context(AppError)?;

 let user: Maybe&lt;User&gt;;
 let mut tx = self.begin().await.change_context(AppError)?;
 {
 let optional_user = sqlx::query_file_as!(User, "sql/users/get_by_email.sql", email)
 .fetch_optional(tx.as_mut())
 .await
 .change_context(AppError)?;

 if optional_user.is_some() {
 return Ok(Maybe::error_with(format!(
 "The email = {email} is already registered"
 )));
 }

 user = sqlx::query_file_as!(
 User,
 "sql/users/create.sql",
 email,
 password_hash,
 display_name.as_ref()
 )
 .fetch_one(tx.as_mut())
 .await
 .change_context(AppError)?
 .into();

 tx.commit().await.change_context(AppError)?;
 }

 Ok(user)
 }

 async fn login(&amp;self, login_user: &amp;LoginUser) -&gt; AppResult&lt;Maybe&lt;User&gt;&gt; {
 let LoginUser { email, password } = login_user;

 let mut conn = self.acquire().await.change_context(AppError)?;
 let user = sqlx::query_file_as!(User, "sql/users/get_by_email.sql", email)
 .fetch_optional(conn.as_mut())
 .await
 .change_context(AppError)?;

 let user = match user {
 Some(user) =&gt; {
+ let verified = bcrypt::verify(password, &amp;user.password_hash).change_context(AppError)?;
 if !verified {
 return Ok(Maybe::error_with("email and password are invalid"));
 }
 user
 }
 None =&gt; {
 return Ok(Maybe::error_with("email and password are invalid"));
 }
 };

 Ok(user.into())
 }
}


</code></pre>
</div></div></details>

<h2 id="%E3%83%8F%E3%83%B3%E3%83%89%E3%83%A9%E3%81%A7-jwt-%E3%83%88%E3%83%BC%E3%82%AF%E3%83%B3%E3%82%92%E7%94%9F%E6%88%90%E3%81%99%E3%82%8B" data-line="0" class="code-line">
<a class="header-anchor-link" href="#%E3%83%8F%E3%83%B3%E3%83%89%E3%83%A9%E3%81%A7-jwt-%E3%83%88%E3%83%BC%E3%82%AF%E3%83%B3%E3%82%92%E7%94%9F%E6%88%90%E3%81%99%E3%82%8B" aria-hidden="true"></a> ハンドラで JWT トークンを生成する</h2>
<code>AppState</code> にJWTエンコーディングする構造体を入れたので、ハンドラ関数で取り出して使うだけ
<details><summary>handlers/auth/login.rs</summary><div class="details-content"><div class="code-block-container">
<div class="code-block-filename-container">handlers/auth/login.rs</div>
<pre class="diff-highlight language-diff-rust"><code class="diff-highlight language-diff-rust code-line" data-line="5">pub async fn login&lt;DB&gt;(
 payload: web::Json&lt;LoginUser&gt;,
 state: web::Data&lt;AppState&lt;DB&gt;&gt;,
) -&gt; Result&lt;impl Responder, ServerError&gt;
where
 DB: AuthRepository + 'static,
{
 let login_user = payload.into_inner();
 let user = state.db.login(&amp;login_user).await?;
+ let response = match user {
+ Maybe::Present(user) =&gt; {
+ let claims = UserClaims::from(user);
+ let token = state.jwt.encode(claims)?;
+ HttpResponse::Ok().json(token)
+ }
+ Maybe::Error { message } =&gt; HttpResponse::Unauthorized().body(message),
+ };
 Ok(response)
}
</code></pre>
</div></div></details>
<details><summary>handlers/auth/register.rs</summary><div class="details-content"><div class="code-block-container">
<div class="code-block-filename-container">handlers/auth/register.rs</div>
<pre class="diff-highlight language-diff-rust"><code class="diff-highlight language-diff-rust code-line" data-line="29">pub async fn register&lt;DB&gt;(
 payload: web::Json&lt;RegisterUser&gt;,
 state: web::Data&lt;AppState&lt;DB&gt;&gt;,
) -&gt; Result&lt;impl Responder, ServerError&gt;
where
 DB: AuthRepository + 'static,
{
 let register_user = payload.into_inner();
 let user = state.db.register(&amp;register_user).await?;
+ let response = match user {
+ Maybe::Present(user) =&gt; {
+ let claims = UserClaims::from(user);
+ let token = state.jwt.encode(claims)?;
+ HttpResponse::Ok().json(token)
+ }
+ Maybe::Error { message } =&gt; HttpResponse::BadRequest().body(message),
+ };
 Ok(response)
}
</code></pre>
</div></div></details>

<h2 id="%E3%83%A6%E3%83%BC%E3%82%B6%E3%83%BC%E7%99%BB%E9%8C%B2%E3%80%81%E3%83%A6%E3%83%BC%E3%82%B6%E3%83%BC%E8%AA%8D%E8%A8%BC%E3%81%AE%E3%83%AA%E3%82%AF%E3%82%A8%E3%82%B9%E3%83%88%E3%81%AB%E3%83%90%E3%83%AA%E3%83%87%E3%83%BC%E3%82%B7%E3%83%A7%E3%83%B3%E3%82%92%E4%BB%98%E3%81%91%E3%82%8B" data-line="0" class="code-line">
<a class="header-anchor-link" href="#%E3%83%A6%E3%83%BC%E3%82%B6%E3%83%BC%E7%99%BB%E9%8C%B2%E3%80%81%E3%83%A6%E3%83%BC%E3%82%B6%E3%83%BC%E8%AA%8D%E8%A8%BC%E3%81%AE%E3%83%AA%E3%82%AF%E3%82%A8%E3%82%B9%E3%83%88%E3%81%AB%E3%83%90%E3%83%AA%E3%83%87%E3%83%BC%E3%82%B7%E3%83%A7%E3%83%B3%E3%82%92%E4%BB%98%E3%81%91%E3%82%8B" aria-hidden="true"></a> ユーザー登録、ユーザー認証のリクエストにバリデーションを付ける</h2>
ユーザー名やパスワードの長さなど、データベースアクセスが不要な分はバリデーションを付けるだけ
<details><summary>payloads/login_user.rs</summary><div class="details-content"><div class="code-block-container">
<div class="code-block-filename-container">payloads/login_user.rs</div>
<pre class="diff-highlight language-diff-rust"><code class="diff-highlight language-diff-rust code-line" data-line="5">- #[derive(Debug, Clone, Eq, PartialEq, Serialize, Deserialize)]
+ #[derive(Debug, Clone, Eq, PartialEq, Serialize, Deserialize, Validate)]
pub struct LoginUser {
+ #[validate(email)]
 pub email: String,
+ #[validate(length(min = 10))]
 pub password: String,
}

</code></pre>
</div></div></details>
<details><summary>payloads/register_user.rs</summary><div class="details-content"><div class="code-block-container">
<div class="code-block-filename-container">payloads/register_user.rs</div>
<pre class="diff-highlight language-diff-rust"><code class="diff-highlight language-diff-rust code-line" data-line="19">- #[derive(Debug, Clone, Eq, PartialEq, Serialize, Deserialize)]
+ #[derive(Debug, Clone, Eq, PartialEq, Serialize, Deserialize, Validate)]
pub struct RegisterUser {
+ #[validate(email)]
 pub email: String,
+ #[validate(length(min = 10))]
 pub password: String,
 #[serde(skip_serializing_if = "Option::is_none")]
+ #[validate(length(max = 256))]
 pub display_name: Option&lt;String&gt;,
}

</code></pre>
</div></div></details>

<h1 id="jwt%E3%82%92%E6%A4%9C%E8%A8%BC%E3%81%99%E3%82%8B%E3%83%9F%E3%83%89%E3%83%AB%E3%82%A6%E3%82%A7%E3%82%A2%E3%82%92%E7%94%A8%E6%84%8F%E3%81%99%E3%82%8B" data-line="0" class="code-line">
<a class="header-anchor-link" href="#jwt%E3%82%92%E6%A4%9C%E8%A8%BC%E3%81%99%E3%82%8B%E3%83%9F%E3%83%89%E3%83%AB%E3%82%A6%E3%82%A7%E3%82%A2%E3%82%92%E7%94%A8%E6%84%8F%E3%81%99%E3%82%8B" aria-hidden="true"></a> JWTを検証するミドルウェアを用意する</h1>
今回ユーザーのロールごとの権限制御などをしないので <a href="https://docs.rs/actix-web-httpauth/latest/actix_web_httpauth/" target="_blank" rel="nofollow noopener noreferrer">actix_web_httpauth</a> だけを使う。
Actix-web のミドルウェアを時前で実装するのはかなり大変そう。<a href="https://actix.rs/docs/middleware" target="_blank" rel="nofollow noopener noreferrer">公式のドキュメント</a>もさわりの部分だけ書いてあるという印象。
<a href="https://imfeld.dev/writing/actix-web-middleware" target="_blank" rel="nofollow noopener noreferrer">Demystifying Actix Web Middleware</a> の記事が非常に参考になった。
<code>actix_web_httpauth</code> のサンプルコードではなく、<a href="https://github.com/DDtKey/protect-endpoints/blob/main/actix-web-grants/examples/jwt-httpauth/main.rs" target="_blank" rel="nofollow noopener noreferrer">actix-web-grantsのサンプルコード</a> をベースに <a href="https://docs.rs/actix-web-httpauth/latest/actix_web_httpauth/middleware/struct.HttpAuthentication.html#impl-HttpAuthentication%3CBearerAuth,+F%3E" target="_blank" rel="nofollow noopener noreferrer">HttpAuthentication::bearer</a>) に渡す関数を実装
<details><summary>middlewares/jwt_auth.rs</summary><div class="details-content"><div class="code-block-container">
<div class="code-block-filename-container">middlewares/jwt_auth.rs</div>
<pre class="language-rust"><code class="language-rust code-line" data-line="11">pub async fn validator&lt;DB: 'static&gt;(
 req: ServiceRequest,
 credentials: BearerAuth,
) -&gt; Result&lt;ServiceRequest, (actix_web::error::Error, ServiceRequest)&gt; {

 // get application state
 let Some(state) = req.app_data::&lt;actix_web::web::Data&lt;AppState&lt;DB&gt;&gt;&gt;() else {
 let report = report!(AppError).attach_printable("Cannot get AppData");
 let error = ServerError::from(report);
 let error = actix_web::error::Error::from(error);
 return Err((error, req));
 };

 // decode JWT token
 let token = credentials.token();
 let claims: Result&lt;UserClaims, _&gt; = state.jwt.decode(&amp;Token {
 token: token.to_string(),
 });

 match claims {
 Ok(claims) =&gt; {
 // success. then attach user info
 req.extensions_mut().insert((claims.id, claims.name));
 Ok(req)
 }
 Err(report) =&gt; {
 // not ok.
 let error: ServerError = report.into();
 Err((error.into(), req))
 }
 }
}

</code></pre>
</div></div></details>
<ul data-line="48" class="code-line">
<li data-line="48" class="code-line">JWTトークンを <code>AppState::jwt</code> を用いてデコードする</li>
<li data-line="49" class="code-line">デコードに成功したら、ユーザーIDと名前をリクエストローカルな変数に追加する</li>
<li data-line="50" class="code-line">
<code>actix-web-grants</code> のサンプルでは permission を追加して、ロールごとに許可されるルーティングを変更するが、今回そこまでしない
<ul data-line="51" class="code-line">
<li data-line="51" class="code-line">なので Cargo.toml に <code>actix-web-grants</code> の依存もつけない</li>
</ul>
</li>
</ul>
<code>HttpAuthMiddleware </code> を <code>main.rs</code> で入れたい
<div class="code-block-container"><pre><code class="code-line" data-line="55"> HttpServer::new(move || {
 let auth = HttpAuthentication::bearer(jwt_auth::validator::&lt;Db&gt;);
 App::new()
 .wrap(middleware::Logger::default())
 .configure(auth::auth_route_with(data.clone()))
 .configure(api::api_route_with(data.clone())) // &lt;- ココ!
 .configure(swagger_route)
 })
 .bind(addrs)
 .change_context(AppError)?
 .run()
 .await
 .change_context(AppError)?;

</code></pre></div><code>auth_route</code> にあるユーザー登録、ログインのルーティングには JWTの検証は不要として、<code>api_routes</code> にある書籍に関連するルーティングに <code>auth</code> ミドルウェアを入れたい。
が、<code>configure</code> では <code>wrap</code> する場所がないので付けれない <code>configure</code>をほどいてここに <code>service</code> を生やすこともできるが、今回は <code>api_route_with</code> の引数に <code>auth</code> を追加する
<details><summary>routes/api.rs</summary><div class="details-content"><div class="code-block-container">
<div class="code-block-filename-container">routes/api.rs</div>
<pre class="language-rust"><code class="language-rust code-line" data-line="77">pub fn api_route_with&lt;Db, Req, Next, O&gt;(
 db: web::Data&lt;AppState&lt;Db&gt;&gt;,
 auth: HttpAuthentication&lt;Req, Next&gt;,
) -&gt; impl FnOnce(&amp;mut web::ServiceConfig)
where
 Db: repositories::BooksRepository + 'static,
 Req: FromRequest + 'static,
 Next: Fn(ServiceRequest, Req) -&gt; O + 'static,
 O: Future&lt;Output = Result&lt;ServiceRequest, (error::Error, ServiceRequest)&gt;&gt; + 'static,
{
 move |cfg: &amp;mut web::ServiceConfig| {
 cfg.app_data(db)
 .service(
 web::scope("/api")
 .wrap(auth)
 .configure(books_route::&lt;Db&gt;)
 );
 }
}

</code></pre>
</div></div></details>
<code>HttpAuthentication</code> にはジェネリックパラメータが 2つあって、<code>Next</code> の方は <code>Fn</code>トレイトを実装してなおかつ関数の戻値が <code>impl Future</code> つまり非同期関数なので型制約がけっこう面倒。だが、まあ、これ位なら何とか。。。
<code>auth_route_with</code> 自体の戻値も <code>FnOnce</code> なのでライフタイムのエラーを <code>'static</code>で黙らせた。いずれ困ったら考える。

<h1 id="%E7%99%BB%E9%8C%B2%E3%81%99%E3%82%8B%E6%9B%B8%E7%B1%8D%E3%82%92%E3%80%81%E3%83%AD%E3%82%B0%E3%82%A4%E3%83%B3%E3%81%97%E3%81%A6%E3%81%84%E3%82%8B%E3%83%A6%E3%83%BC%E3%82%B6%E3%83%BC%E3%81%AE%E6%89%80%E8%94%B5%E3%81%A8%E3%81%99%E3%82%8B" data-line="0" class="code-line">
<a class="header-anchor-link" href="#%E7%99%BB%E9%8C%B2%E3%81%99%E3%82%8B%E6%9B%B8%E7%B1%8D%E3%82%92%E3%80%81%E3%83%AD%E3%82%B0%E3%82%A4%E3%83%B3%E3%81%97%E3%81%A6%E3%81%84%E3%82%8B%E3%83%A6%E3%83%BC%E3%82%B6%E3%83%BC%E3%81%AE%E6%89%80%E8%94%B5%E3%81%A8%E3%81%99%E3%82%8B" aria-hidden="true"></a> 登録する書籍を、ログインしているユーザーの所蔵とする</h1>
これまで <code>books</code> テーブルは単純に書籍の山として定義されていたが、ユーザーが増えたので各ユーザーが所蔵する書籍に変更する

<h1 id="%E3%83%86%E3%82%B9%E3%83%88%E3%82%92%E4%BF%AE%E6%AD%A3%E3%83%BB%E8%BF%BD%E5%8A%A0%E3%81%99%E3%82%8B" data-line="0" class="code-line">
<a class="header-anchor-link" href="#%E3%83%86%E3%82%B9%E3%83%88%E3%82%92%E4%BF%AE%E6%AD%A3%E3%83%BB%E8%BF%BD%E5%8A%A0%E3%81%99%E3%82%8B" aria-hidden="true"></a> テストを修正・追加する</h1>
...

<h1 id="swagger-ui-%E3%81%AB%E8%AA%8D%E8%A8%BC%E8%A8%AD%E5%AE%9A%E3%82%92%E8%BF%BD%E5%8A%A0%E3%81%99%E3%82%8B" data-line="0" class="code-line">
<a class="header-anchor-link" href="#swagger-ui-%E3%81%AB%E8%AA%8D%E8%A8%BC%E8%A8%AD%E5%AE%9A%E3%82%92%E8%BF%BD%E5%8A%A0%E3%81%99%E3%82%8B" aria-hidden="true"></a> Swagger UI に認証設定を追加する</h1>
...

method	url	説明
GET	/api/books	書籍の一覧
GET	/api/books/{id}	指定したIDの書籍
POST	/api/books	書籍を新規に作成
PUT	/api/books/{id}	指定したIDの書籍を更新
DELETE	/api/books/{id}	指定したIDの書籍を削除