ЧАВО

Почему в Falcon нет батареек?

Falcon разработан для приложений, требующих высокой степени настройки или оптимизации производительности. Минималистский дизайн фреймворка позволяет разработчику выбирать лучшие стратегии и пакеты сторонних разработчиков для текущей задачи.

Экосистема Python предлагает ряд отличных пакетов, которые вы можете использовать изнутри своих обработчиков, хуков и компонентов middleware. В качестве отправной точки сообщество поддерживает список дополнений и дополнительных пакетов Falcon.

Как использовать WSGI middleware с Falcon?

Экземпляры falcon.API являются полноценными WSGI-приложениями, поэтому вы можете использовать стандартный шаблон, описанный в PEP-3333. В вашем основном файле «app» вы просто обернёте свой экземпляр api приложением middleware. Например:

import my_restful_service
import some_middleware

app = some_middleware.DoSomethingFancy(my_restful_service.api)

См. также пример WSGI middleware, приведенный в PEP-3333.

Как выполнить аутентификацию запросов?

Хуки и компоненты middleware можно использовать вместе для аутентификации и авторизации запросов. Например, компонент middleware может использоваться для анализа входящих учетных данных и размещения результатов в req.context. Далее, компоненты или хуки ниже по потоку могут использовать эту информацию для авторизации запроса, учитывая роль пользователя и запрашиваемый ресурс.

Почему Falcon не создаёт новый экземпляр Resource для каждого запроса?

Falcon обычно старается минимизировать количество создаваемых объектов. Он делает это по двум причинам: во-первых, для экономии ресурсов на создание объекта, а во-вторых, для уменьшения использования памяти. Поэтому при добавлении маршрута Falcon требует экземпляр вашего класса ресурса, а не тип класса. Этот же экземпляр будет использоваться для обработки всех входящих запросов по этому маршруту.

Falcon потокобезопасен?

Новые объекты Request и Response создаются для каждого входящего HTTP-запроса. Однако один экземпляр каждого класса ресурса, привязанного к маршруту, используется для всех запросов. Следовательно, если вы будете внимательны к тому, как обработчики обращаются к переменным членам класса, чтобы избежать конфликтов, ваше WSGI-приложение должно быть потокобезопасным.

При этом Falcon-сервисы обычно разворачиваются с использованием зелёных потоков (через библиотеку gevent или подобные), которые фактически не работают одновременно, поэтому могут быть некоторые специфические случаи, когда Falcon не потокобезопасен, которые ещё не обнаружены.

Купите на свой страх и риск!

Как реализовать как POST, так и GET операции для одного ресурса?

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

# Resource Collection
POST /resources
GET /resources{?marker, limit}

# Resource Item
GET /resources/{id}
PATCH /resources/{id}
DELETE /resources/{id}

Вы можете реализовать такой API, просто используя два класса Python: один для представления одного ресурса и другой для представления коллекции таких ресурсов. Обычно оба класса размещаются в одном модуле.

Сообщество Falcon проводило эксперименты по маршрутизации как одиночных, так и коллекционных операций к одному классу Python, но оказалось, что это усложняет и делает менее интуитивными определения маршрутов. Тем не менее, мы всегда открыты для новых идей, поэтому сообщите нам, если вы найдёте другой способ.

См. также этот раздел руководства.

Как передать данные из хука в обработчик и между хуками?

Вы можете ввести дополнительные аргументы обработчика (kwargs) из хука, добавив их в словарь params, переданный в хук. Вы также можете добавить пользовательские данные в словарь req.context, в качестве способа передачи контекстной информации.

Falcon устанавливает Content-Length или мне нужно сделать это явно?

Falcon попытается сделать это за вас, в зависимости от значения resp.body, resp.data, или resp.stream_len (которое задано в ответе, в порядке проверки).

Для динамически генерируемого контента вы можете отказаться от stream_len, в этом случае Falcon пропустит заголовок Content-Length, и, надеюсь, ваш WSGI-сервер сделает «правильное дело» (если вы указали ему включить keep-alive).

Я устанавливаю тело ответа, но оно не возвращается. Что происходит?

Falcon пропускает обработку тела ответа, когда, согласно спецификации HTTP, тело возвращать не следует. Если клиент отправляет запрос HEAD, фреймворк всегда возвращает пустое тело. Falcon также вернет пустое тело всякий раз, когда код состояния ответа является одним из следующих:

falcon.HTTP_100
falcon.HTTP_204
falcon.HTTP_416
falcon.HTTP_304

Если у вас есть другой случай, когда тело не возвращается клиенту, это, вероятно, ошибка! Сообщите нам в IRC или на списке рассылки, чтобы мы могли помочь.

Приложение устанавливает cookie, но оно не передаётся обратно в последующих запросах.

По умолчанию Falcon включает атрибут cookie secure. Следовательно, если вы тестируете своё приложение по HTTP (а не HTTPS), клиент не будет отправлять cookie в последующих запросах. См. также документацию по cookie

Почему возникновение ошибки внутри ресурса приводит к аварийному завершению приложения?

В целом, Falcon предполагает, что обработчики ресурсов (например, on_get, on_post и т. д.) в основном будут действовать правильно. Другими словами, Falcon не пытается сильно защитить код обработчика от самого себя.

Этот подход снижает количество (часто) лишних проверок, которые Falcon в противном случае должен был бы выполнять, делая фреймворк более эффективным. С учётом этого, для создания качественного API на основе Falcon необходимо:

1. Обработчики ресурсов устанавливают переменные ответа в разумные значения.
2. Ваш код хорошо протестирован, с высоким покрытием кода.
3. Ошибки прогнозируются, обнаруживаются и обрабатываются надлежащим образом внутри каждого обработчика и с помощью пользовательских обработчиков ошибок.

Почему из req.path удаляются конечные слэши?

Falcon нормализует пути входящих URI для упрощения дальнейшей обработки и повышения предсказуемости логики приложения. В дополнение к удалению конечных слэшей (если таковые имеются), Falcon преобразует пустые пути в «/».

Обратите также внимание, что маршрутизация также нормализована, поэтому добавление маршрута для «/foo/bar» также подразумевает добавление маршрута для «/foo/bar/». Запросы, поступающие для любого из путей, будут направлены на тот же ресурс.

Почему имена полей в шаблонах URI ограничены определёнными символами?

Имена полей ограничены символами ASCII в наборе [a-zA-Z_]. Использование ограниченного набора символов позволяет фреймворку делать упрощающие предположения, которые снижают нагрузку на разбор входящих запросов.

Почему мой параметр запроса отсутствует в объекте req?

Если параметр запроса не имеет значения, Falcon по умолчанию игнорирует этот параметр. Например, передача «foo» или «foo=» приведёт к игнорированию параметра.

Если вы хотите распознать такие параметры, вы должны установить параметр запроса keep_blank_qs_values в значение True. Параметры запроса задаются глобально для каждого экземпляра falcon.API через атрибут req_options. Например:

api.req_options.keep_blank_qs_values = True

Как получить доступ к параметрам POST-формы?

По умолчанию Falcon не потребляет тела запросов. Однако установка auto_parse_form_urlencoded в значение True заставит фреймворк потреблять тело запроса, когда тип контента равен application/x-www-form-urlencoded, сделав параметры формы доступными через params, get_param() и т. д.

api.req_options.auto_parse_form_urlencoded = True

В качестве альтернативы, параметры POST-формы можно читать непосредственно из stream и парсить с помощью falcon.uri.parse_query_string() или urllib.parse.parse_qs().