C# と .NET を勉強するつもりで、自分用の Web アプリを ASP.NET Core MVC で組んだことがあった。 ローカルの macOS で動かす個人用のツールで、SQLite にデータを入れて Razor で画面を返すだけのシンプルなもの。 せっかく作ったので機能を足しながらそのまま使ってたけど、ふだん書く言語が Python に寄ってきたのもあって、いつか書き換えたいとは思っていた。

書き換え先を FastAPI にしたのは、自分がいちばんよく使う Python の比較的新しいフレームワークで、この規模のアプリにちょうどいい軽さだったから。

ここでは ASP.NET Core MVC と FastAPI の対応関係を整理しつつ、書き換えながら気づいたことを残しておく。

ASP.NET Core MVC と FastAPI

まずは今回の主役の 2 つのフレームワークについて簡単に。

ASP.NET Core MVC

Microsoft の Web フレームワーク。C# で書いて、MVC(Model-View-Controller)パターンに沿ってアプリを組み立てる。

.NET のエコシステムは成熟していて、DI(依存性注入)コンテナやミドルウェアパイプラインも標準で組み込まれている。 パッケージは NuGet で管理して、ビルドや実行は dotnet CLI でやる。 HTTP サーバーも Kestrel が入っているので、アプリを単体で起動すればそのままリクエストを受けられる。

型が強くてコンパイル時にエラーを拾ってくれる安心感はある。ただクラスやインターフェースの定義が増えがちで、小さいアプリでもファイル数が膨らみやすい。

FastAPI

Python の Web フレームワーク。2018 年に出た比較的新しいもので、Python の型ヒント(type hints)を活かすのが特徴。

Python の Web フレームワークだと Django や Flask が有名だが、FastAPI の立ち位置はこの 2 つと少し違う。 Django は「全部入り」で、ORM・管理画面・認証などが最初からセットになってる。 Flask は「最小限」で、必要な機能をプラグインで足していくスタイル。 FastAPI は Flask に近い軽さで、型ヒントによる自動バリデーションと API ドキュメントの自動生成(Swagger UI)が標準で付いてくる。

もう 1 つの特徴は非同期(async/await)への対応。 FastAPI は ASGI(Asynchronous Server Gateway Interface)という非同期対応のインターフェース仕様に沿っている。 これまでの Python の Web フレームワーク(Django や Flask)は WSGI(Web Server Gateway Interface)という同期的なインターフェースが主流だった。 ASGI はリクエストを非同期で処理できるので、I/O 待ちが多い場面でのスループットが高い。

ただ ASGI アプリ単体だと HTTP リクエストを受けられないので、Uvicorn のような ASGI サーバーが別で必要になる。 .NET の Kestrel のように「フレームワークにサーバーが内蔵されている」わけじゃないのがここの違い。

FastAPI にした理由

書き換えたいとは思いつつ、.NET のまま使い続けていたのは単に「動いてるから」。ただ macOS で dotnet を使う運用には面倒なところがいくつかあった。

  • .NET ランタイムのバージョン管理(メジャーバージョンが上がるたびに .csproj の TargetFramework を書き換えてパッケージも更新しないといけない)
  • ビルド時間の長さ(自分しか使わないアプリなのに毎回コンパイルが走って重い)
  • NuGet パッケージの依存解決がたまに壊れる

正直、自分しか使わないローカルツールにしては構えが大きいなと思ってた。

書き換え先を Python にしたのは、ふだんいちばんよく書いている言語だから。macOS なら Homebrew で python3 が入るし、SQLite は標準ライブラリに入っている。インタプリタ言語なのでビルドもいらないし、ファイルを書き換えたらすぐ反映される。

Python のフレームワークの中でも FastAPI にしたのは、比較的新しいことと、型ヒントベースのバリデーションが .NET の「型で守る」感覚に近かったから。 Flask も候補にはあった。でも Flask だと型ヒントはあくまでドキュメント的な役割どまり。 FastAPI は型ヒントからバリデーションルールと API ドキュメントが自動で作られるので、書いた型がちゃんと動作に効いてくる。

Django は今回の用途には機能が多すぎた。ORM・管理画面・認証はどれもいらなくて、SQLite を直接叩いて HTML を返すだけのアプリなら FastAPI くらいの粒度がちょうどいい。

部分更新は HTMX に任せる

HTMX は HTML の属性だけでサーバーと非同期に通信するライブラリ。JavaScript をほぼ書かずにページを部分的に更新できる。

昔ながらの Web アプリだと、フォーム送信後にサーバーがページ全体を返してリダイレクト → ページ丸ごと再読み込みという流れが普通だった。 部分更新したければ jQuery の $.ajax() や fetch() で JavaScript を書かないといけない。 React や Vue みたいな SPA フレームワークを入れる手もあるけど、自分用のツールにはオーバースペック。

HTMX はちょうどその間を埋めてくれる感じ。

<!-- 削除ボタン -->
<button hx-post="/items/42/delete"
        hx-target="#item-list"
        hx-swap="innerHTML">
    削除
</button>

<!--
  hx-post   : POST /items/42/delete にリクエストを送る
  hx-target : レスポンス HTML で #item-list の中身を差し替える
  hx-swap   : 差し替え方法(innerHTML = 中身だけ入れ替え)
-->

この例では削除ボタンを押すと HTMX が POST /items/42/delete を裏で送って、サーバーが返した HTML の断片で #item-list の中身を差し替える。ページ全体のリロードは起きない。

サーバー側は「HTML の断片を返すだけ」でよくて、JSON API を設計する必要もない。 テンプレートエンジンで HTML を作る今までのサーバーサイドレンダリングの延長で部分更新ができるので、自分みたいなバックエンド寄りの人間にはありがたかった。

.NET 版ではフォームを送るたびにページ全体をリダイレクトで読み込み直していた。HTMX を入れてからは操作のたびに画面がちらつくこともなくなった。

プロジェクト構成はこう変わった

.NET(ASP.NET Core MVC)のプロジェクトはこんな感じ。Controller・Service・Model・View がフォルダで分かれていて、それぞれが役割ごとのレイヤーになっている。

MyApp/
├── MyApp.sln
├── MyApp/
│   ├── MyApp.csproj
│   ├── Program.cs                 # エントリポイント
│   ├── appsettings.json           # 設定
│   ├── Controllers/
│   │   └── ItemController.cs      # ルーティング + ハンドラ
│   ├── Services/
│   │   └── ItemService.cs         # ビジネスロジック
│   ├── Models/
│   │   ├── Entities/
│   │   │   └── ItemEntity.cs      # テーブルに対応する型
│   │   ├── ViewModels/
│   │   │   └── ItemViewModel.cs   # View に渡すモデル
│   │   └── DTOs/
│   │       └── AddItemRequest.cs  # POST リクエスト
│   ├── DataAccess/
│   │   ├── DbConnectionFactory.cs # DB 接続管理
│   │   └── ItemRepository.cs      # SQL 実行(Dapper)
│   ├── Views/
│   │   ├── Shared/
│   │   │   └── _Layout.cshtml     # 共通レイアウト
│   │   └── Item/
│   │       └── Index.cshtml       # 個別ページ
│   └── wwwroot/                   # 静的ファイル
│       ├── css/
│       ├── js/
│       └── lib/                   # Bootstrap, jQuery 等

Models の中が Entities・ViewModels・DTOs に分かれていて、DataAccess まで独立してるのが .NET の MVC らしいところ。 Entity はデータベースのテーブルに対応するクラス、ViewModel は画面に渡すデータをまとめたクラス、DTO(Data Transfer Object)はフォームの入力値などリクエストデータを受け取るクラス。 Repository は DB へのクエリ実行の担当。それぞれに専用のクラスを作るのが .NET の流儀。

FastAPI 版はこうなった。

my-app/
├── app/
│   ├── main.py            # エントリポイント・ルーター登録
│   ├── config.py           # 設定(環境変数)
│   ├── templating.py       # Jinja2 インスタンス
│   ├── routers/
│   │   └── items.py        # ルーティング + ハンドラ
│   ├── db/
│   │   ├── __init__.py     # sqlite3 接続管理
│   │   └── queries.py      # SQL クエリ関数
│   ├── templates/
│   │   ├── base.html       # 共通レイアウト
│   │   ├── items.html      # 個別ページ
│   │   └── components/     # HTMX 用パーシャル
│   └── static/
│       ├── css/
│       └── js/
├── data/                   # SQLite DB ファイル
├── requirements.txt
└── tests/

フォルダはルーター(= Controller)・DB・テンプレート(= View)で分けてる。.NET 版にあった Service 層・ViewModel・Entity・DTO はまるごとない。

.NET 版は Controller → Service → Repository → Entity / ViewModel と 4 つのレイヤーを通るのが定番だった。 FastAPI 版はルーターが直接 DB の関数を呼んでテンプレートに渡すだけの 2 層構成。 レイヤーが減ったぶん追うコードも減る。 チーム開発やテストのしやすさを考えれば層を分けたほうがいいが、自分専用のツールならこのくらいがちょうどいい。

エントリポイント

アプリの起動地点がどう違うか見てみる。

ASP.NET Core の Program.cs

.NET の Program.cs はビルダーパターンでサービスを登録したりミドルウェアを設定したりして、最後に app.Run() で起動する。

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllersWithViews();

// DB 接続文字列を appsettings.json から取得して DI に登録
var connStr = builder.Configuration.GetConnectionString("Default")
    ?? "Data Source=data/app.db";
builder.Services.AddSingleton(new DatabaseConfig(connStr));

var app = builder.Build();

app.UseStaticFiles();
app.MapControllers();
app.Run();

builder.Services.AddControllersWithViews() で MVC に必要なサービス一式を DI コンテナに登録する。DB の接続文字列も DatabaseConfig として DI に入れておく。 この「ビルダーでサービスを登録 → パイプラインを組む → 起動」という流れが ASP.NET Core の基本のパターン。

app.Run() を呼ぶと内蔵の Kestrel サーバーが HTTP リクエストを受け付け始める。 Web サーバーを別に用意しなくてもアプリが立ち上がるのは便利。でも裏を返すと、アプリのコードとサーバーの起動が一体になってる。

FastAPI の main.py

FastAPI 版の main.py はこう。

from pathlib import Path
from fastapi import FastAPI
from fastapi.staticfiles import StaticFiles
from app.routers import items

BASE_DIR = Path(__file__).resolve().parent

app = FastAPI(title="My App")
app.mount("/static", StaticFiles(directory=BASE_DIR / "static"), name="static")
app.include_router(items.router)

FastAPI() のインスタンスを作って、ルーターを include_router で登録するだけ。.NET の Program.cs に比べるとだいぶ短い。

ここで 1 つ気になるのは「サーバーを起動するコードがない」こと。 FastAPI 側は ASGI アプリを定義するだけで、HTTP サーバーとして起動するのは Uvicorn の仕事。 要は main.py は「アプリの定義」だけを書くファイルで、「起動」は別のコマンド(uvicorn app.main:app)でやる。

.NET では builder.Services.AddControllersWithViews() で MVC の一式を DI コンテナに登録する。 FastAPI にはそういう仕組みがなくて、ルーターのモジュールを import して include_router するだけ。 DI に慣れていると最初は「これだけで動くの?」と思うが、Python ではモジュールの import 自体が実質 DI の代わりになっている。

起動・終了時の処理は lifespan で

.NET の Program.cs で起動時の DB 初期化などを書いてた部分は、FastAPI だと lifespan に書く。 @asynccontextmanager で囲んだジェネレータの yield より前が起動処理、後ろが終了処理になる。

from contextlib import asynccontextmanager
from fastapi import FastAPI

@asynccontextmanager
async def lifespan(app: FastAPI):
    # 起動時の初期化処理(DB マイグレーションなど)
    print("アプリケーション起動")
    yield
    # 終了時のクリーンアップ
    print("アプリケーション終了")

app = FastAPI(title="My App", lifespan=lifespan)

.NET だと Program.cs に上から順に初期化コードを書けば起動時に実行されるし、終了処理は IHostedService や IDisposable で書くことが多い。 FastAPI の lifespan は Python のコンテキストマネージャの仕組みを使っていて、yield の前後で起動と終了を分けるのはいかにも Python っぽい書き方。 最初は若干クセがあるなと思ったけど、起動と終了の処理が 1 つの関数にまとまるので見通しはいい。

Controller → Router

リクエストを受けて処理を振り分ける部分。.NET では Controller、FastAPI では Router と呼ぶ。名前が違うだけでやってることは同じ。

ASP.NET Core の Controller

.NET の Controller はクラスにアクションメソッドを並べる形。[Route] 属性でパス、[HttpPost] で HTTP メソッドを指定する。

public class ItemController : Controller
{
    private readonly IItemService _service;

    public ItemController(IItemService service)
    {
        _service = service;
    }

    [Route("/")]
    public IActionResult Index()
    {
        var model = _service.CreateIndexViewModel();
        return View(model);
    }

    [Route("items/add")]
    [HttpPost]
    public IActionResult AddItem(AddItemRequest request)
    {
        _service.AddItem(request);
        return RedirectToAction("Index");
    }

    [Route("items/delete")]
    [HttpPost]
    public IActionResult DeleteItem(int id)
    {
        _service.DeleteItem(id);
        return RedirectToAction("Index");
    }
}

Controller クラスは Controller を継承して、メソッドごとに [Route("...")] と [HttpPost] などの属性(Attribute)を付けてルーティングを決める。 GET では return View(model) で Razor テンプレートをレンダリングして、POST では RedirectToAction で一覧に戻る。 コンストラクタで IItemService を受け取っているのは DI(依存性注入)のパターン。

FastAPI の Router

FastAPI の Router は関数にデコレータを付ける形。@router.get("/") や @router.post("/items") で同じことを書ける。

from contextlib import closing
from fastapi import APIRouter, Form, Request
from app.db import get_connection, queries
from app.templating import templates

router = APIRouter()

@router.get("/")
async def index(request: Request):
    with closing(get_connection()) as conn:
        rows = queries.load_items(conn)
    return templates.TemplateResponse(request, "items.html", {"items": rows})

@router.post("/items")
async def add_item(request: Request, name: str = Form("")):
    if name.strip():
        with closing(get_connection()) as conn:
            queries.insert_item(conn, name.strip())
            rows = queries.load_items(conn)
    return templates.TemplateResponse(
        request, "components/item_list.html", {"items": rows}
    )

@router.post("/items/{item_id}/delete")
async def delete_item(request: Request, item_id: int):
    with closing(get_connection()) as conn:
        queries.delete_item(conn, item_id)
        rows = queries.load_items(conn)
    return templates.TemplateResponse(
        request, "components/item_list.html", {"items": rows}
    )

.NET の「クラス + 属性」に対して FastAPI は「関数 + デコレータ」。パスと HTTP メソッドの指定の仕方が違うだけで、やっていることは変わらない。

FastAPI 版のほうは HTMX 向けのパーシャルレスポンスを返している。 POST の処理が終わったら更新後のリストの HTML だけを返して、HTMX が画面のその部分だけを差し替える。 .NET 版の「POST → リダイレクト → ページ全体を再読み込み」と違って画面がちらつかない。

POST パラメータの受け取り方

フォームから送られたデータをサーバー側でどう受け取るかは、両者で書き方が結構違う。

.NET は DTO(Data Transfer Object)クラスを定義しておいて、ASP.NET のモデルバインドが自動でマッピングしてくれる。

// POST リクエストを受け取るための DTO クラス
public class AddItemRequest
{
    public string Name { get; set; }
    public int Category { get; set; }
}

// Controller 側ではこう受け取る
[HttpPost]
public IActionResult AddItem(AddItemRequest request)
{
    // ASP.NET が自動的にフォームの値を AddItemRequest にマッピングする
    _service.AddItem(request);
    return View("RedirectIndex");
}

FastAPI は Form(...) で各フィールドを関数の引数として直接受け取る。

# FastAPI 側ではデコレータの引数として受け取る
@router.post("/items")
async def add_item(
    request: Request,
    name: str = Form(""),          # <input name="name"> に対応
    category: int = Form(0),       # <input name="category"> に対応
):
    if name.strip():
        with closing(get_connection()) as conn:
            queries.insert_item(conn, name.strip(), category)
    ...

.NET のやり方は「フィールドが増えても DTO クラスに足すだけ」で管理しやすいが、そのぶんクラスファイルが増える。 FastAPI のほうは関数の引数を見ればフォームの項目がわかるのがいいところ。 ただフィールドが 10 個を超えるような大きいフォームだと引数が長くなるので、そういうときは Pydantic の BaseModel にまとめることもできる。

Service 層はなくても困らなかった

.NET 版にはこんな Service クラスがあった。Controller から呼ばれて、ViewModel の組み立てと Repository の呼び出しを受け持つ。

public class ItemService : IItemService
{
    private readonly IItemRepository _repository;
    private readonly DatabaseConfig _dbConfig;

    public ItemService(IItemRepository repository, DatabaseConfig dbConfig)
    {
        _repository = repository;
        _dbConfig = dbConfig;
    }

    public IndexViewModel CreateIndexViewModel()
    {
        using var db = new SqliteConnection(_dbConfig.ConnectionString);
        var model = new IndexViewModel
        {
            Items = _repository.LoadItems(db)
        };
        return model;
    }

    public void AddItem(AddItemRequest request)
    {
        using var db = new SqliteConnection(_dbConfig.ConnectionString);
        _repository.InsertItem(db, request);
    }

    public void DeleteItem(int id)
    {
        using var db = new SqliteConnection(_dbConfig.ConnectionString);
        _repository.DeleteItem(db, id);
    }
}

Controller → Service → Repository の 3 層構造は .NET の定番のパターン。でも見てのとおり、Service がやってるのは「DB から取ってきて ViewModel に詰める」だけ。 ビジネスロジックが薄いアプリだと Service 層はただの受け渡し役になりがち。

なので FastAPI 版ではこの層を作らなかった。 ルーターの関数の中で直接 queries.load_items(conn) を呼んで、結果を辞書でテンプレートに渡している。 Python は関数ベースなので「わざわざクラスにまとめる必要がない」場面が多い。処理が複雑になったらモジュールを切り出せばいいし、最初から層を作っておく必要はなかった。

DB アクセスは Dapper から sqlite3 へ

Dapper は SQL を自分で書く ORM

Dapper は .NET のマイクロ ORM。Entity Framework のようなフル ORM と違って SQL は自分で書く。 Dapper がやってくれるのは「クエリ結果を C# のクラスに自動でマッピングする」ことと「パラメータのバインド」の 2 つ。

SQL は自分でコントロールしたいが、結果の変換は自動でやってほしい。そういうときにちょうどいい。ちなみに開発元は Stack Overflow で、パフォーマンスの高さでも知られている。

public IEnumerable<ItemEntity> LoadItems(SqliteConnection db)
{
    db.Open();
    var sql = @"SELECT * FROM Items";
    return db.Query<ItemEntity>(sql);
}

public void InsertItem(SqliteConnection db, AddItemRequest request)
{
    db.Open();
    var sql = @"INSERT INTO Items(Name, CreatedAt) VALUES(@Name, @CreatedAt)";
    db.Query(sql, new { Name = request.Name, CreatedAt = DateTime.Now.ToString("d") });
}

public void DeleteItem(SqliteConnection db, int id)
{
    db.Open();
    var sql = @"DELETE FROM Items WHERE Id = @id";
    db.Query(sql, new { id = id });
}

db.Query<ItemEntity>(sql) と書くと、クエリの結果が ItemEntity クラスのプロパティに自動でマッピングされる。 パラメータは匿名オブジェクト(new { Name = request.Name })で渡すと、SQL の中の @Name に対応づけてくれる。

結果を受け取る Entity クラスは別に定義しておく。

// テーブルのカラムに対応するクラス
public class ItemEntity
{
    public int Id { get; set; }
    public string Name { get; set; }
    public string CreatedAt { get; set; }
}

// Dapper がクエリ結果を自動で ItemEntity にマッピングする
// → row.Id, row.Name のようにプロパティでアクセスできる

Python 側は sqlite3 をそのまま使う

Python 版では外部パッケージの ORM は入れずに、標準ライブラリの sqlite3 を直接使った。 Python には SQLAlchemy という有名な ORM もある。でも Dapper と同じく SQL を直接書くスタイルのまま移行したかったので見送った。

import sqlite3
from pathlib import Path

DB_PATH = Path(__file__).resolve().parent.parent.parent / "data" / "app.db"

def get_connection() -> sqlite3.Connection:
    conn = sqlite3.connect(DB_PATH, timeout=5)
    conn.row_factory = sqlite3.Row  # カラム名でアクセス可能にする
    conn.execute("PRAGMA journal_mode=WAL")
    return conn

ポイントは conn.row_factory = sqlite3.Row の行。 これを設定しないとクエリ結果がタプル((1, "りんご"))で返ってくるので、カラム名がわからない。 sqlite3.Row を指定すると辞書みたいにカラム名でアクセスできるようになる。

# sqlite3.Row を使うと、辞書のようにカラム名でアクセスできる
conn.row_factory = sqlite3.Row

row = conn.execute("SELECT Id, Name FROM Items").fetchone()
print(row["Id"])     # => 1
print(row["Name"])   # => "りんご"

# row_factory を設定しないと、タプルで返る
# row = (1, "りんご")  ← カラム名がわからない

クエリ関数を並べてみる

書き味は Dapper 版とかなり近い。

def load_items(conn: sqlite3.Connection) -> list[sqlite3.Row]:
    return conn.execute("SELECT Id, Name, CreatedAt FROM Items").fetchall()

def insert_item(conn: sqlite3.Connection, name: str) -> None:
    conn.execute(
        "INSERT INTO Items (Name, CreatedAt) VALUES (?, ?)",
        (name, datetime.now().isoformat(timespec="seconds")),
    )
    conn.commit()

def delete_item(conn: sqlite3.Connection, item_id: int) -> None:
    conn.execute("DELETE FROM Items WHERE Id = ?", (item_id,))
    conn.commit()

Dapper も sqlite3 も「SQL を自分で書く」スタイルなので、移植はほぼ機械的にできた。違うのは次の 2 点。

  • パラメータのバインドが new { Name = param.Name }(名前付き)から (name,)(位置指定のタプル)に変わる
  • 結果のマッピングが Entity クラスへの自動変換(Dapper)から sqlite3.Row(辞書風アクセス)になる

sqlite3.Row は Entity クラスのように前もってプロパティを定義しなくていい。 そのぶんファイルは減るけど、型安全性は落ちる。row["Naem"] みたいなタイポがあっても実行するまで気づけない。 自分用のツールなら許容範囲。ただチーム開発なら Entity クラスのような型定義はあったほうが安全。

DB 接続管理の違い

.NET 版では接続文字列を DatabaseConfig クラスに持たせて、DI で各 Service に渡している。接続のオープン・クローズは using ステートメントで管理する。

// DI で接続文字列を共有するための設定クラス
public class DatabaseConfig
{
    public string ConnectionString { get; }

    public DatabaseConfig(string connectionString)
    {
        ConnectionString = connectionString;
    }
}

// 使う側では DI で受け取り、using で接続を開閉する
using var db = new SqliteConnection(_dbConfig.ConnectionString);

Python 版は get_connection() 関数と contextlib.closing で同じことをやっている。

C# の using var db = new SqliteConnection(...) と Python の with closing(get_connection()) as conn: は構文が違うだけで意図は同じ。どちらも「スコープを抜けたらリソースを閉じる」を確実にやるための仕組み。

あと Python 版では PRAGMA journal_mode=WAL も設定している。SQLite の WAL(Write-Ahead Logging)モードのことで、複数のプロセスが同時に DB を読み書きするときの競合を和らげてくれる。

Razor のテンプレートを Jinja2 に移す

サーバー側で HTML を作るテンプレートエンジンの話。.NET では Razor、FastAPI では Jinja2 を使う。

Razor(.NET)

Razor は C# の式をテンプレートに埋め込むタイプのエンジン。@ から始まる記法で HTML の中に C# のコードを書ける。 @model で ViewModel の型を宣言して、@foreach で繰り返す。

@model IndexViewModel
@{
    ViewData["Title"] = "アイテム一覧";
}

<h2>アイテム一覧</h2>
<form method="post" action="/items/add">
    <input type="text" name="Name" />
    <button type="submit">追加</button>
</form>

<ul>
@foreach (var item in Model.Items)
{
    <li>
        @item.Name
        <button onclick="deleteItem(@item.Id)">削除</button>
    </li>
}
</ul>

共通レイアウトは _Layout.cshtml に書いて、各ページの中身を @RenderBody() で差し込む。

<!DOCTYPE html>
<html lang="ja">
<head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>@ViewData["Title"] - MyApp</title>
    <link rel="stylesheet" href="~/lib/bootstrap/dist/css/bootstrap.min.css" />
    <script src="~/lib/jquery/dist/jquery.min.js"></script>
</head>
<body>
    <nav>
        <a href="/">ホーム</a>
    </nav>
    <main>
        @RenderBody()
    </main>
</body>
</html>

Jinja2(FastAPI)

Jinja2 は Python のテンプレートエンジン。Flask でも標準で使われていて、Python のテンプレートエンジンだといちばんメジャーなもの。FastAPI でも Jinja2Templates クラス経由で使える。

Razor の @ は Jinja2 だと 2 種類の記法に分かれる。

  • {{ 変数名 }} … 変数の値を出力する(Razor の @item.Name に相当)
  • {% 制御構文 %} … if / for / block などの制御文(Razor の @foreach / @if に相当)
{% extends "base.html" %}
{% block content %}
<h2>アイテム一覧</h2>
<form method="post" action="/items"
      hx-post="/items" hx-target="#item-list">
    <input type="text" name="name" />
    <button type="submit">追加</button>
</form>

<div id="item-list">
    {% include "components/item_list.html" %}
</div>
{% endblock %}

共通レイアウトは base.html に書いて、各ページは {% extends "base.html" %} で継承する。Razor の @RenderBody() にあたるのが {% block content %}。

<!DOCTYPE html>
<html lang="ja">
<head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>My App</title>
    <script src="https://unpkg.com/htmx.org"></script>
    <link rel="stylesheet" href="/static/css/style.css" />
</head>
<body>
    <nav>
        <a href="/">ホーム</a>
    </nav>
    <main>
        {% block content %}{% endblock %}
    </main>
</body>
</html>

HTMX 用のパーシャルテンプレート

HTMX を入れたことで「パーシャルテンプレート」という考え方が加わった。ページ全体ではなく、画面の一部分だけを表す HTML 断片のテンプレートのこと。

<!-- components/item_list.html -->
<ul>
{% for item in items %}
    <li>
        {{ item["Name"] }}
        <button hx-post="/items/{{ item['Id'] }}/delete"
                hx-target="#item-list">
            削除
        </button>
    </li>
{% endfor %}
</ul>

フォームを送るときに hx-post でリクエストを投げると、サーバーはこのパーシャルテンプレートだけをレンダリングして返す。 HTMX は受け取った HTML の断片で hx-target の要素を差し替えるので、ページ全体を読み込み直さなくていい。

Razor にもパーシャル(Partial View)の仕組みはあるが、.NET 版では使っていなかった。 フォーム送信 → ページ全体をリダイレクト → 再読み込みという古典的な流れで作ってたので、操作のたびに画面がちらついていた。 HTMX のパーシャルに変えてからは画面の更新が滑らかになって、使い勝手が明らかによくなった。

テンプレートのインスタンスは 1 つを使い回す

.NET なら return View(model) と書けば裏で Razor エンジンが動く。FastAPI では Jinja2Templates のインスタンスを自分で作らないといけないので、全ルーターで同じものを使い回せるように別モジュールに切り出した。

from pathlib import Path
from fastapi.templating import Jinja2Templates

templates = Jinja2Templates(directory=Path(__file__).resolve().parent / "templates")

各ルーターのファイルで from app.templating import templates と書けば、同じ Jinja2Templates のインスタンスを共有できる。 .NET のように DI コンテナで管理するのではなく、Python のモジュールの仕組み自体がシングルトンの代わりになっている。

設定は環境変数で済ませた

.NET には appsettings.json を中心にした設定管理の仕組みが最初から入っている。appsettings.json(共通)と appsettings.Development.json(開発環境用)のように環境別のファイルを用意しておくと、自動でマージしてくれる。

{
  "ConnectionStrings": {
    "Default": "Data Source=wwwroot/DB/MyDB.db"
  },
  "Logging": {
    "LogLevel": {
      "Default": "Information"
    }
  }
}

コードの中では Configuration.GetConnectionString("Default") のようにキー名を指定して値を取ってくる。 環境(Development / Production)は環境変数の ASPNETCORE_ENVIRONMENT で切り替わって、対応する JSON ファイルが自動で読み込まれる。

FastAPI(Python)側にはこういう組み込みの設定管理の仕組みはない。os.environ.get() で環境変数から読むのがよくあるやり方。

import os
from pathlib import Path

_BASE_DIR = Path(__file__).resolve().parent.parent

DB_PATH = Path(
    os.environ.get("APP_DB_PATH", str(_BASE_DIR / "data" / "app.db"))
).expanduser()

STATIC_DIR = Path(
    os.environ.get("APP_STATIC_DIR", str(_BASE_DIR / "app" / "static"))
).expanduser()

Pydantic の BaseSettings を使えば .env ファイルからの読み込みと型バリデーションも自動化できる。ただ今回は自分用なので、シンプルに os.environ で済ませた。デフォルト値をコードに書いておけば、環境変数を設定しなくてもそのまま動く。

.NET の「環境ごとに JSON ファイルを分ける」仕組みは整理されていて便利。でもローカル専用で環境は 1 つしかないアプリなら、環境変数のほうが素直だと思う。設定ファイルがないので管理するファイルも減る。

起動と常駐のさせ方

開発時の起動

.NET では dotnet run でアプリを起動する。コンパイル → ビルド → Kestrel サーバーの起動までが一気に走る。ファイルを変えたときの自動リロードは dotnet watch run でやる。

FastAPI は ASGI アプリなので、Uvicorn のような ASGI サーバーから起動する。

# 開発時(ファイル変更で自動リロード)
uvicorn app.main:app --reload --port 8000

# 本番(全インターフェースでリッスン)
uvicorn app.main:app --host 0.0.0.0 --port 8000

app.main:app は「app パッケージの main モジュールにある app という変数」という意味。 .NET の dotnet run がプロジェクトファイルからエントリポイントを勝手に見つけてくれるのに比べると明示的だが、「何を起動しているか」がコマンドを見るだけでわかるのはいい。

--reload を付けるとファイルを変えたときに自動でリロードしてくれる。.NET の dotnet watch run と同じ役割だが、Python はコンパイルしなくていいぶん再起動が速い。ファイルを保存した瞬間にはもう反映されてる。

常駐は launchd のまま

macOS で 24 時間動かすのに launchd を使っている。.NET 版も同じく launchd で dotnet MyApp.dll を常駐させてたので、起動コマンドを書き換えるだけで移行できた。

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.myapp.web</string>
    <key>ProgramArguments</key>
    <array>
        <string>/path/to/my-app/.venv/bin/uvicorn</string>
        <string>app.main:app</string>
        <string>--host</string>
        <string>0.0.0.0</string>
        <string>--port</string>
        <string>8000</string>
    </array>
    <key>WorkingDirectory</key>
    <string>/path/to/my-app</string>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
</dict>
</plist>

RunAtLoad で OS の起動時に自動で開始して、KeepAlive でプロセスが落ちたら自動で再起動する。 .NET 版で dotnet /path/to/MyApp.dll だったところを .venv/bin/uvicorn app.main:app に書き換えた。 気をつけたいのは仮想環境(.venv)の中の uvicorn をフルパスで指定すること。launchd はログインシェルの PATH を引き継がないので、フルパスじゃないと見つからない。

テストは TestClient で書く

.NET だと xUnit や NUnit でテストを書くのが定番。テストメソッドに [Fact] や [Theory] の属性を付けて実行する。

FastAPI には TestClient というテスト用のクライアントが用意されている。サーバーを実際に立ち上げなくてもリクエストを投げられるので、テストがシンプルに書ける。

from fastapi.testclient import TestClient
from app.main import app

client = TestClient(app)

def test_index():
    response = client.get("/")
    assert response.status_code == 200

def test_add_item():
    response = client.post("/items", data={"name": "テスト"})
    assert response.status_code == 200

実行は pytest。 .NET みたいに属性を付けなくても、test_ で始まる関数を書くだけで勝手に集めてくれる。 TestClient は中で ASGI アプリを直接呼んでいるので、テスト用にポートを開ける必要もない。

.NET のテストだと WebApplicationFactory でテスト用のサーバーを立てることが多いが、セットアップのコードがそこそこ長くなる。FastAPI の TestClient は 2 行で使い始められるので、テストを書くハードルが低い。

パッケージ管理

本番で必要なパッケージはこの 4 つだけ。

fastapi
uvicorn[standard]
jinja2
python-multipart
  • fastapi … Web フレームワーク本体
  • uvicorn[standard] … ASGI サーバー。[standard] で HTTP パーサーや WebSocket 対応が付く
  • jinja2 … テンプレートエンジン。FastAPI には入っていないので別でインストールが必要
  • python-multipart … フォームデータの解析用。これがないと Form() が使えない

開発用には pytest や mypy などを足している。

# requirements-dev.txt
-r requirements.txt
pytest
httpx
mypy
ruff

.NET 版の .csproj には Microsoft.Data.Sqlite と Dapper の NuGet パッケージが入っていた。 Python 版は SQLite が標準ライブラリにあるので DB 用の外部パッケージはいらない。依存パッケージが少ないほどバージョン更新やセキュリティパッチへの追従が楽になる。

対応関係を表にしておく

.NET (ASP.NET Core MVC) Python (FastAPI)
Controller クラスRouter(APIRouter)
[Route] / [HttpPost] 属性@router.get() / @router.post() デコレータ
Service 層なし(ルーターから直接呼ぶ)
ViewModel クラステンプレートに辞書で渡す
View (.cshtml / Razor)Jinja2 テンプレート (.html)
_Layout.cshtml + @RenderBody()base.html + {% block %}
Dapper + Microsoft.Data.Sqlitesqlite3 標準ライブラリ
Entity クラス(プロパティアクセス)sqlite3.Row(辞書風アクセス)
DTO クラス(モデルバインド)Form() 引数
appsettings.json(環境別)os.environ(環境変数)
dotnet run / Kestrel(内蔵サーバー)uvicorn(外部 ASGI サーバー)
using var db = new SqliteConnection(...)with closing(get_connection())
NuGet (.csproj)pip (requirements.txt)
DI コンテナモジュールの import
AJAX(jQuery / fetch)HTMX(HTML 属性のみ)
launchd(dotnet 起動)launchd(uvicorn 起動)

書き換えてみて

全体でコード量は半分くらいになった。 大きいのは .NET 版にあった Service 層・ViewModel・Entity・DTO クラスの大半がなくなったこと。 書くときは Python のほうが楽。でも型情報が減ったぶん、「あのカラム名なんだっけ」と DB を確認することは増えた気がする。

Dapper → sqlite3 の移行は思ってたよりスムーズだった。 どっちも「SQL を自分で書く」スタイルなので、クエリの部分はほぼコピペで移植できた。 もし .NET 版で Entity Framework のようなフル ORM を使っていたら、テーブル定義やマイグレーションの仕組みごと作り直しになるので、こうはいかなかったと思う。

FastAPI の開発体験でいちばんよかったのは Swagger UI が勝手に生えてくるところ。 /docs を開くだけで API の一覧と試し打ちができる。 .NET でも Swagger は使えるが、NuGet パッケージ(Swashbuckle)を足して設定しないといけない。FastAPI みたいに何もしなくても出てくる手軽さはない。

副次的な効果が大きかったのは HTMX。 .NET 版のときはフォームを送るたびにページ全体がリロードされていたが、HTMX で部分更新にしてから操作感がかなりよくなった。 JavaScript を書かずに HTML の属性だけで済むので、保守の手間が増えないのもいい。

DB ファイルをそのまま引き継げたのも助かった。テーブル定義は変えていないので、.NET 版で溜めたデータがそのまま使える。 フレームワークを移るのにデータ移行がいらなかったのは地味に大きい。SQLite はファイル 1 つで完結するので、こういうときに身軽さが効いてくる。