夫婦で使う家計簿アプリ、あったらいいので作ります。⑤ FastAPIで支出管理APIを作る

家計簿アプリ

前回は、家計簿アプリの全体構成と、FastAPI・SQLite・PWAなどの技術を採用した理由について紹介しました。

今回は、実際のソースコードを使って、FastAPIによるバックエンドの実装方法を紹介します。

今回の家計簿アプリでは、支出の登録や履歴の取得、予算の集計、夫婦間の清算などをFastAPIで処理しています。

ただ、これらの処理をすべて1つのファイルに書いてしまうと、機能を追加するたびにコードが複雑になってしまいます。

そこで、今回のアプリでは、APIの受付処理と実際のデータ処理を分ける構成にしました。

今回は、支出の登録機能を例に、FastAPIの基本的な仕組みと、実際にどのように実装したのかを紹介します。


FastAPIで何ができるのか

まずは、FastAPIについて簡単に説明します。

FastAPIは、PythonでWeb APIを作成するためのフレームワークです。

APIとは、アプリ同士がデータをやり取りするための窓口のようなものです。

例えば、スマートフォンの家計簿画面から2,000円の支出を登録するとします。

このとき、スマートフォンから送信された金額やカテゴリを受け取り、データベースに保存する処理が必要になります。

こうした処理を担当するのがFastAPIです。

HTTPメソッドで処理を分ける

Web APIでは、主に次のようなHTTPメソッドを使用します。

メソッド役割家計簿での例
GETデータを取得支出履歴を表示
POSTデータを登録新しい支出を追加
PUTデータを更新登録した支出を編集
DELETEデータを削除支出を削除

今回のアプリでも、これらを使って支出管理APIを実装しています。

FastAPIでは、Pythonの関数にデコレーターを付けることで、比較的簡単にAPIを作成できます。


Routerを使って機能ごとに分割する

今回のアプリでは、FastAPIのAPIRouterを使って、機能ごとにAPIを分割しています。

主な構成は次のとおりです。

app/
├── main.py
├── routers/
│   ├── transactions.py
│   ├── incomes.py
│   ├── summary.py
│   ├── settings.py
│   └── sync.py
└── ...

それぞれのファイルが、対応する機能のAPIを担当します。

例えば、支出管理はtransactions.py、収入管理はincomes.py、予算や清算の集計はsummary.pyという形です。

main.pyでRouterを登録する

FastAPIアプリの中心となるのがmain.pyです。

ここで、それぞれのRouterを登録します。

実際のコードでは、次のようになっています。

app.include_router(transactions.router)
app.include_router(incomes.router)
app.include_router(summary.router)
app.include_router(settings.router)
app.include_router(sync.router)

※主要なRouterのみ抜粋しています。

これにより、各ファイルで定義したAPIを、1つのFastAPIアプリとして利用できます。

機能ごとにファイルを分けることで、修正する場所が分かりやすくなることが大きなメリットです。


支出登録APIを実装する

ここからは、実際の支出登録処理を見ていきます。

今回のアプリには、支出を直接登録する通常APIと、スマートフォン内に保存したデータを送信する同期APIがあります。

現在のiPhone入力画面では、オフライン対応のため、主に同期APIを利用しています。

ただし、どちらも共通の支出登録処理を使用しているため、まずは仕組みがシンプルな通常登録APIから説明します。

支出管理用のAPIは、routers/transactions.pyに定義しています。

APIの入口を作る

まず、支出登録のAPIは次のようになっています。

@router.post("", status_code=status.HTTP_201_CREATED)
def create_transaction(payload: TransactionInput):
    with get_connection() as db:
        item, _ = insert_transaction(db, payload)
        return item

これは実際のソースコードから抜粋したものです。

処理を順番に見ていきます。

① @router.post()

POSTリクエストを受け付けるAPIを定義しています。

このRouterには/api/transactionsというURLが設定されているため、次のURLで支出を登録できます。

POST /api/transactions

② payload: TransactionInput

スマートフォンなどから送られてきたデータを受け取ります。

ここでは、TransactionInputというデータ形式を使用しています。

③ get_connection()

SQLiteへの接続を取得します。

④ insert_transaction()

受け取った支出データをデータベースに登録します。

そして、登録したデータを返す仕組みです。

このように、APIの受付処理自体は短いコードで実装しています。


Pydanticで入力データをチェックする

Webアプリでは、入力されたデータが必ず正しいとは限りません。

例えば、

  • 金額がマイナスになっている
  • 金額に数値として解釈できない文字列が入力されている
  • 存在しないカテゴリIDが指定されている
  • 日付の形式が間違っている

といった可能性があります。

そこで、今回のアプリではPydanticを使って入力データを検証しています。

Pydanticは、Pythonでデータの型や値をチェックするためのライブラリです。

FastAPIと組み合わせることで、APIに送られてきたデータを自動的に検証できます。

実際の入力データの定義

schemas.pyでは、支出登録用のデータ形式を次のように定義しています。

class TransactionInput(BaseModel):
    transaction_date: date
    category_id: int = Field(gt=0)
    subcategory_id: int = Field(gt=0)
    amount: int = Field(gt=0, le=100_000_000)
    user_id: int = Field(gt=0)
    payment_method_id: int = Field(gt=0)
    memo: Memo = ""

例えば、金額を表すamountには、

amount: int = Field(gt=0, le=100_000_000)

という条件を設定しています。

これは、

  • 整数として扱える値であること
  • 0円より大きいこと
  • 1億円以下であること

を意味しています。

この条件に合わないデータが送信されると、FastAPIは入力エラーを返します。

なお、Pydanticでは"2000"のような数値文字列も整数に変換できるため、必ずしも文字列がすべて拒否されるわけではありません。

また、日付にはdate型を指定しているため、日付として解釈できない値も拒否できます。

データの形式と登録ルールは別々に検証する

ここで重要なのが、Pydanticでの検証と、家計簿としての登録ルールの確認は別の処理だということです。

例えば、category_idに正の整数が指定されていても、そのIDのカテゴリが実際に存在するとは限りません。

そこで、今回のアプリでは次のように役割を分けています。

  • Pydantic:金額や日付、IDなどのデータ形式を検証する
  • Service:カテゴリや支払者が実際に存在するか、詳細項目が正しいカテゴリに属しているかを確認する

このように、データ形式の検証と登録ルールの確認を分けることで、不正なデータが保存されることを防いでいます。


RouterとServiceの役割を分ける

今回の実装でもう一つ意識したのが、APIの受付処理と、実際のデータ処理を分けることです。

先ほどの支出登録APIでは、次の関数を呼び出していました。

insert_transaction(db, payload)

この関数は、transaction_service.pyに定義しています。

支出登録の処理を、Routerとは別のファイルにまとめているのです。

今回の登録処理では、Service側で次のような確認を行っています。

  • 指定したカテゴリが存在するか
  • 詳細項目が正しいカテゴリに属しているか
  • 支払者が存在するか
  • 支払い方法が存在するか

これらの確認が完了したら、SQLiteに支出データを保存します。

つまり、RouterはAPIのリクエストを受け付け、Serviceが登録ルールの確認やデータ保存を担当する仕組みです。

なお、現在のアプリではすべての処理をServiceに分離しているわけではなく、支出の更新や削除など、一部の処理はRouter内で実行しています。

今回は、通常APIと同期APIで共通利用する支出登録処理をServiceにまとめていることがポイントです。

なぜ処理を分けたのか

理由は、同じ登録処理を複数の場所から利用するためです。

今回のアプリには、通常の支出登録APIとは別に、オフラインで入力した支出を同期するAPIもあります。

どちらの場合も、最終的には支出をデータベースに登録する必要があります。

そこで、登録処理を共通のServiceにまとめました。

これなら、支出登録のルールを変更するときも、共通の処理を修正すれば済みます。

同じ処理を何度も書かないことで、修正漏れや処理の違いが発生しにくくなります。


オフライン同期にも同じ処理を利用

今回の家計簿アプリでは、普段の入力時にもオフライン対応を考慮した仕組みを利用しています。

第4回で紹介したように、支出を入力すると、まずiPhone内のIndexedDBに保存します。

その後、サーバーへ接続できるときにFastAPIへ同期します。

この同期処理を担当しているのが、routers/sync.pyです。

実際のAPIは次のようになっています。

@router.post("/transactions")
def sync_transactions(payload: TransactionSyncRequest):
    return _sync_items(
        payload.transactions,
        insert_transaction,
        "expense",
    )

このAPIのURLは、

POST /api/sync/transactions

です。

ここでも、先ほど紹介したinsert_transaction()を使用しています。

つまり、通常のAPIから支出を登録するときも、オフライン同期で登録するときも、共通の処理を利用しています。

二重登録を防ぐ仕組み

同期処理では、同じ支出が二重登録されないようにする必要があります。

例えば、スマートフォンからデータを送信したあと、サーバーでは保存できていても、通信が切れて応答を受け取れない場合があります。

そのまま再送すると、同じ支出が2回登録される可能性があります。

そこで、今回のアプリでは、支出ごとにclient_idという一意の識別IDを付けています。

サーバー側では、このIDを使って、すでに登録済みの支出かどうかを確認します。

登録済みであれば、新しく保存せず、同期結果としてalready_existsを返します。

さらに、SQLite側でも重複登録を防ぐために、次のような一意インデックスを設定しています。

CREATE UNIQUE INDEX IF NOT EXISTS idx_transactions_client_id
ON transactions(client_id)
WHERE client_id IS NOT NULL

これは、同じclient_idを持つ支出を、データベースに複数保存できないようにする設定です。

つまり、

  • Service側:登録済みのIDを確認して、重複登録を避ける
  • SQLite側:同じIDのデータが重複して保存されることを制限する

という2段階の仕組みになっています。

ただし、これは同じIDで再送されたデータの重複を防ぐもので、別々のIDで登録した同じ内容の支出まですべて判定するものではありません。

こうした仕組みによって、通信が不安定な場合でも支出データを安全に同期しやすくしています。

詳しい同期処理については、第7回のPWA・オフライン対応の記事で紹介します。


FastAPIのAPIドキュメントを使う

FastAPIの便利な機能の一つが、APIドキュメントの自動生成です。

今回のアプリでは、次のURLから確認できます。

/api/docs

この画面では、作成したAPIの一覧や、必要な入力データ、返されるデータの形式などを確認できます。

また、APIに実際のデータを送信して動作確認することもできます。

例えば、支出登録APIにテストデータを送れば、データが正常に登録されるかを確認できます。

ただし、登録APIを実行すると実際のデータベースが変更されるため、動作確認にはテスト用の環境を使う方が安全です。

今回のようにAPIが増えていくアプリでは、こうした確認機能があると開発を進めやすくなります。


まとめ

今回は、FastAPIを使った支出管理APIの実装方法について紹介しました。

今回のアプリで意識したのは、次の3つです。

  • Routerを使って機能ごとにAPIを分割する
  • Pydanticを使って入力データを検証する
  • Serviceに処理をまとめ、複数のAPIから共通利用する

FastAPIを使えば、比較的少ないコードでWeb APIを作ることができます。

ただし、機能が増えていくアプリでは、単にAPIが動くだけでなく、あとから機能を追加したり修正したりしやすい構成にすることも大切です。

今回の家計簿でも、支出管理から始めて、収入管理や清算、NISAなどの機能を少しずつ追加してきました。

役割ごとに処理を分けたことで、こうした機能追加も行いやすくなっています。

次の記事では、今回のFastAPIと組み合わせて使用しているSQLiteについて、データベースの設計と、夫婦独自の清算処理をどのように実装したのかを紹介します。


関連記事

コメント

タイトルとURLをコピーしました