メインコンテンツまでスキップ

エンドポイント

エンドポイントはlihilで最も原子的なASGIコンポーネントで、クライアントがRouteによって公開されたリソースとやり取りする方法を定義します。

パラメータ解析​

from lihil import Route
from ididi import NodeConfig
from typing import Annotated, NewType
from sqlalchemy.ext.asyncio import AsyncConnection, AsyncEngine


async def get_conn(engine: AsyncEngine) -> AsyncConnection:
    async with engine.begin() as conn:
        yield conn

UserID = NewType("UserID", str)

def user_id_factory() -> UserID:
    return UserID(str(uuid4()))

user_route = Route("/users", deps=[get_conn, (user_id_factory, NodeConfig(reuse=False))])

@user_route.post
async def create_user(
    user: UserData, user_id: UserID, conn: AsyncConnection
) -> Annotated[UserDB, stauts.Created]:

    sql = user_sql(user=user, id_=user_id)
    await conn.execute(sql)
    return UserDB.from_user(user, id=user_id)

ここで、

  1. user_idはuser_id_factoryによって作成され、文字列形式のuuidを返します。
  2. connはget_connによって作成され、AsyncConnectionのインスタンスを返し、接続はリクエスト後にエンジンに返されます。
  3. UserDBはJSON シリアライズされ、コンテンツタイプがapplication/json、ステータスコードが201のレスポンスを返します。

パラメータを明示的に宣言​

Paramでパラメータを明示的に宣言すると、Lihilにそれ以上の分析なしにそのまま扱うように指示します。

例：

async def login(cred: Annotated[str, Param("header", alias="User-Credentials")], x_access_token: Annotated[str, Param("header")]) : ...

  • ここでパラメータcredはUser-Credentialsキーのヘッダーを期待します。

  • キーが提供されない場合、パラメータ名のkebab-caseが使用されます。例えば、ここでx_access_tokenはx-access-tokenキーのヘッダーを期待します。

データ検証​

lihilはmsgspecを使用してすぐに使えるデータ検証機能を提供します。

制約​

typing.AnnotatedとParamを組み合わせてパラメータに制約を設けることができます：

from lihil import Param
all_users = Route("/users")

@all_users.get
async def get_users(numers: Annotated[int, Param(gt=0)]):
    ...

ここでget_userは0より大きい値の整数であるnumersクエリパラメータを期待します。

戻り値マーク​

エンドポイントのステータスコードやコンテンツタイプを変更したい場合、1つまたは複数の戻り値マークの組み合わせを使用できます。例えば、ステータスコードを変更するには：

from lihil import Annotated, status

async def create_user(user: UserData, engine: Engine) -> Annotated[UserDB, status.Created]:
    ...

現在create_userはデフォルトの200ではなく、ステータスコード201を返します。

使用したい戻り値マークがいくつかあります：

戻り値マーク目的型引数注記例
Json[T]application/jsonコンテンツタイプのレスポンスT: レスポンス本体型指定されない場合のデフォルト戻り値型Json[list[int]]
Stream[T]text/event-streamコンテンツタイプのサーバー送信イベントT: イベントデータ型イベントストリーミング用Stream[str]
Texttext/plainコンテンツタイプのプレーンテキストレスポンスなしシンプルテキストレスポンス用Text
HTMLtext/htmlコンテンツタイプのHTMLレスポンスなしHTMLコンテンツ用HTML
Empty空のレスポンス（本体なし）なし戻すコンテンツがないことを示すEmpty