День 1640. #ЗаметкиНаПолях
Разработка API для Людей.
Часть 4. Шаблоны разработки. Начало
Часть 1
Часть 2
Часть 3
В этой части серии рассмотрим некоторые шаблоны проектирования, которые достаточно универсальны, чтобы быть полезными практически всем, кто участвует в проектировании API.
1. Язык
Называть вещи трудно. Проблема в том, что, как и в случае с именами переменных и функций, вы хотите, чтобы маршруты API, поля и типы были понятными, но лаконичными.
Используйте простой язык
Это очевидно, но на практике довольно сложно сделать и может привести к «эффекту велосипедного сарая». Постарайтесь выразить самую суть понятия и не бойтесь использовать словарь синонимов. Например, не путайте понятия пользователя и клиента. Пользователь напрямую использует ваш API, клиент (или конечный пользователь) – тот, кто покупает товары или услуги, которые может предлагать ваш пользователь через ваш API.
Избегайте жаргона
Не думайте, что ваш пользователь знает всё о вашей конкретной отрасли. Например, 16-значный номер кредитной карты называется основным номером счета (Primary Account Number, PAN). В финтех-кругах, люди говорят о PAN, DPAN и FPAN, поэтому поймут, если в платёжном API будет:
card.pan = 4242424242424242;
Но для более широкой аудитории всё же лучше подойдёт:
card.number = 4242424242424242;
Это особенно важно, когда вы думаете о том, кто является аудиторией вашего API. Скорее всего, это разработчик, не знакомый с финансовыми терминами, поэтому лучше предположить, что люди не знакомы с жаргоном вашей отрасли.
2. Структура
Используйте enum вместо bool
Представим, что у нас есть API для модели подписки. Мы хотим, чтобы пользователи могли определить, активна подписка или отменена. Кажется разумным определить:
Subscription.canceled={true, false}
Это сработает, но что если вам нужно будет добавить приостановку подписки? Т.е. мы делаем перерыв в приеме платежей, но подписка активна и не отменена. Придётся добавить новое поле:
Subscription.canceled={true, false}
Subscription.paused={true, false}
Теперь, чтобы увидеть фактический статус подписки, нам нужно смотреть на два поля. А что, если они оба true? Можно ли приостановить подписку, которая была отменена?
Вместо этого проще сделать поле статуса с перечислением:
Subscription.status={"active", "canceled"}
Тогда приостановку легко добавить, добавив значение перечисления:
Subscription.status={"active", "canceled", "paused"}
Мы добавили функциональность, но сохранили сложность API на том же уровне, а также сделали его более описательным. Если мы когда-нибудь решим удалить функцию приостановки подписки, удалить значение перечисления всегда будет проще, чем удалить поле. Наверняка есть случаи, когда поле bool подойдёт лучше, но всегда рассматривайте возможность возникновения третьего варианта.
Используйте вложенные объекты для расширяемости
Пробуйте логически сгруппировать поля вместе. Это:
customer.address = {
line1: "Main Street 123",
city: "San Francisco",
postal_code: "12345"
};
выглядит гораздо понятнее, чем:
customer.address_line1 = "Main street 123";
customer.address_city = "San Francisco";
customer.address_postal_code: "12345";
Первый вариант значительно упрощает добавление дополнительного поля позже (например, поле страны, если вы решите расширить свой бизнес для зарубежных клиентов) и гарантирует, что имена полей не станут слишком длинными.
Окончание следует…
Источник: https://dev.to/stripe/common-design-patterns-at-stripe-1hb4
