Как правильно — Response Model vs Function Return Type?

Question

[Andrey]

Приветствую,

Какой способ правильнее использовать ?

Вариант №1

@app.get("/portal1", response_model=MyModel)
async def get_portal1() -> Any:
    result = {"name1": "name", "age": 10}
    return result

или

Вариант №2

@app.get("/portal2")
async def get_portal2() -> MyModel:
    result = {"name1": "name", "age": 10}
    return MyModel(**result)

Документация пестрит примерами с response_model
ИИ говорит что return type правильнее

Из того что заметил - Вариант №1 с response_model выдает более читаемую информацию по ошибке в случае возникновения таковой

...
fastapi.exceptions.ResponseValidationError: 1 validation error:
  {'type': 'missing', 'loc': ('response', 'name'), 'msg': 'Field required', 'input': {'name1': 'name', 'age': 10}}
  File ".../main.py", line 13, in get_portal1
    GET /portal1

Для Варианта №2 не сразу и понятно где искать

...
pydantic_core._pydantic_core.ValidationError: 1 validation error for MyModel
name
  Field required [type=missing, input_value={'name1': 'name', 'age': 10}, input_type=dict]
    For further information visit https://errors.pydantic.dev/2.13/v/missing

Comments

[Алексей Уколов]

В документации превалирует один вариант, он же на практике вам кажется более удобным. Почему тогда вообще вопрос у вас возник?

[Andrey]

Алексей Уколов,
Видел примеры

def make_data() -> MyModel2:
    result = {"name": "name", "age": 10, "city": "city"}
    return MyModel2(**result)


@app.get("/portal1", response_model=MyModel)
async def get_portal1() -> Any:
    return make_data() # ничего не покажет 


@app.get("/portal2")
async def get_portal2() -> MyModel:
    return make_data() # статический анализатор покажет не соответствие типов

Answer 1

[Пума Тайланд]

response_model и return type частично пересекаются — в современных версиях FastAPI (0.89+) оба влияют на рантайм.

Return type annotation FastAPI использует для OpenAPI-схемы, IDE и (важно) для сериализации/фильтрации ответа. response_model имеет приоритет если оба указаны.

Вариант 1 нужен когда реально возвращаешь что-то другое: ORM-объект с лишними полями, голый dict. Вариант 2 подходит когда честно возвращаешь именно MyModel. Кста в доке FastAPI по SQL прямо написано: "используем response_model вместо return type потому что реально возвращаем не HeroPublic".

p.s. ИИ говорит "return type правильнее", для простых случаев да, но response_model для ORM/dict незаменим.

Comments

[Andrey]

Однако не все так однозначно.
Нашел вот это где сам Себастьян дает разъяснения на этот счет
https://github.com/fastapi/fastapi/discussions/8247

Основной его посыл был таков

Also, the idea/benefit of type annotations is to help you use them in the rest of your code. To detect errors, have completion, etc. But a path operation function is never called by yourself. It's called by FastAPI. So, there's no real benefit in adding a return annotation to the functions. Even though at first it seems the more intuitive place to declare that.

Ну и собственно чтобы успокоить статические анализаторы и их любителей предлагает простое решение Any

@app.get("/item/{item_id}", response_model=Item)
def read_item(item_id: str) -> Any:
    return fake_db.get(item_id)

Для всех остальных остается вариант

@app.get("/item/{item_id}", response_model=Item)
def read_item(item_id: str) -> Item:
    return Item(**fake_db.get(item_id))

или проще начиная с FastAPI 0.89.0
https://github.com/fastapi/fastapi/pull/1436

@app.get("/item/{item_id}")
def read_item(item_id: str) -> Item:
    return Item(**fake_db.get(item_id))

[Пума Тайланд]

хорошая ссылка — `-> Any` + `response_model` это и есть канонический вариант.