REST-слой (часть1)
Git tag: Step12
Наступил завершающий этап нашего приключения в поисках чистой архитектуры. Мы создали модели предметной области, сериализаторы, сценарии и хранилище. Но пока отсутствует интерфейс, который склеивает все вместе: получает параметры вызова от пользователя, инициализирует сценарий с хранилищем, выполняет сценарий, который получает модели предметной области из хранилища, и преобразует их в стандартный формат. Этот слой может быть представлен с помощью множества интерфейсов и технологий. Например, с помощью интерфейса командной строки (CLI): получать параметры с помощью ключей командной строки и возвращать результат в виде текста на консоли. Но та же базовая система может быть использована и для web-страницы, которая получает параметры вызова из набора виджетов, выполняет описанные выше шаги, и разбирает возвращенные данные в формате JSON для отображения результата на той же странице.
Вне зависимости от выбранной технологии, для взаимодействия с пользователем, сбора входных данных и предоставления выходных результатов, нам необходимо взаимодействовать с недавно созданной чистой архитектурой. Поэтому сейчас мы создадим слой для вынесения наружу API для работы с HTTP. Реализовано это будет при помощи сервера, который предоставляет набор HTTP-адресов (конечных точек API), при обращении к которым возвращаются некоторые данные. Такой слой обычно называют REST-слой, потому что, как правило, семантика адресов схожа с рекомендациями REST.
Flask — это легкий веб-сервер с модульной структурой, которая обеспечивает только необходимые пользователю части. В частности, мы не будем использовать какую-либо базу данных/ORM, так как у нас уже имеется собственный реализованный слой хранилища.
Замечу, что обычно этот слой вместе со слоем хранилища реализуется в виде отдельного пакета, но в рамках этого урока я разместил их вместе.
Обновим файл зависимостей. Файл prod.txt должен содержать модуль Flask
Flask
Файл dev.txt содержит расширение Flask-Script
-r test.txt
pip
wheel
flake8
Sphinx
Flask-Script
И в файл test.txt добавим расширение pytest для работы с Flask (подробнее об этом позже)
-r prod.txt
pytest
tox
coverage
pytest-cov
pytest-flask
После этих изменений обязательно снова запустим pip install -r requirenments/dev.txt, чтобы установить новые пакеты в виртуальную среду.
Настройка Flask-приложения проста, но включает много особенностей. Так как это не учебник по Flask, я бегло пройдусь по этим шагам. Тем не менее, я буду предоставлять ссылки на документацию по Flask для каждой фичи.
Обычно я определяю отдельные конфигурации для моей тестовой, девелоп и продакшн среды. Так как приложение Flask можно настроить с помощью обычного Python-объекта(документация), я создаю файл rentomatic/settings.py для размещения этих объектов
import os
class Config(object):
"""Base configuration."""
APP_DIR = os.path.abspath(os.path.dirname(__file__)) # This directory
PROJECT_ROOT = os.path.abspath(os.path.join(APP_DIR, os.pardir))
class ProdConfig(Config):
"""Production configuration."""
ENV = 'prod'
DEBUG = False
class DevConfig(Config):
"""Development configuration."""
ENV = 'dev'
DEBUG = True
class TestConfig(Config):
"" "Тестовая конфигурация". ""
ENV = 'test'
TESTING = True
DEBUG = True
Чтобы узнать больше о параметрах конфигурации Flask, смотрите эту страницу. Теперь нам нужна функция, которая инициализирует приложение Flask (документация), настраивает его и регистрирует чертежи (документация). В файле rentomatic/app.py содержится следующий код:
from flask import Flask
from rentomatic.rest import storageroom
from rentomatic.settings import DevConfig
def create_app(config_object=DevConfig):
app = Flask(__name__)
app.config.from_object(config_object)
app.register_blueprint(storageroom.blueprint)
return app
Конечные точки приложения должны возвращать Flask-объект Response с актуальными результатами и HTTP-статусом. Содержанием ответа, в данном случае, является JSON -сериализация ответа сценария.
Начнём писать тесты шаг за шагом, что бы вы смогли хорошо понять, что будет происходить в конечной точке REST. Базовая структура теста выглядит следующим образом
[SOME PREPARATION]
[CALL THE API ENDPOINT]
[CHECK RESPONSE DATA]
[CHECK RESPONDSE STATUS CODE]
[CHECK RESPONSE MIMETYPE]
Поэтому, наш первый тест — tests/rest/test_get_storagerooms_list.py состоит из следующих частей
@mock.patch('rentomatic.use_cases.storageroom_use_cases.StorageRoomListUseCase')
def test_get(mock_use_case, client):
mock_use_case().execute.return_value = res.ResponseSuccess (storagerooms)
Поскольку здесь мы не тестируем сам сценарий, мы можем его замокать. Мы заставляем сценарий возвращать экземпляр ResponseSuccess, содержащий список моделей предметной области (которые мы еще не определили).
def test_get(client, monkeypatch):
def monkey_execute(self, rqst):
return res.ResponseSuccess(storagerooms)
monkeypatch.setattr(StorageRoomListUseCase, 'execute', monkey_execute)
Если кто-то знает причину, почему оригинальный код не срабатывает, сообщите, пожалуйста.
http_response = client.get('/storagerooms')
Это текущий вызов API. Мы выставляем конечную точку по адресу /storagerooms.Обратите внимание на использование фикстуры client, предоставленной pytest-Flask.
assert json.loads(http_response.data.decode('UTF-8')) == [storageroom1_dict]
assert http_response.status_code == 200
assert http_response.mimetype == 'application/json'
Вот эти упомянутые выше три проверки. Вторая и третья довольно просты, в то время как первая нуждается в объяснений. Мы хотим сравнить http_response.data с [storageroom1_dict], который представляет собой список Python-словарей, содержащих данные объекта storageroom1_domain_model. Flask-объекты Response содержат двоичное представление данных, поэтому мы сначала декодируeм байты, используя UTF-8, а затем преобразуем их в Python-объект. Гораздо удобнее сравнивать Python-объекты, так как у pytest могут возникать проблемы со словарями, в силу отсутствия у них порядка ключей. Но если сравнивать строки, то подобных сложностей не будет.
Окончательный тестовый файл с тестом модели предметной области и его словарь:
import json
from unittest import mock
from rentomatic.domain.storageroom import StorageRoom
from rentomatic.shared import response_object as res
storageroom1_dict = {
'code': '3251a5bd-86be-428d-8ae9-6e51a8048c33',
'size': 200,
'price': 10,
'longitude': -0.09998975,
'latitude': 51.75436293
}
storageroom1_domain_model = StorageRoom.from_dict(storageroom1_dict)
storagerooms = [storageroom1_domain_model]
@mock.patch('rentomatic.use_cases.storageroom_use_cases.StorageRoomListUseCase')
def test_get(mock_use_case, client):
mock_use_case().execute.return_value = res.ResponseSuccess(storagerooms)
http_response = client.get('/storagerooms')
assert json.loads(http_response.data.decode('UTF-8')) == [storageroom1_dict]
assert http_response.status_code == 200
assert http_response.mimetype == 'application/json'
Пришло время написать конечную точку, где мы, наконец, увидим работу всех частей архитектуры.
Минимальную конечную точку Flask можно поместить в rentomatic/rest/storageroom.py
blueprint = Blueprint('storageroom', __name__)
@blueprint.route('/storagerooms', methods=['GET'])
def storageroom():
[LOGIC]
return Response([JSON DATA],
mimetype='application/json',
status=[STATUS])
Первое, что мы создаём, это StorageRoomListRequestObject. На данный момент можно игнорировать необязательные параметры строки запроса и использовать пустой словарь
def storageroom():
request_object = ro.StorageRoomListRequestObject. from_dict ({})
Как видите, я создаю объект из пустого словаря, так что параметры строки запроса не учитываются. Второе, что нужно сделать, это инициализировать хранилище
repo = mr.MemRepo ()
Третьим идёт инициализация сценария конечной точкой
use_case = uc.StorageRoomListUseCase(repo)
И, наконец, мы выполняем сценарий, передавая объект запроса
response = use_case.execute(request_object)
Но этот ответ пока ещё не HTTP-ответ. Мы должны явно построить его. HTTP-ответ будет содержать JSON представление атрибута response.value.
return Response(json.dumps(response.value, cls=ser.StorageRoomEncoder),
mimetype='application/json',
status=200)
Обратите внимание, что эта функция еще не завершена, так как она всегда возвращает успешный ответ (код 200). Но этого достаточно для прохождения написанных тестов. Весь файл выглядит так:
import json
from flask import Blueprint, Response
from rentomatic.use_cases import request_objects as req
from rentomatic.repository import memrepo as mr
from rentomatic.use_cases import storageroom_use_cases as uc
from rentomatic.serializers import storageroom_serializer as ser
blueprint = Blueprint('storageroom', __name__)
@blueprint.route('/storagerooms', methods=['GET'])
def storageroom():
request_object = req.StorageRoomListRequestObject.from_dict({})
repo = mr.MemRepo()
use_case = uc.StorageRoomListUseCase(repo)
response = use_case.execute(request_object)
return Response(json.dumps(response.value, cls=ser.StorageRoomEncoder),
mimetype='application/json',
status=200)
Этот код демонстрирует работу чистой архитектуры целиком. Правда, написанная функция ещё не закончена, поскольку она не учитывает параметры строковых запросов и случаи с ошибками.
Сервер в действии
Git tag: Step13
Перед тем, как дописать недостающие части конечной точки, давайте посмотрим на сервер в работе и увидим наш проект в действии.
Для того чтобы при обращении к конечной точки увидеть результаты, мы должны заполнить хранилище тестовыми данными. Очевидно, что сделать нам это приходится из-за непостоянности хранилища, которое мы используем. Реальное хранилище будет оборачивать постоянный источник данных, и эти тестовые данные уже будут не нужны. Определяем их для инициализации хранилища:
storageroom1 = {
'code': 'f853578c-fc0f-4e65-81b8-566c5dffa35a',
'size': 215,
'price': 39,
'longitude': '-0.09998975',
'latitude': '51.75436293',
}
storageroom2 = {
'code': 'fe2c3195-aeff-487a-a08f-e0bdc0ec6e9a',
'size': 405,
'price': 66,
'longitude': '0.18228006',
'latitude': '51.74640997',
}
storageroom3 = {
'code': '913694c6-435a-4366-ba0d-da5334a611b2',
'size': 56,
'price': 60,
'longitude': '0.27891577',
'latitude': '51.45994069',
}
И передаём их в наше хранилище
repo = mr.MemRepo ([storageroom1, storageroom2, storageroom3])
Теперь мы можем запустить Flask через файл manage.py и проверить опубликованные URL-адреса:
$ python manage.py urls
Rule Endpoint
------------------------------------------------
/static/<path:filename> static
/storagerooms storageroom.storageroom
И запустить сервер разработки
$ python manage.py server
Если вы откроете браузер и перейдёте по адресу http://127.0.0.1:5000/storagerooms, вы увидите результат API вызова. Рекомендую установить расширение форматирования для браузера, чтобы ответ был удобочитаемым. Если вы используете Chrome, попробуйте JSON Formatter.
REST-слой (часть2)
Git tag: Step14
Давайте рассмотрим два нереализованных случая в конечной точке. Сначала я введу тест, проверяющий корректность обработки параметров строки запроса конечной точкой
@mock.patch('rentomatic.use_cases.storageroom_use_cases.StorageRoomListUseCase')
def test_get_failed_response(mock_use_case, client):
mock_use_case().execute.return_value = res.ResponseFailure.build_system_error('test message')
http_response = client.get('/storagerooms')
assert json.loads(http_response.data.decode('UTF-8')) == {'type': 'SYSTEM_ERROR',
'message': 'test message'}
assert http_response.status_code == 500
assert http_response.mimetype == 'application/json'
Теперь мы проверяем, что сценарий возвращает ответ об ошибке, а так же смотрим, что HTTP-ответ содержит код ошибки. Для прохождения теста мы должны соотнести коды ответов предметной области с кодами HTTP-ответов
from rentomatic.shared import response_object as res
STATUS_CODES = {
res.ResponseSuccess.SUCCESS: 200,
res.ResponseFailure.RESOURCE_ERROR: 404,
res.ResponseFailure.PARAMETERS_ERROR: 400,
res.ResponseFailure.SYSTEM_ERROR: 500
}
Затем нам нужно создать Flask-ответ с корректным кодом
return Response(json.dumps(response.value, cls=ser.StorageRoomEncoder),
mimetype='application/json',
status=STATUS_CODES[response.type])
Второй и последний тест немного сложнее. Как и прежде, мы замокаем сценарий, но на этот раз мы также запатчим и StorageRoomListRequestObject. Нам нужно знать, что объект запроса инициализируется верными параметрами из командной строки. Так что, двигаемся шаг за шагом:
@mock.patch('rentomatic.use_cases.storageroom_use_cases.StorageRoomListUseCase')
def test_request_object_initialisation_and_use_with_filters(mock_use_case, client):
mock_use_case().execute.return_value = res.ResponseSuccess([])
Здесь, как и ранее, патч класса сценария, гарантирующий возврат прецедентом экземпляр объекта ResponseSuccess.
internal_request_object = mock.Mock()
Объект запроса будет создан внутри StorageRoomListRequestObject.from_dict, и мы хотим, чтобы функция возвращала инициализированный ранее здесь мок-объект.
request_object_class = 'rentomatic.use_cases.request_objects.StorageRoomListRequestObject'
with mock.patch(request_object_class) as mock_request_object:
mock_request_object.from_dict.return_value = internal_request_object
client.get('/storagerooms?filter_param1=value1&filter_param2=value2')
Мы патчем StorageRoomListRequestObject и назначаем заранее известный результат на метод from_dict(). Затем мы обращаемся к конечной точке с некоторыми параметрами строки запроса. Происходит следующее: метод from_dict() запроса вызывается с параметрами фильтра, и метод execute() экземпляра сценария вызывается с internal_request_object.
mock_request_object.from_dict.assert_called_with(
{'filters': {'param1': 'value1', 'param2': 'value2'}}
)
mock_use_case().execute.assert_called_with(internal_request_object)
Функция конечной точки должна быть изменена так, чтобы отразить это новое поведение и сделать тест валидным. Итоговый код нового Flask-метода storageroom() выглядит следующим образом
import json
from flask import Blueprint, request, Response
from rentomatic.use_cases import request_objects as req
from rentomatic.shared import response_object as res
from rentomatic.repository import memrepo as mr
from rentomatic.use_cases import storageroom_use_cases as uc
from rentomatic.serializers import storageroom_serializer as ser
blueprint = Blueprint('storageroom', __name__)
STATUS_CODES = {
res.ResponseSuccess.SUCCESS: 200,
res.ResponseFailure.RESOURCE_ERROR: 404,
res.ResponseFailure.PARAMETERS_ERROR: 400,
res.ResponseFailure.SYSTEM_ERROR: 500
}
storageroom1 = {
'code': 'f853578c-fc0f-4e65-81b8-566c5dffa35a',
'size': 215,
'price': 39,
'longitude': '-0.09998975',
'latitude': '51.75436293',
}
storageroom2 = {
'code': 'fe2c3195-aeff-487a-a08f-e0bdc0ec6e9a',
'size': 405,
'price': 66,
'longitude': '0.18228006',
'latitude': '51.74640997',
}
storageroom3 = {
'code': '913694c6-435a-4366-ba0d-da5334a611b2',
'size': 56,
'price': 60,
'longitude': '0.27891577',
'latitude': '51.45994069',
}
@blueprint.route('/storagerooms', methods=['GET'])
def storageroom():
qrystr_params = {
'filters': {},
}
for arg, values in request.args.items():
if arg.startswith('filter_'):
qrystr_params['filters'][arg.replace('filter_', '')] = values
request_object = req.StorageRoomListRequestObject.from_dict(qrystr_params)
repo = mr.MemRepo([storageroom1, storageroom2, storageroom3])
use_case = uc.StorageRoomListUseCase(repo)
response = use_case.execute(request_object)
return Response(json.dumps(response.value, cls=ser.StorageRoomEncoder),
mimetype='application/json',
status=STATUS_CODES[response.type])
Обратите внимание, что мы извлекаем параметры из строки запроса глобального Flask-объекта request. После того как параметры строки запроса окажутся в словаре, необходимо лишь создать объект запроса от него.
Заключение
Ну, вот и все! Некоторые тесты в REST-слое отсутствуют, но, как я говорил, это лишь рабочая реализация для демонстрации чистой архитектуры, а не полностью разработанный проект. Думаю, вы должны попробовать добавить самостоятельно некоторые изменения, такие как:
- ещё одна конечная точка, к примеру, доступ к одиночному ресурсу (
/storagerooms/<code>) - реальное хранилище, подключенное к настоящей БД (как вариант, SQLite)
- реализация нового параметра строки запроса, например, расстояние от заданной точки на карте (рекомендую использовать geopy для простого вычисления расстояния)
Во время разработки вашего кода, всегда пытайтесь следовать TDD-подходу. Тестируемость — это одна из главных особенностей чистой архитектуры, очень важно писать тесты, не игнорируйте их.
Вне зависимости от того, решите ли вы использовать чистую архитектуру или нет, я надеюсь, что этот пост поможет вам получить свежий взгляд на архитектуру программного обеспечения, как это случилось со мной, когда я впервые узнал об изложенных здесь концепциях.
