From 1b67ee5eba855801340d668fbb956d70d342ea55 Mon Sep 17 00:00:00 2001 From: Callista-del-Mar <92268061+Callista-del-Mar@users.noreply.github.com> Date: Wed, 8 Dec 2021 10:15:49 +0700 Subject: [PATCH] Punctuation and word order modified --- .../02-Раздел I. Проектирование API/04.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/src/ru/clean-copy/02-Раздел I. Проектирование API/04.md b/src/ru/clean-copy/02-Раздел I. Проектирование API/04.md index d0271b8..a37368e 100644 --- a/src/ru/clean-copy/02-Раздел I. Проектирование API/04.md +++ b/src/ru/clean-copy/02-Раздел I. Проектирование API/04.md @@ -2,7 +2,7 @@ Исходя из описанного в предыдущей главе, мы понимаем, что иерархия абстракций в нашем гипотетическом проекте должна выглядеть примерно так: - * пользовательский уровень (те сущности, с которыми непосредственно взаимодействует пользователь и сформулированы в понятных для него терминах; например, заказы и виды кофе); + * пользовательский уровень (те сущности, с которыми непосредственно взаимодействует пользователь сформулированы в понятных для него терминах; например, заказы и виды кофе); * уровень исполнения программ (те сущности, которые отвечают за преобразование заказа в машинные термины); * уровень рантайма для API второго типа (сущности, отвечающие за state-машину выполнения заказа). @@ -12,7 +12,7 @@ В нашем умозрительном примере получится примерно так: - 1. Сущности уровня пользователя (те, работая с которыми, разработчик непосредственно решает задачи пользователя). + 1. Сущности уровня пользователя (те сущности, работая с которыми, разработчик непосредственно решает задачи пользователя). * Заказ `order` — описывает некоторую логическую единицу взаимодействия с пользователем. Заказ можно: * создавать; * проверять статус; @@ -20,14 +20,14 @@ * отменять. * Рецепт `recipe` — описывает «идеальную модель» вида кофе, его потребительские свойства. Рецепт в данном контексте для нас неизменяемая сущность, которую можно только просмотреть и выбрать. * Кофе-машина `coffee-machine` — модель объекта реального мира. Из описания кофе-машины мы, в частности, должны извлечь её положение в пространстве и предоставляемые опции (о чём подробнее поговорим ниже). - 2. Сущности уровня управления исполнением (те, работая с которыми, можно непосредственно исполнить заказ). + 2. Сущности уровня управления исполнением (те сущности, работая с которыми, можно непосредственно исполнить заказ). * Программа `program` — описывает некоторый план исполнения для конкретной кофе-машины. Программы можно только просмотреть. * Селектор программ `programs/matcher` — позволяет связать рецепт и программу исполнения, т.е. фактически выяснить набор данных, необходимых для приготовления конкретного рецепта на конкретной кофе-машине. Селектор работает только на выбор нужной программы. * Запуск программы `programs/run` — конкретный факт исполнения программы на конкретной кофе-машине. Запуски можно: * инициировать (создавать); * проверять состояние запуска; * отменять. - 3. Сущности уровня программ исполнения (те, работая с которыми, можно непосредственно управлять состоянием кофе-машины через API второго типа). + 3. Сущности уровня программ исполнения (те сущности, работая с которыми, можно непосредственно управлять состоянием кофе-машины через API второго типа). * Рантайм `runtime` — контекст исполнения программы, т.е. состояние всех переменных. Рантаймы можно: * создавать; * проверять статус; @@ -37,7 +37,7 @@ #### Сценарии использования -На этом уровне, когда наше API уже в целом понятно устроено и спроектировано, мы должны поставить себя на место разработчика и попробовать написать код. Наша задача — взглянуть на номенклатуру сущностей и понять, как ими будут пользоваться. +На этом уровне, когда наше API уже в целом понятно устроено и спроектировано, мы должны поставить себя на место разработчика и попробовать написать код. Наша задача: взглянуть на номенклатуру сущностей и понять, как ими будут пользоваться. Представим, что нам поставили задачу, пользуясь нашим кофейным API, разработать приложение для заказа кофе. Какой код мы напишем? @@ -197,7 +197,7 @@ POST /v1/orders При этом существует «золотое правило», применимое не только к API, но ко множеству других областей проектирования: человек комфортно удерживает в краткосрочной памяти 7±2 различных объекта. Манипулировать большим числом сущностей человеку уже сложно. Это правило также известно как [«закон Миллера»](https://ru.wikipedia.org/wiki/%D0%A0%D0%B0%D0%B1%D0%BE%D1%87%D0%B0%D1%8F_%D0%BF%D0%B0%D0%BC%D1%8F%D1%82%D1%8C#%D0%9E%D1%86%D0%B5%D0%BD%D0%BA%D0%B0_%D0%B5%D0%BC%D0%BA%D0%BE%D1%81%D1%82%D0%B8_%D1%80%D0%B0%D0%B1%D0%BE%D1%87%D0%B5%D0%B9_%D0%BF%D0%B0%D0%BC%D1%8F%D1%82%D0%B8). -Бороться с этим законом можно только одним способом: декомпозицией. На каждом уровне работы с вашим API нужно стремиться там, где это возможно, логически группировать сущности под одним именем — так, чтобы разработчику никогда не приходилось оперировать более чем 10 сущностями одновременно. +Бороться с этим законом можно только одним способом: декомпозицией. На каждом уровне работы с вашим API нужно стремиться логически группировать сущности под одним именем там, где это возможно и таким образом, чтобы разработчику никогда не приходилось оперировать более чем 10 сущностями одновременно. Рассмотрим простой пример: что должна возвращать функция поиска подходящей кофе-машины. Для обеспечения хорошего UX приложения необходимо передать довольно значительные объёмы информации. ``` @@ -283,6 +283,6 @@ POST /v1/orders ``` Такое API читать и воспринимать гораздо удобнее, нежели сплошную простыню различных атрибутов. Более того, возможно, стоит на будущее сразу дополнительно сгруппировать, например, `place` и `route` в одну структуру `location`, или `offer` и `pricing` в одну более общую структуру. -Важно, что читабельность достигается не просто снижением количества сущностей на одном уровне. Декомпозиция должна производиться таким образом, чтобы разработчик при чтении интерфейса сразу понимал: так, вот здесь находится описание заведения, оно мне пока неинтересно и углубляться в эту ветку я пока не буду. Если перемешать данные, которые одновременно в моменте нужны для выполнения действия, по разным композитам — это только ухудшит читабельность, а не улучшит. +Важно, что читабельность достигается не просто снижением количества сущностей на одном уровне. Декомпозиция должна производиться таким образом, чтобы разработчик при чтении интерфейса сразу понимал: так, вот здесь находится описание заведения, оно мне пока неинтересно и углубляться в эту ветку я пока не буду. Если перемешать данные, которые нужны в моменте одновременно для выполнения действия по разным композитам — это только ухудшит читабельность, а не улучшит. -Дополнительно правильная декомпозиция поможет нам в решении задачи расширения и развития API, о чем мы поговорим в разделе II. \ No newline at end of file +Дополнительно правильная декомпозиция поможет нам в решении задачи расширения и развития API, о чем мы поговорим в разделе II.