Системный сдвиг

Пятничный пост (не очень серьезный) Набор вопросов из предыдущего поста можно обобщить и использовать для рассмотрения системы в целом. Интересно, что список вопросов можно взять примерно тот же, что используется коучами для самоопределения людей :) Вот, например, пирамида Дилтса (не путать с Маслоу и Минто!). Её уровни: 1. Окружение. Кто вокруг, контекст, использующая система. От кого мы зависим, чьё мнение про систему для нас важно. На кого мы хотим повлиять. 2. Поведение. Это функции системы. Что система делает, как ведёт себя в зависимости от реакции пользователя/внешней среды. 3. Способности (capabilities) — возможности системы. Что система потенциально может делать (и что ей сделать будет трудно). Тут связь с архитектурой. 4. Ценности и принципы. Продуктовые параметры. Что для нас, хорошо, и что — плохо? На что мы никогда не пойдем? Что мы будет поддерживать изо всех сил? Что для нас ценно, а что неважно? (Важны ли данные пользователя, или их можно потерять? Важна ли безопасность? Важна ли социальная составляющая, и какие именно взаимодействия мы хотим поддерживать? Исходя из чего мы выбираем, что делать?) 5. Идентичность — вот эта система, она кто? Ведь обычно система представляет опосредованное взаимодействие людей (вы могли бы пойти в банк и общаться с операционистом, но используете банковское приложение). И вот эта система для пользователя — кто? Помощник? Советник? Контролер? Наставник? Диджей? Экспертный продавец? И т.п. Например, для одной школьной системы мы пришли к выводу, что система, которую задумывали, как дневник, на самом деле должна вести себя как тьютор — не ругать за ошибки, а спрашивать про настрой и мягко вести к цели. 6. Миссия — зачем мы делаем систему? Какое влияние хотим оказать на мир? Как говорят коучи, решение любой проблемы находится на более высоких уровнях пирамиды. Если у вас противоречивые требования к функциям — проверьте уровни способностей, ценностей и идентичности. Если вы затрудняетесь с определением архитектуры — подумайте над идентичностью и миссией.

Обещал написать, какими вопросами можно зацепить функции для робота-пылесоса. В целом, всё сводится к анализу контекста и окружения: нам нужно понять, что может находиться вокруг робота во время работы и с чем он может столкнуться. Также нужно немного подвигать временное окно — что было до того, как началось выполнение действия, и что может быть после. Я пользуюсь набором простых вопросов (иногда в уме, иногда в явном виде — для сложных проектов) для каждого действия (сценария). Вопросы: * Для чего? (Вариант: что будет дальше?) * Какое обратное действие? * Кто? (роль; есть ли дополнительные признаки и условия?) * Когда? (ограничения на допустимые состояния; триггеры автоматического запуска) * Где? (какое устройство? что вокруг?) * С кем? Кто рядом? * Сколько? (любой численный показатель, который может описывать процесс) * Как? (какие есть альтернативные способы выполнения действия и какие ограничения?) * Какой? (особенности, классификаторы и состояния объекта) * Что нужно/может быть до начала действия? (в описании use case это нужно писать в "предусловия", но мало кто пишет) * Что уменьшается/увеличивается в процессе? (например, при записи на курс уменьшается число свободных мест; у робота тратится заряд и увеличивается убранная площадь) * Чем заканчивается действие? (Постусловия, что будет создано? что поменяется? есть ли триггер на прерывание длительного действия?) * Что может помешать выполнить действие? * Что будет, если каких-то объектов 0,1,N? (Например, один студент записывается на курс. Может ли на курс записаться N студентов одним действием? А N студентов параллельно?) Можно добавить вопросы безопасности: * Чем система может навредить при выполнении действия? * Какую информацию нельзя показывать/изменять при выполнении действия? * Что может сделать злоумышленник при выполнении действия? На фичу из предыдущего поста могут навести вопросы "Кто рядом?" (дети, домашние животные), "Что было до?" (что от них могло остаться на полу?), "Что может помешать?", "Чем система может навредить?"

Отличное задание для проверки аналитика на собеседовании: предложите кандидату написать требования для управления роботом-пылесосом. А потом посмотрите — появится ли в списке требований обнаружение собачьих/кошачьих 💩 и остановка в этой ситуации. Конечно, можно наткнуться на человека, у которого есть дети и/или домашние животные, и который сам оказывался в ситуации, когда робот-пылесос не обладал такой функцией, въехал в :poop: и потом разнес его по всему дому... Но если животных нет, то какой ход мысли должен быть у аналитика, чтобы выявить такую функцию? Какие вопросы можно задать, чтобы выйти на такую потребность? А после этого ещё оценить, насколько сложно реализовать такую функцию при помощи имеющихся технологий, и насколько нужно её реализовывать, какова её востребованность и влияние на пользователей? В реальном мире такая функция появилась далеко не сразу — то ли про неё и правда не подумали, то ли не знали, как решить, пока не развились технологии уверенного распознавания образов. Но уж этого-то наверняка было много сообщений от пользователей, можно целый spreadshit составить (pun intended). ⬇️⬇️⬇️ В книге Яна Александера 'Discovering Requirements' (не того, который актер озвучания в Last of Us, а английского учёного в области инженерии требований) разделяются 'greenfield development' и 'brownfield development' — проекты, стартующие с нуля, и проекты развития/модернизации существующей системы. Сбор требований к проектам разного вида имеет свои особенности. В случае Brownfield обычно имеется большое число жалоб, обращений пользователей, предложений и -- очень важный источник — народные сценарии работы, прихватки и инструкции. В компаниях они иногда написаны на клейких листочках, иногда передаются друг-другу в виде доковских файлов или постов на форуме; в старое время я видел тетрадки с записанными рукой шагами для получения какого-нибудь отчета (пойти в настройки, переключить там галочку, потом пойти в отчет, задать такие-то параметры, сохранить в xml, запустить скрипт, который написал парень, работавший здесь 4 года назад, открыть в Excel вот в этом шаблоне, вписать на первой странице точные даты начала и окончания квартала — и отчет готов!). Это всегда просто кладезь информации о том, как пользователи обходят несовершенство системы! Рассуждая дальше о greenfield и brownfield, Александер отмечает, что в университетах и на курсах практически всегда говорят о первой ситуации (сбор требований к новой системе), а в жизни чаще встречается второй вариант: доработка существующей системы. Правда, сам он тоже не слишком много внимания уделяет этой теме, зато упоминает корпоративную археологию! — когда нужно найти описания и причины текущего состояния системы, прокопавшись через несколько культурных слоев документации. Удивительно, но книга Александера никогда не переводилась на русский (написана в 2009). А по содержанию и концентрации смысла она точно не хуже Вигерса!

На корпоративных тренингах на рабочем месте часто бывает ситуация, когда люди отваливаются: вчера ещё было 3 человека в команде, а сегодня, смотришь — остался только один, остальных растащили на встречи. И часто этот оставшийся работает лучше и быстрее, чем до этого они работали втроем! Я и сам сталкивался с таким, как участник: на одном курсе по управлению проектами мы выполняли задание сначала индивидуально, а потом то же задание в группах. По идее, результат группы должен быть лучше самого лучшего индивидуального результата, но моя группа сумела даже ухудшить мой результат :) Инициативу захватила одна участница, которая, видимо, очень хотела показать свои лидерские качества, а проще всего это сделать, если всех критиковать, подвергать сомнению и настаивать на собственной правоте. А то какой же я лидер, если просто прислушиваюсь к другим! Я в это играть не очень хотел, ну и вот. Не хотите ко мне прислушиваться — садитесь в лужу, bon voyage. У этого явления есть название: эффект Рингельмана. В ИТ мы знаем его следствие, известное как Закон Брукса: «Если проект не укладывается в сроки, то добавление рабочей силы задержит его ещё больше». Эффект Рингельмана формулируется так: «Личная продуктивность отдельных членов группы снижается по мере роста численности группы» Изучал он этот эффект на примере перетягивания каната — в принципе, деятельность, похожая на создание ИТ-продукта. В исследованиях Рингельмана общая продуктивность группы уже на 5 участниках составляет только 3.5 (считая эталонную продуктивность каждого в отдельности за 1), а после 7 практически перестает расти, застывая на отметке 3.92. Обычно эффект объясняют двумя причинами: "социальной ленью" и потерей координации. Если мы видим, что над той же задачей работает кто-то ещё, мы уже не так сильно вкладываемся. Это "социальная лень" или "социальное бездействие". Если наши действия нескоординированы, мы, как минимум тратим время на их координацию (в том числе — выясняя, кто тут главный), как максимум — начинаем действовать разнонаправлено, разбалансируя работу. Что тут можно сделать? Брукс предлагал выстраивать группы вокруг признанного лидера и эксперта, по типу операционной бригады (всегда есть главный хирург, который делает операцию, остальные ему ассистируют). Agile говорит, что команда должна быть не больше, чем можно накормить двумя пиццами (5-7 человек). Исследования сообщают, что социальное бездействие ослабевает, если: 1. У людей есть общая разделяемая цель 2. Вклад каждого участника может быть идентифицирован и оценен 3. Люди чувствуют свою незаменимость В целом, это вопрос мотивации. А вот координация — вопрос технический, это "харды" организации работ. Сам Рингельман, кроме перетягивания каната, изучал ещё перетаскивание камней при помощи веревок и перемещением тележек мускульной силой (он вообще занимался организацией работ в сельском хозяйстве, и работал примерно в одно время с Тейлором и Гастевым). Измеряя силы, прикладываемые работниками к камню, он выяснил, что основная проблема в синхронизации усилий: то один начинает не вовремя, то тянут в разные стороны. Про мотивацию он как раз не писал. В общем, эти харды применимы к любым работам: - нужно обеспечить последовательность работ; - устранить потери (объект работы ждёт человека; человек ждёт объект работы); - по возможности убрать одновременные разнонаправленные работы над одним объектом; - очертить каждому участнику границу работ и поставить точную цель; - определить, формализовать и ограничить по срокам процесс принятия решений; В конечном счете это всё про разделение (объектов и выполняемых над ними работ), объединение (результатов работ в единое целое) и принятие решений. Хм, кажется, опять получилось про анализ и архитектуру.

В этом году я член ПК Летнего Аналитического Фестиваля, он состоится в Подмосковье 13-14 июля, и остается чуть больше недели, чтобы подать заявку на доклад! Подавайте заявку, даже если вы ещё ни разу нигде не выступали, но очень хотите попробовать. ЛАФ в этом смысле — одна из самых демократичных конференций. Темы, которые мы ждем больше всего: - Проектирование, интеграция и архитектура - Практики использования инструментов для системных аналитиков - Продуктовые практики - Использование AI-инструментов А также: - Разработка и управление требованиями - Развитие и саморазвитие аналитика - Soft skills - Лидерство и управление командой - Другие темы, которые помогут расширить кругозор аналитика Мы будем рады рассказам и рефлексии личного опыта в реальных проектах, а также любым интерактивным форматам: мастер-классам, воркшопам, деловым играм, круглым столам и дискуссиям. Зарегистрировать заявку на доклад можно здесь: https://events-pro.ru/conference/fe501f51-4043-4340-882b-55e5cd97f1a5/become_speaker (Если совсем сомневаетесь — можете мне в личные сообщения написать с идеей, обсудим) Для докладчиков проживание в отеле Sheraton Skypoint Luxe 5* БЕСПЛАТНО при включении вашего выступления в программу. Срок подачи заявок - до 20 апреля 2024 года.

Ваше API не REST! Ну и что? Слова "REST API" уже несколько потеряли свой смысл, и только пуристы и зануды вспоминают Леонарда Ричардсона с его четырьмя уровнями зрелости REST API и Роя Филдинга с его диссертацией. Это как Конституция — все слышали, что она есть, но мало кто её сам читал, а уж когда доходит дело до применения... Мы используем http — значит, у нас уже REST! В реальной практике чего только не бывает, и CRUD вокруг ресурса — под что REST наилучшим способом заточен — бывает как раз не так уж часто. В сервисах и микросервисах часто в API выставляют некие функций (у которых даже имена, как у функций: getClientPortfolio, validatePassport, saveFile), и близко не покрывающие матрицу действий по созданию, чтению, изменению и удалению. И это оправдано! Ну вот какой ресурс мы создаем или читаем при проверке паспорта заёмщика? Да мы его просто проверяем. не-REST API — это нормально. Если вы осознанно выбрали этот вариант, и понимаете плюсы и минусы. Удаленный вызов процедуры, RPC, как паттерн имеет смысл. Только давайте будем честны перед собой и не будем называть это REST. С другой стороны, а как называть, если это не SOAP, а что-то более легкое и на JSON-чиках? Вообще, с 2005 года существует и развивается протокол JSON-RPC, сейчас уже версии 2.0. Хотите RPC на JSONах — возьмите хоть что-то более-менее стандартизованное, не изобретайте велосипед. Есть уже готовые реализации протокола почти на любом языке. Официальный сайт https://www.jsonrpc.org/ Есть свой эквивалент сваггера и OpenAPI: OpenRPC, который одновременно и документацию генерит, и работает как WSDL для SOAP — то есть, позволяет получить весь контракт сервиса JSON-RPC. Короче! Не придумывайте свои велосипеды, используйте готовые! В англоязычной среде есть термин 'bikeshadding', "обсуждение сарая для велосипедов". Велосипеды здесь по совпадению, а может быть и нет. Источником является история про комиссию, которая должна была согласовать проект атомной электростанции, но на каждом совещании занималась рассмотрением мелких вопросов вроде сарайчика для велосипедов — из каких он должен быть материалов и где установлен? Другое название этого эффекта — "Закон тривиальности": "Участники обсуждения всегда придают чрезмерное значение тривиальным вопросам" или "Время, потраченное на обсуждение пункта повестки, обратно пропорционально его важности" Это типичное проявление когнитивного искажения, связанного с подменой объекта: мы избегаем думать о сложном и труднодоступном объекте, предпочитая обсуждать нечто другое — явно или неявно. В общем, прекращайте обсуждать сарайчик для велосипедов! Решите главное: у вас REST или RPC. Решили? Берите готовый стандарт: OpenAPI и JSON:API для REST, JSON-RPC или SOAP для RPC, и двигайтесь дальше. Там, глядишь, и до gRPC доживете :)

Я учу людей уже больше 15 лет — сначала в университетах, потом на тренингах. За это время через меня прошло, наверное, больше тысячи учеников. И вот что я заметил: кроме знаний и навыков в людях существуют некоторые базовые реакции и вообще отношение к делу, которые очень сложно изменить. В модели KSA это третья буква — Attitude, в переводе: отношение, подход, жизненная позиция. Я уже писал про неё парураз. И это отношение очень хорошо проявляется на тренинге. Почти на каждом курсе по выявлению требований и проектированию систем появляется задача поиска внешней документации. Люди выбирают предметную область, в которой есть регуляторные документы: стандарты, приказы, регламенты. Либо (на тренингах по проектированию интеграций) возникают интеграции с внешними системами — государственными или стандартными в отрасли — например, 1С. И среди многих сотен участников моих образовательных событий за все годы я могу по пальцам пересчитать людей, которые действительно пошли и почитали эти документы! Регламенты, стандарты, документацию по способам интеграции. Единицы! В основном все говорят: ну, мы предположим. Или: мы понимаем, что так нужно сделать, и в реальном проекте мы бы нашли эти документы и изучили их, а на тренинге — да ну, зачем. Доходит до смешного: я прихожу, скажем, на второй день тренинга, и показываю группе документацию или даже тестовый эндпоинт, которые я нашел по пути домой. Очень интересно, говорят участники, и продолжают выдумывать удобные им форматы. Это то самое отношение. Это естественная реакция на новое. Я — даже на тренинге, и даже для участников учебного проекта — не могу оставить какой—то вопрос повисшим в воздухе. Мне нужно разобраться и найти источники. С одной стороны это любопытство — а как они вот это всё спроектировали? С другой — тревожность: как же я оставлю в проекте вопрос, который от меня не зависит, непроясненным. Это срабатывает на автомате: обнаружил внешние требования — нашел их источник. (Так же у меня на автомате срабатывает фактчекинг и поиск исходного источника при прочтении новостей). И это отношение очень важно для аналитика! Любопытство, желание докопаться до источников, опасение оставить в проекте дырку или голые предположения. Тем более, что очень часто все документы есть на расстоянии буквально пары кликов — вбить поисковый запрос и прочитать первые две-три страницы в выдаче. И ведь как интересно может быть! Помню, когда я вел тренинг Сергея Нужненко про ручку, мы загадали участникам написать ТЗ на ручки для детского самоката. Так как это товар для детей, было очевидно, что он зарегулирован. И действительно, есть ГОСТ Р ИСО 8124-1-2014, где детским самокатам посвящен отдельный раздел 4.29 и разделы 5.26-30 с методами испытаний. Это же просто песня! Во-первых, можно сразу брать из документа готовые требования. Во-вторых, я надолго зачитался самим стандартом и пришел в восторг — как много, всё-таки, требований к физическому изделию — там и размеры, и прочность, и острые углы, и акустика, и магнитные свойства, и электрические — вот где действительно требуется анализ требований! Конечно, такое отношение не возникает на тренингах — просто не хватает времени. Возможно, его можно воспитать в университете за годы обучения. Или на работе — при понятной и быстрой обратной связи и влиянии среды (что касается ценностей, мы ориентируемся на окружающих — теория разбитых окон работает в обе стороны). Ну и смежный вопрос — как проверить этот самые attitudes на собеседовании? (И есть ли у нанимающего менеджера они в списке проверок). Вообще они легко проверяются при помощи небольшого тестового, требующего изучения внешней документации, но я слышал, что тестовые задания сейчас очень негативно воспринимаются кандидатами...

Собственно, по управлению требованиями у нас есть целый ГОСТ Р 59194-2020. Вот его основные положения. 1. Есть два вида деятельности: — разработка требований (инженерная деятельность по выявлению, анализу, декомпозиции, проверке, согласованию и утверждению требований к изделию). — контроль требований (управленческая деятельность, направленная на поддержание актуальности и согласованности требований к изделию и его СЧ в ходе всего ЖЦ изделия (в том числе при изменении потребностей заинтересованных сторон). 2. Требования могут быть представлены в форме базы данных или документа. 3. Есть исходные требования — фиксирующие потребности заинтересованных сторон и служащие для валидации, и есть проектные требования — для разработки различной документации готового объекта и для верификации. 4. Есть два типа "контрольных рубежей": — на которых проверяют, согласовывают и утверждают разработанные требования к объекту (в результате требованиям присваивают статус готовности); — на которых проверяют соответствие объекта требованиям (в результате требованиям присваивают статус выполнения). 5. При проверке требований выполняют их валидацию и верификацию. При валидации проверяют: — полноту покрытия спецификацией исходных требований — правильность выражения потребностей или отражения принятого технического решения — наличие связи с потребностями или родительским требованием — непротиворечивость При верификации: — что требования относятся к одному объекту (!) — что требования соответствуют критериям качества — что у них правильно заполнены атрибуты, они правильно классифицированы и связаны — установлены критерии верификации и валидации объекта, который будет разработан по этим требованиям. 6. Минимальный набор атрибутов требования: — Уникальный идентификатор — Ссылка на потребность заинтересованной стороны (в идеале -- выраженной в документе. Ссылка на конкретный пункт документа) — Для проектных требований — ссылка на исходное требование или запись о принятом техническом решении (привет ADR!) 7. Очень сильная идея: требования являются частью конфигурации! И статус выполнения требования тоже относится к конкретной конфигурации и конкретному этапу работ (в стандарте они названы "контрольные рубежи"). То есть, одно и то же требование может быть выполнено в одной конфигурации, и не выполнено в другой! Про конфигурации и их изменения есть соседний ГОСТ Р 59193-2020 "Управление конфигурацией", там, в частности, написано, как обходиться с изменениями конфигураций разных видов и по разным причинам (и изменениями требований, как части конфигурации). Про конфигурации очень часто не задумываются, пока не обнаруживают себя в ситуации, когда развернуто 8-10 экземпляров одной и той же системы, отличающихся набором данных, справочников, функций, набором ролей, подключенных внешних систем и заглушек и средств мониторинга. Причем никто в точности не знает — сколько их точно развернуто, где, чем они друг от друга отличаются и кто к ним имеет доступ. Вот тут-то управление конфигурациями и начинается!

У Григория Добрякова, которого здесь уже цитировал, вышел пост про управление требованиями. К гигиеническому минимуму он относит вот что. Требования должны быть: 1. Сформулированы. 2. Записаны. 3. Доведены до адресатов. 4. Проверены на соответствие результатов. В деталях: Сформулированы: Должна быть буквально проведена работа по выявлению ожиданий. Кто, чего и от кого/чего ожидает. Особенно если неявно. Особенно если «ну я думал вы сами догадаетесь, это же очевидно». Записаны: Должна быть буквально проведена работа по фиксированию всего о чём проговорили. Текстом, документом, табличкой, реестром, схемами, всем чем можете. Лаконично, но достаточно. Главная цель — ничего не оставить на словах. Сюда же входит задача провалидировать записанное с заказчиками. Иван Иваныч, а я правильно записал? Ну-ка гляньте. Доведены до адресатов: Доводить — это процесс, а не просто галочка в отчёте. Ты требование видел? А осознал? А технически реализовать сможешь? А ресурсы есть? А чё сломается если сделать буквально как написано? Результат проверен на соответствие. Тут вроде понятно, причём это не только верификация, но и валидация: "Причём у малоопытных менеджеров результат может быть в полном соответствии с требованиями формально, но абсолютно вырвиглазно по сути." Этот пост мне живо напомнил принцип 3C's Рона Джеффриса, сформулированный ещё в 2001 году применительно к пользовательским историям: Card, Conversation и Confirmation. Требования сформулированы и записаны — это Card. В оригинале карточка не равна требованию, сам Рон называет её токеном (token), вещью для представления требования и управления им. Такая заметка, чтобы не забыть, что нужно обсудить идею. Четвертую C обычно не упоминают, но это Commitment — обязательство. Как только идея — может быть, ещё даже не требование! — зафиксирована, у команды возникает обязательство её обсудить. В одном из проектов у меня даже KPI были такие — число обработанных идей, то есть — рассмотренных, обсужденных, возможно — проверенных экспериментом и принятых в работу. Обсуждение — conversation — вот что важно. Это решает задачи и по формулированию, и по доведению до адресатов (тех, кто будет создавать реализацию). И тут стоит добавить пятую C — Collaboration. Требования не записаны в голове у стейкхолдера, требования - точнее, решения по свойствам будущего продукта — рождаются в ходе совместного обсуждения, поэтому обсуждение так важно. И особенно важна возможность свободного высказывания членами команды, предложения идей, уточнения запроса. Вовлечение команды разработки в процесс определения свойств продукта (специально не пишу "выявления требований"!). Иначе это прямой путь к выгоранию. Тут опять возникает commitment: обсудив решение, команда принимает обязательство по его реализации. А коллаборация подключает "эффект Икеа": если ты принимал участие в разработке решения, то ценность его для тебя растет, и такое решение легче исполнять. Ну и подтверждение, confirmation. В свежей (от 2019 года) статье про 3C's Рон пишет про сдвиг в сторону максимально конкретного выражения этого самого confirmation — в виде конкретных примеров, в идеале — исполнимых. Хуже ничего нет, чем "совещание по приёмке" — когда толпа людей просто идут по пунктам ТЗ и отмечают их реализацию путем осмотра готового ПО, без заготовленных примеров, без рассмотрения краевых ситуаций и стыков — на чем в последствии и вылезают большинство дефектов. Так что, идеальная картина: 1. Зафиксировали намеченное требование (идею). 2. Обсудили вместе с заказчиком и представителями разработки, наметили способ реализации. 3. Составили и согласовали способ проверки. 4. Реализовали, проверили. А для полного контроля и прозрачности хорошо бы завести правило, что ни одно изменение не вносится в систему без указания связи с требованием (тех.долг — это тоже требование!), ни одно требование не принимается без изменений в коде.

Знаете ли вы, что уровни обязательности требований стандартизированы? Ну, хотя бы в Интернете: есть RFC 2119, где перечислены следующие модальные глаголы: MUST (необходимо) — а также требуется (REQUIRED) и нужно (SHALL), означают абсолютную необходимость. MUST NOT (недопустимо), SHALL NOT (не позволяется) — соответственно, абсолютный запрет. SHOULD (следует) и RECOMMENDED (рекомендуется) — требования, от выполнения которых можно отказаться при наличии разумных причин. SHOULD NOT (не следует) и NOT RECOMMENDED (не рекомендуется) — эти вещи допустимы, но могут вызвать проблемы. MAY (возможно) и OPTIONAL (опционально) — можно включать (для полноты), можно не включать (для упрощения) — в целом, все должны быть готовы к тому, что у кого-то эта функция может быть не реализована. Конечно, все эти уровни имеют смысл, когда одна спецификация может иметь несколько реализаций — как при реализации интернет-протоколов разными вендорами. Когда же мы сами можем столкнуться с подобной ситуацией? Конечно, когда мы разрабатываем общедоступное API! Помимо самой спецификации, в этом случае хорошо бы выпустить описание протокола взаимодействия, в котором перечислить — что является абсолютно необходимым, что — желаемым, а что — только опциональным. Соответственно, на своей стороне быть готовым обрабатывать запросы, в которых опущены опциональные параметры и данные. Например, такую спецификацию я разрабатывал для открытого протокола приёма цифрового следа о действиях обучающегося для Университета 20.35 (подмножество протокола xAPI). Понятно, что мы не можем ожидать от всех клиентов, что они в полной мере реализуют весь протокол, и стоит в явном виде им сказать — что обязательно, а что можно опустить. А вот в RFC 6919 от 1 апреля 2013 были добавлены дополнительные уровни требований: MUST (BUT WE KNOW YOU WON'T) — необходимо(но мы знаем, что вы всё равно не сделаете). Думаю, тут не нужно объяснять, очень полезный уровень требований в реальных проектах! В реальной практике выражение в скобках очень часто опускается. SHOULD CONSIDER (следует рассмотреть) — когда авторы спецификации хотели бы, чтобы тут что-то было сделано, но пока не придумали — что именно. REALLY SHOULD NOT (действительно не следует) — когда мы знаем, что что-то нежелательное всё равно будет сделано, и поэтому не можем написать "недопустимо". OUGHT TO (сделать это — ваш долг) — когда речь идёт скорее о моральных обязательствах, но мы не можем требовать этого по контракту. WOULD PROBABLY (вероятно стоило бы) — когда четкого обоснования требования нет, на автор спецификации хочет надавить на разработчика, используя пассивную агрессию. MAY WISH TO (могут пожелать) — описание почти бессмысленной функциональности, которую запросил кто-то из второстепенных согласующих и которую точно никто не будет делать, но намек на неё остается, чтобы не затягивать согласование документа. COULD (может) — тонкий намек на критически важную функцию, но без жестких требований. POSSIBLE (возможно) — авторы спецификации не пришли к единому мнению насчет этого. Кто-то считает, что такое вообще никогда не может произойти, но, скорее всего, это фундаментальная функция, и ситуация будет случаться очень часто. MIGHT — не знаю, как перевести, я уже запутался в уровнях и тонкостях английских модальных глаголов. По-русски это тоже "может", но слабее, чем COULD и имеет оттенок просьбы. На русском, конечно, стоило бы составить свой список. Я точно видел в документах "следует рассмотреть", "должно быть определено", "может потребоваться" и "возможно". А вы с какими уровнями обязательности сталкивались?

В статье про то, как Вася проектировал API, есть блок про безопасность. Но не такую безопасность, как https и схемы авторизации, а не совсем очевидную: раскрытие чувствительных данных и компрометация системы. Компрометацию я видел вблизи и в очень неприятном виде: в сервисе электронных домашних заданий (которые прямо на компьютере можно выполнять, то есть это по сути тесты) имелся API, через который можно было получить верные ответы. Разумеется, школьники его сразу же обнаружили и начали использовать: появились боты, выдающие правильные номера ответов. Да, через некоторое время проверку полностью перенесли на сервер, но обратно убедить учителей, что теперь-то школьники не смогут найти правильные ответы, так полностью и не удалось. Про ситуации, когда по известной структуре адреса можно скачать документ безо всякой авторизации, думаю, вы не раз слышали. То есть, у вас есть бинарный документ (doc, pdf, xls) или образ (jpg, png), и он лежит в файловом хранилище, а в ответ API подставляется по ссылке. Если ссылки устроены однотипно, а файлы имеют упорядоченные наименования — например, по порядку, или по дате — то можно выкачать их все. Например, как это было на Госуслугах. Ну и другие открытые метаданные бывают интересными, вот тут статья про анализ поведения такси по открытым данным. На что стоит обратить внимание: ✅ полномочия доступа к статическим ресурсам тоже должны проверяться. Ну, это не всегда хочется или есть возможность сделать. поэтому есть следующее правило: ✅ выдача идентификаторов не должна идти подряд! Иначе можно простым инкрементом вытащить сразу много объектов. А также, например, узнать прирост числа объектов за день, что тоже может быть интересным. ✅ не показывайте ссылки на технические домены — для мониторинга и отслеживания ошибок. Если уж ссылаетесь, то не размещайте там же, например, репозиториев с кодом или открытых технических страниц / админок по стандартным адресам. А то мы тут с сыном, пока ждали очереди в поликлинике, запустили на их справочном киоске youtube — именно по цепочке незакрытых технических ссылок. ✅ избегайте бесконтрольное перекладывание данных из БД в API, включая мета-информацию (кто создал, кто последний раз обновлял, и т.п.) ✅ не выдавайте лишней информации в ошибках. Например, API Github не выдает ошибку 403 при попытке доступа к приватному ресурсу, а выдает 404 — чтобы нельзя было в принципе обнаружить существование такого ресурса! ✅ контролируйте частоту запросов от одного клиента — у того же Github есть сложная система с первичными и вторичными лимитами, можно взять, как источник вдохновения. ✅ контроль подозрительной широты запросов клиента, не соответствующих естественным бизнес-потребностям (от имени учителя истории в средней школе множество запросов результатов тестов по математике и физике 10-11 классов) ✅ не передавайте алгоритм расчета или проверки на клиента (хотели тонкого клиента и избежать обновлений клиентов). Тут понятно — передать-то мы передали, а вот что клиент этот наш, и что именно по этому алгоритму он будет считать и проверять...

У статьи про стажера Васю и идемпотентность, про которую писал тут, оказывается, есть продолжение, в котором Вася разбирается с ретраями — повторными запросами. При идемпотентности такие перезапросы выполнять безопасно. Вот только они могут добить замедлившийся сервер. Хотя статьи эти написаны в первую очередь для разработчиков, аналитикам, особенно проектирующим API, тоже нужно разбираться в теме. Особенно критичной тема перезапросов становится при наличии множества экземпляров клиента (фронтового клиента или клиента-микросервиса) и высокой нагрузки. Если у вас API используется только между двумя экземплярами системы раз в сутки — то вам и заморачиваться особо не нужно (и вообще это больше похоже на ETL, а не на API). Впрочем, в любом случае стоит рассчитывать, что удаленный сервер упадет. Вопросы только — когда и какова будет продолжительность недоступности. Даже если сервер не упадет совсем, а просто замедлится — начнет расти число активных клиентов по Закону Литтла: число клиентов в очереди равно интенсивности запросов умноженное на среднее время обработки запроса. Через некоторое время сервер просто перестанет отвечать: все доступные соединения будут заняты. Если клиент сам обрабатывает запрос другого сервиса — что бывает очень часто в микросервисной архитектуре — задержка начнет распространяться по всей системе в обратную сторону, и ляжет всё. Как сказано в статье от AWS: Рассмотрим систему, в которой вызов пользователя создает пятиуровневый стек вызовов сервиса. Он предусматривает отправку в итоге запроса к базе данных, а также три повторные попытки на каждом уровне. Что происходит, когда в базе данных начинают возникать ошибки запросов вследствие нагрузки? Если на каждом уровне выполняются свои повторные попытки, нагрузка на базу данных увеличится в 243 раза, что сделает ее восстановление маловероятным. Какие моменты в статье про Васю и на что нужно обратить внимание, когда в проектируете перезапросы: 1. Максимальное число перезапросов (в какой-то момент нужно остановиться и выдать ошибку) 2. Промежутки между запросами: равные или увеличивающиеся (exponential backoff)? Кроме экспоненциального роста промежутка бывают ещё увеличивающиеся по последовательности Фибоначчи. 3. Максимальное время, пока мы вообще делаем перезапросы. 4. Jitter — случайная задержка между запросами, чтобы распределить нагрузку от разных экземпляров клиентов. 5. Circuit Breaker — "размыкатель" — отключение ретраев при превышении числа неисполненных запросов определенного порога, например — 20% 6. Retry Budget — на перезапросы выделяется ограниченный "бюджет", доля от общего числа запросов. В статье от AWS упомянут "алгоритм маркерной корзины", который работает примерно так: от каждого успешного запроса клиент "откладывает" в "корзину" часть маркера/токена, например, 0.1. Для того, чтобы сделать перезапрос, клиент должен "взять" из корзины целый токен (соотношение 1/10). Если целых токенов в корзине нет — перезапрос не на что сделать. Также в статье описана техника deadline propagation — когда клиент передает серверу в заголовке запроса значение таймаута, после которого он будет делать ретрай. Если сервер понимает, что не укладывается в таймаут, он сразу прерывает выполнение запроса и возвращает ошибку, причем учитывает ожидание ответа от следующего сервера в цепочке. P.S.: Кроме статьи про ретраи, про Васю есть ещё статья, в которой он проектирует API, там тоже много интересного.