Return types - Возвращаемые типы

FastAPI использует аннотации типов Python для определения возвращаемых типов конечных точек. Это даёт несколько преимуществ:

• Автоматическая конвертация данных: FastAPI автоматически конвертирует возвращаемое значение Python в JSON, совместимый с указанным типом.
• Валидация данных: FastAPI проверяет, соответствует ли возвращаемое значение заявленному типу. Если нет, возвращается ошибка 500 Internal Server Error, защищая API от непредвиденных ошибок.
• Автоматическая документация: На основе аннотаций типов FastAPI генерирует интерактивную документацию OpenAPI, что упрощает использование и тестирование API.

Разберем, какие типы можно использовать и как FastAPI с ними работает:

from fastapi import FastAPI

app = FastAPI()

@app.get("/json_str/")
def get_json_str() -> str:
    return "json as string"

@app.get("/json_number/")
def get_json_number() -> int | float:
    return -12
    # return -5.7

@app.get("/json_bool/")
def get_json_number() -> bool:
    return True

@app.get("/json_tuple_list_set/")
def get_json_tuple_list_set() -> tuple | list | set:
    # return (1, 2, 3)
    # return ["any", "objects", 4]
    return {11, 11, 22, 22, 33}

@app.get("/json_dict/")
def get_json_dict() -> dict:
    return {'page': 8, 'text': "page with json"}

@app.get("/json_object/")
def get_json_object() -> list[dict]:
    list_pages = [
        {'rout': '/json_str/', 'data': "json as string"},
        {'rout': '/json_number/', 'data': 12},
        {'rout': '/json_number/', 'data': -5.7},
        {'rout': '/json_tuple_list_set/', 'data': (1, 2, 3)},
        {'rout': '/json_tuple_list_set/', 'data': ["any", "objects", 4]},
        {'rout': '/json_tuple_list_set/', 'data': {11, 11, 22, 22, 33}},
        {'rout': '/json_dict/', 'data': {'page': 8, 'text': "page with json"}},
    ]
    return list_pages

Соответствие типов Python и JSON

В FastAPI существует прямое соответствие между некоторыми типами данных Python и JSON:

• str: Строка в Python преобразуется в строку JSON.

  @app.get("/json_str/")
  def get_json_str() -> str:
      return "json as string"

• int, float: Целые и вещественные числа в Python преобразуются в числа JSON. Можно использовать int | float для указания, что возвращаемое значение может быть либо целым, либо вещественным числом.

  @app.get("/json_number/")
  def get_json_number() -> int | float:
      return -12
      # return -5.7

• bool: Булевы значения в Python преобразуются в булевы значения JSON (true/false).

  @app.get("/json_bool/")
  def get_json_number() -> bool:
      return True

• list: Списки в Python преобразуются в массивы JSON.

  @app.get("/json_tuple_list_set/")
  def get_json_tuple_list_set() -> tuple | list | set:
      return ["any", "objects", 4]

• tuple: Кортежи в Python также преобразуются в массивы JSON. Разница между list и tuple с точки зрения JSON-результата отсутствует.

  @app.get("/json_tuple_list_set/")
  def get_json_tuple_list_set() -> tuple | list | set:
      return (1, 2, 3)

• set: Множества в Python также преобразуются в массивы JSON. При этом дубликаты, если они были в множестве, удаляются.

  @app.get("/json_tuple_list_set/")
  def get_json_tuple_list_set() -> tuple | list | set:
      return {11, 11, 22, 22, 33} # Вернет [11, 22, 33] в JSON

• dict: Словари в Python преобразуются в объекты JSON.

  @app.get("/json_dict/")
  def get_json_dict() -> dict:
      return {'page': 8, 'text': "page with json"}

Сложные структуры данных

FastAPI позволяет возвращать сложные структуры данных, комбинируя базовые типы. Например, list[dict] представляет собой список словарей, что в JSON будет представлено как массив объектов.

@app.get("/json_object/")
def get_json_object() -> list[dict]:
    list_pages = [
        # ... (данные)
    ]
    return list_pages

JSON типы vs Python типы: ключевые различия

Хотя JSON и Python имеют схожие типы данных, существуют некоторые ключевые различия, о которых стоит помнить:

Python Type	JSON Type	Особенности
str	String	Строки в Python и JSON в основном идентичны.
int, float	Number	JSON не различает целые числа и числа с плавающей точкой, оба представляются как Number.
bool	Boolean	Булевы значения (True, False) соответствуют true и false в JSON.
list, tuple, set	Array	Все три типа коллекций (список, кортеж и множество) преобразуются в JSON-массивы. Помните об отсутствии порядка во множествах и отсутствии кортежей в JSON.
dict	Object	Словари в Python напрямую соответствуют JSON-объектам. Ключи словаря должны быть строками.
None	null	Объект None в Python преобразуется в null в JSON.

Использование возвращаемых типов в FastAPI — это хорошая практика кодирования, важный инструмент для создания надежных, понятных и хорошо документированных API. Указывая типы возвращаемых значений, вы позволяете FastAPI автоматизировать валидацию данных, сериализацию в JSON и генерацию документации OpenAPI. Это значительно упрощает разработку и поддержку API, а также улучшает взаимодействие с клиентами вашего API. Понимание различий между типами данных Python и JSON поможет вам правильно определять возвращаемые типы и избежать неожиданного поведения при сериализации данных.