Коротко — оба варианта имеют смысл, но для разных задач. Ниже — когда что лучше использовать (на примере FastAPI / Pydantic, т. к. термин «Response Model» обычно в этом контексте применяется именно там).
1) Аннотация типа возвращаемого значения (return type)
- Хорошо для: документирования и статической проверки кода, чтобы IDE и типизаторы понимали, что функция возвращает.
- FastAPI: если вы аннотируете функцию Pydantic-моделью (или typing.List[Model]), FastAPI автоматически возьмёт эту аннотацию как модель ответа для OpenAPI и сериализации.
- Рекомендуется, когда функция действительно возвращает именно ту модель, которую вы хотите показать в API.
Пример:
def get_user(...) -> UserOut:
return user # UserOut — Pydantic-модель
2) response_model (параметр в декораторе)
- Хорошо для: явного управления тем, какой формат/модель будет в ответе независимо от того, что реально возвращает функция.
- Полезно если:
- Вы возвращаете ORM-объекты или другие структуры, и хотите, чтобы FastAPI сконвертировал/валидаировал их в нужную Pydantic-модель.
- Нужно скрыть поля (пароли, внутренние поля) или вернуть упрощённую модель, отличную от внутреннего представления.
- Нужен контроль через options (response_model_exclude_none, include/exclude и т.д.).
- Пример:
@app.get("/users/{id}", response_model=UserOut)
def get_user(...):
return db_user # db_user — ORM-объект, FastAPI сконвертирует в UserOut
3) Практические рекомендации
- По умолчанию: ставьте аннотацию return -> Model — это очевидно и удобно.
- Используйте response_model, когда нужно переопределить/отфильтровать ответ, либо когда реальный возвращаемый объект не является Pydantic-моделью.
- Помните о производительности: сериализация/валидация response_model имеет накладные расходы. Если нужны максимальные скорости и вы уверены в ответе, можно избегать лишней валидации.
- Всегда используйте response_model (или явную аннотацию Pydantic) для публичных API — это даёт корректную схему в OpenAPI и безопасность (скрывает чувствительные поля).
Вывод: ставьте аннотацию типа как базовую практику; используйте response_model, когда требуется явное преобразование/фильтрация/переопределение модели ответа.