🚀

【完全理解】FastAPIはPythonの型ヒントをどう活用している？

に公開
Python
FastAPI
型ヒント
tech

☁️ はじめに

FastAPIの特徴のひとつは、
「Pythonの型ヒントを最大限に活用している」 という点です。

型ヒントは、もともとコードの読みやすさや補完を助ける“注釈”のようなものですが、
FastAPIではそれをアプリケーションの動作・設計そのものに利用しています。

この記事では、

  • 型ヒントとは何か
  • FastAPIがどう活かしているか
  • そして型チェックが自動で行われる仕組み

を、初学者でも理解できるように解説します。
 
では、本題に入ります！

💡そもそも「型ヒント」とは？

Pythonは 「動的型付け言語」 です。
つまり、変数や関数の型を明示しなくても動くのが特徴です。

def add(a, b):
    return a + b

print(add(1, 2))     # → 3  
print(add("A", "B")) # → "AB"

この柔軟さの一方で、「この関数はどんな型の値を扱うか？」が曖昧になりがちです。

ここで登場するのが、 「型ヒント」。

型ヒントとは、変数や関数がどんな型（str, int など）を扱うのかを明示するための仕組みです。

def add(a: int, b: int) -> int:
    return a + b

このように書くと、

  • a と b は 整数型（int）
  • 戻り値 も 整数型（int）

ということを示しています。

注意点として、型ヒントはあくまで「ヒント」なので、実行時に型チェックはされません。
型チェックは、静的解析ツールやIDEで行うことができます。

🧩 よく使う型ヒント例

ここで、型ヒント例をいくつか紹介しておきます。

・整数型

# 引数: 整数型
# 戻り値: 文字列型

def add(num1: int, num2: int) -> str:
    return str(num1 + num2)

・文字列型

# 引数: 文字列型
# 戻り値: 文字列型

def greet(name: str) -> str:
    return f"おはよう！{name}!"

・浮動小数点型

# 引数: 浮動小数点型
# 戻り値: 浮動小数点型

def divide(dividend: float, divisor: float) -> float:
    return dividend / divisor

・リスト

# 引数: リスト「文字列型」
# 戻り値: なし

def process_items(items: list[str]) -> None:
    for item in items:
        print(item)

・辞書

# 引数: リスト「文字列型」
# 戻り値: 辞書「文字列型、整数型」

def count_characters(word_list: list[str]) -> dict[str, int]:
    # 変数に型ヒント
    count_map: dict[str, int] = {}
    for word in word_list:
        # キー: 文字列
        # 値: 文字列に対応する文字数
        count_map[word] = len(word)
    return count_map

 

⚙️ FastAPIは型ヒントをどう有効活用している？

本題ですね。

FastAPIでは、この「型ヒント」をAPIのリクエスト・レスポンスの定義に活用しています。
つまり、型ヒントがそのままAPIの仕様書やバリデーションのルールになるのです。

from fastapi import FastAPI

app = FastAPI()

@app.get("/hello")
def greet(name: str, age: int):
    return {"message": f"Hello {name}, you are {age} years old!"}

ここで name: str と age: int と書くだけで、FastAPIは以下を自動的に行います。

  1. リクエストの型チェックを自動化
  2. OpenAPI仕様書を自動生成
  3. Swagger UIを自動で構築

🔍 リクエストの型チェックが自動化されるとは？

たとえば、上記APIに次のようなリクエストを送るとします。

✅ 正しい例
GET /hello?name=Alice&age=20

→ これはOK。{"message": "Hello Alice, you are 20 years old!"} が返ります。

❌ 間違った例
GET /hello?name=Alice&age=twenty

この場合、age に文字列 "twenty" が送られています。
FastAPIは内部で型ヒントをもとに、
「age は int 型であるべき」と判断し、リクエストを検証します。

つまり、型ヒントを書く＝FastAPIがバリデーションを自動でしてくれる ということです！

📘 OpenAPIとSwagger UIについて

FastAPIは型ヒントをもとにAPIドキュメントを自動生成します。
ただしこの仕組み（OpenAPIとSwagger UI）については、
別の記事で詳しく解説します。

✅まとめ

FastAPIでの、型ヒントは""ただの注釈""ではなく、APIのルールそのもの。
FastAPIは、型ヒントを最大限に活用して、コードの信頼性と可読性を向上させています。

  • 型ヒントとは： 変数や関数の型を明示するためのPythonの標準の仕組み。（FastAPIの独自の機能ではない）
  • FastAPIがどう活かしているか： 型ヒントをもとにAPIの動作・検証・ドキュメント生成を自動化
  • 型チェックの自動化とは： リクエストを受け取った時点で、型に沿ってFastAPIが自動でバリデーションする

Discussion