"Рекомендации по проектированию api". Марина...

Рекомендации по проектированию API

Степанова Марина

– Всем привет! Меня зовут Марина, и я сейчас буду рассказывать, как надо проектировать API.

Начну заново

Меня зовут Марина, и я программист…

…как и моя мама.

Я работаю в команде API Яндекс.Карт

2008 1.0.0

1.1.21

… 2.0.1

2.0.33 2.1-beta

2008 1.0.0

1.1.21

… 2.0.1

2.0.33 2.1-beta

Я начала здесь

300 000 сайтов используют API 15 000 000 пользователей видят карту через API ежедневно (это каждый 10-й человек в России)

Про что я буду рассказывать

!  В чем основная проблема разработки API

!  Приемы проектирования, которые мы применяем, чтобы с этой

проблемой жить

Бонус!

Я буду приводить примеры, когда мы не соблюдали собственные рекомендации и сильно от этого страдали Слайды стыда и позора будут помечены специальным знаком

Корень страданий разработчика API

О чем таком особенном должен помнить проектировщик API?

Программный код Пользовательский интерфейс

К чему все привыкли

Чего хотел пользователь?

Понятно Крутой дизайн

Не глючит

Функциональность

Котики

Няшки

Программный код

Программный интерфейс

Пользовательский интерфейс

Все меняется, когда вы делаете API

Программный код

Программный интерфейс

Пользовательский интерфейс

Все меняется, когда вы делаете API

Мечта каждого программиста – видеть свой код 1 раз в жизни

Чего хочет этот пользователь?

API Пользовательский код, работающий с API Проект

Написал, отладил и

забыл

Если вы ломаете обратную совместимость, пользователь вынужден вечно переписывать код

Пользовательский код №0

Проект

Если вы ломаете обратную совместимость, пользователь вынужден вечно переписывать код

И ему это не нравится

А чего хотим мы сами?

Чего хотим мы, разработчики API?

!  Править баги !  Добавлять фичи ! Рефакторить код

Мы заморочились и посчитали сколько строк кода мы переписали за год

2.0.7 2.0.31

60% кода поменялось

(без потери обратной совместимости)

Итак, причина страданий разработчика API:

Мы должны переписывать свой код, а пользователи должны свой не переписывать

Смягчить удар позволяет правильное проектирование системы

Наши приемы проектирования

Мы разбиваем систему на уровни абстракции

Пример абстракций в API

Точка

Пример абстракций в API

Геообъект Геометрическая

модель DOM-макет

Точка

При формировании уровней абстракции мы следуем некоторым правилам, о которых я и буду говорить

Иерархия уровней

Геообъект Геометрическая модель

DOM-макет

В этом месяце мы должны заработать в

три раза больше

Уровни знают только о своих соседях

Уровни знают только о своих соседях С этого дня

работаете в две смены

Геообъект Геометрическая модель DOM-макет

Не знает, как будет выглядеть, зато знает свои координаты

Ничего не знает про координаты, зато умеет встраиваться в DOM

Уровни знают только о своих соседях

Каждый уровень – это информационный контекст

Здесь важны координаты, проекция, зум

Здесь важны пиксельные координаты окна карты

Максимальное разграничение обязанностей

Canvas-макет

Оценим предусмотрительность нашего старого знакомого

API Пользовательский код, работающий с API Проект

Как знал, что понадобится!

Система превращается в большой конструктор, в котором легко заменяются части

Части вашей системы должны между собой как-то взаимодействовать

Взаимодействие на событиях

«Я подвинулась»

«Карта подвинулась, надо бы перерисоваться»

«Так, говорят надо перерисовываться, двигай наш div»

Геообъект Геометрическая модель

DOM-макет Карта

События дают много места для маневра

В 2.1-beta мы сделали адаптивный дизайн

size = “small” size = “large”

«Большой» макет реагирует на все события

Контрол пробок

addtomap!

select!

expand!

Маленький макет…

select! expand! enable!

providerchange!

ЭЭЭ…

Маленький макет делает что может

Плюсы взаимодействия на событиях

!  Слабая связанность объектов !  Легко «подцепить» новую сущность !  Абстрагируетесь от соседей !  Можно реагировать на события частично

Что мы узнали про уровни абстракции

!  Нужно выстроить иерархию взаимодействия !  Уровни знают только о своих соседях !  Уровень – это информационный контекст !  Максимально разграничиваем обязанности !  Взаимодействие уровней через события

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

Это надо отметить описать!

На арену выходят программные интерфейсы

Что такое программный интерфейс?

!  Описание функциональности, которую предоставляет компонент. Причем в определенном контексте. !

IChild!!.getParent() // Описание методов.!!.setParent()!!@parentchange // Описание событий. !

Интерфейсы наследуются

ICustomizable

IChildOnMap

IGeoObject

Объект, у которого есть менеджер опций

Объект, добавляемый на карту

Геообъект (свои методы + композиция более мелких интерфейсов)

Какие задачи решают программные интерфейсы?

Вспомним пример, в котором мы хотели заменить один из компонентов

Canvas-макет

Как понять, насколько точно нам надо скопировать заменяемую сущность, чтобы система не рухнула?

DOM-макет

Canvas-макет

Если вы описываете интерфейсы, проблем такого рода не возникает

IGeoObject IOverlay ILayout

На это место можно поместить любую реализацию интерфейса

Какие задачи решают программные интерфейсы

!  Вы получаете формальное описание вашей системы !  Сущности становятся легко заменяемыми (подойдет любая реализация интерфейса)

!  Когда вы продумываете программные интерфейсы, вы наводите порядок у себя в голове

Интерфейсы должны быть дробными

ICollection

IParentOnMap

ymaps.Collection

ymaps.GeoObjectCollection

Если в вашем интерфейсе много сущностей - это повод задуматься

setParent() getParent() .options .events

IChild

ICustomizable

IEventEmitter

Названия, ключи, алиасы должны быть очень конкретными

– Петька, get()! – 32! – Что 32? – А что get()?

Грустный пример из реальной жизни www.somesite.ru?%с&%n&%l&%j%s Для расшифровки этого url нужно выучить небольшой нелогичный алфавит: %c – coordinates %l – lang %n – layer (ну потому что %l занято) %j – id (пошло от «jam») %s – timestamp (потому что «stamp»)

В какой момент пора выделять программные интерфейсы?

Вариант №1 (неправильный)

!  Выделяем уровни абстракции !  Пишем код !  Описываем получившиеся интерфейсы

Почему этот вариант неправильный?

У нас в 2.0 появился кластеризатор

Метки собираются в объект-кластер

Кластеризатор

Объект-кластер

Кластеризатору для работы нужно знать, сколько меток в каждом кластере

Можно хранить данные у себя

Можно спрашивать у кластера ???

Идем по пути наименьшего сопротивления

cluster.getGeoObjects()

Позже утверждаем интерфейсы

IGeoObject

ICollection IGeoObject

ICollection IGeoObject IGeoObject

Подставим интерфейсы в схему

ICollection cluster.getGeoObjects() IGeoObject

IGeoObject IGeoObject

IGeoObject

Подставим интерфейсы в схему

ICollection cluster.getGeoObjects() IGeoObject

IGeoObject

Этот метод больше нельзя использовать – он не входит в интерфейс

Как реально выглядит процесс

!  Выделяем уровни абстракции !  Пишем код !  Описываем получившиеся интерфейсы !  Переписываем код, чтобы все сущности использовали только интерфейсные методы

Вариант №2 (правильный)

!  Выделяем уровни абстракции !  Описываем интерфейсы !  Пишем код, в котором объекты взаимодействуют через интерфейсные методы, поля, события

Интерфейсы изменят ваш проект

Подобное станет подобным

Placemark

Polygon

Polyline

IGeoObject

Мы не успели отточить интерфейсы контролов при запуске

Контролы писали разные люди, в результате получили немного разные конструкторы

Button(params, options)! TrafficControl(state, options)! SearchControl(options)!

Обратная сторона интерфейсов

Из-за того, что объекты станут композициями дробных интерфейсов, конечные объекты могут иметь несколько монструозный и избыточный интерфейс.

У нас чудесным, но монструозным вышел IGeoObject

! var myPlacemark = new ymaps.GeoObject({!! !geometry: { ! ! ! !type: “Point”,!! ! !coordinates: [37.61, 55.75] !! !},!! !properties: {!! ! !balloonContent: ‘Hello!’,!! ! !id: 723!! !}!!}, {!! !// Опции.!! !preset: ‘twirl#redIcon’,!! !zIndex: 100!!});!

Мы выбрали самые частые варианты использования и сделали для них хелперы

Создавать метки стало проще

! !var myPlacemark = new ymaps.Placemark([37.61, 55.75], {!! ! !// Данные.!

! ! !balloonContent: ‘Hello!’,!! ! !id: 723!! !}, {!! ! !// Опции.!! ! !zIndex: 100,!! ! !preset: ‘twirl#redIcon’!! !}); !

Также вас спасут значения по умолчанию

Программист изучает опции геообъекта только в тот момент, когда они ему понадобятся и не забивает голову ненужным мусором

Еще одна военная хитрость

Публичная часть Наше API

Все вылизано, документировано, никогда не изменится

Публичная часть Закрытая часть

Все вылизано, документировано, никогда не изменится

Публичная часть Закрытая часть

Таких ситуаций быть не должно

Мы открывали сущности постепенно 2.0.14 2.0.33

Лучше открыть мало, но хорошо, чем много, но плохо

Подведем итоги

Мы в ответе за тех, кто пользуется нашим API

Вывод №1

Вывод №2

Проектирование большой системы – сложный процесс. Но если заложить верные принципы, все получится.

Спасибо за внимание

Степанова Марина Разработчик интерфейсов

mstepanova@yandex-team.ru

! ya_mstepanova

"Рекомендации по проектированию api". Марина...

Technology

по физике 6 класс степанова

Сексуальная жизнь при ВИЧ //...

harley-davidson Степанова Лилия

Руководство по проектированию...

Реклама на улицах Саратова.....

Яндекс маркет

"Как Яндекс распознаёт музыку с...

Правила жизни Коли Степанова

по физике 7 класс степанова

Яндекс расписание

rflp – современный подход к...

Яндекс Метрика

яндекс. метрика

степанова наталья

Современный подход к...

Яндекс директ

Сергей Герштейн, Яндекс

епишина, степанова

степанова лиля

Степанова Ольга РАБОТА 2