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

3.2. HATEOAS. Hypermedia As Transfer Engine Of Application State. Не бывает. Хотя идея в целом хорошая: к ответу сервер должен цеплять перечень эндпоинтов, связанных с запрашиваемым ресурсом, показывая всю иерархию подчиненных ресурсов. В теории, если вы обращаетесь к корню API, сервер должен отдать всю структуру API, фактически -- документацию. Но реализации такого почти не встречается. 3.3. Версионирование. Тут понятно: у вас может быть несколько версий API, и клиент может пользоваться только какой-то конкретной. Варианта два — добавляем версию в URL: /v2/user или в кастомный заголовок типа X-API-VERSION или похожий. Вот такие уровни зрелости и правила REST. И цитата из Роя Филдинга: A REST API should be entered with no prior knowledge beyond the initial URI and set of standardized media types that are appropriate for the intended audience. [...] In other words, if the engine of application state (and hence the API) is not being driven by hypertext, then it cannot be RESTful and cannot be a REST API. Period.

Про REST слышали наверняка все. Некоторые даже слышали про RESTful. Единицы вспомнят модель зрелости REST Леонарда Ричардсона и её уровни. Между тем, есть отличная статья Guy Levin, перевода которой я почему-то не нашел. Нужно это срочно исправить! Здесь дам короткий вольный пересказ. Уровень 0: The swamp of POX (Plain old XML) — Болото старого доброго XML. Это нам напоминает, с чем боролся Рой Филдинг: XML, SOAP и вызовы разных функций из одного эндпоинта методом POST. Даже тут есть правила: 1. В названиях эндпоинтов слова нужно разделять дефисом: "-", это spinal case или kebab-case, "шашлычный стиль" — слова как бы нанизываются на шампур. 2. Подчеркивания в названиях эндпоинтов лучше не использовать. Почему так: потому что ссылки в тексте подчеркиваются, и символы "_" могут визуально потеряться, в отличие от "-". 3. Все ссылки должны быть в нижнем регистре. Это всё рекомендации RFC3986. 4. Расширения (то есть точку) лучше не использовать, формат ответа задаётся заголовком Content-Type. Пример: http://api.example.com/blogs/guy-levin/posts/this-is-my-first-post Уровень 1. Ресурсы. Идея: разные эндпоинты для разных ресурсов. Названия эндпоинтов - существительные. Правила: 1. Слэш ("/") в конце названия эндпоинта не нужен. Каждый ресурс имеет один адрес (URI). Разные URI указывают на разные ресурсы. 2. Слэш употребляется для указания иерархии ресурсов: http://api.canvas.com/shapes/polygons/quadrilaterals/squares, http://api.college.com/students/3248234/courses/2020/fall 3. Существительные в единственном или во множественном числе? Тут у автора сомнения, но большинство фреймворков поддерживают названия ресурсов во множественном числе. Мне лично тоже больше нравится во множественном. Уровень 2. Методы. Используем для операций с ресурсами стандартные методы http, соответствующие CRUD: POST, GET, PUT, DELETE, PATCH + дополнительные HEAD и OPTIONS. Если вам не хватает операций CRUD, автор рекомендует сделать подчиненный ресурс /actions, и делать к нему POST с указанием типа операции и дополнительных параметров. Такой небольшой кусочек RPC-like style, когда RESTful не одобряет, но очень хочется. 2.1. Заголовки HTTP Используйте заголовки! Тема тут обширная, но в основном заголовки используются для безопасности, переговоров клиента и сервера о форматах и кодировках контента, о кэшировании, версиях и обновлениях ресурсов, их размерах. Собственно, запрос HEAD возвращает заголовки без самого тела ресурса, чтобы клиент мог понять — нужно ли запрашивать ресурс вообще. 2.2. Параметры запроса Используйте параметры запроса! (та часть, которая после @?"). Не забывайте про такие операции, как фильтрация, поиск, сортировка и пагинация. Для фильтров добавляем названия полей ресурса, по которым можно отфильтровать результат, указав значения или диапазон: https://example.com/api/products?category=electronics&price=50-100 Для поиска — параметр ?q={строка поиска}. Для сортировки: ?sort={поле, по которому сортируем}&order={ASC|DESC}. Как вариант, для сортировки по нескольким полям: ?sort=name,-price (сортируем по названию в прямом порядке, по цене — в обратном). Для пагинации указываем число элементов на странице и номер страницы: ?limit=10&offset=20. 2.3. Коды ошибок Используйте коды ошибок HTTP. Уровень 3. Управление гипермедиа. Тут два аспекта: обсуждение формата и HATEOAS. 3.1. Обсуждение формата — это про заголовки. Клиент и сервер договариваются, в каком формате сервер вернет ресурс. Может, в json, может в XML, а может просто в виде текста. В теории должно работать, и серверы должны отдавать ресурс в удобном для клиента представлении. На практике реализация встречается очень редко, но во внутренних гетерогенных системах может быть полезным. Запрос OPTIONS как раз про это: какие действия допускает сервер над ресурсом и в каких форматах готов его отдавать.

Упомянутый вчера BTABoK прекрасен большим количеством различных шаблонов-канвасов на разные случаи жизни. Лежат они в разделе Structed Canvases, и там много вкусного. Вот, например, шаблон для описания сервиса (частично подойдет и для описания интеграций). По-моему, просто огонь! 🔥🔥🔥 Что мы хотим знать про сервис: — Его тип (сущность / задача / функция) — Его уровень (бизнес-процесс / возможность / ядро бизнеса / инструмент / инфраструктура ) — Зависимости — Ценность, которую он поставляет — Его интерфейс (как с ним работать) — Кто им может пользоваться (типовые консьюмеры) — Политики / правила / соглашения / ограничения по использованию — Атрибуты качества — JTBD для сервиса — Команда разработки и стоимость разработки — Метрики и аналитика — что собираем? — Экономика сервиса

Кто нас учит. Раньше меня часто просили порекомендовать какую-нибудь книгу по системному анализу и смежным областям. В последние пару лет почти перестали — теперь просят порекомендовать курс! Так вот книг именно по системному анализу и управлению требованиями давно уже никаких не выходило, тема себя исчерпала. Свежие книги только про продукты и архитектуру. Но книги — это, в общем, попсовый источник знаний. Есть более формальные тексты: стандарты (и руководства по их применению), научные статьи и своды знаний — Body of Knowledge. Сегодня про них. Ну, все точно слышали про PMBoK и BABoK. Но есть ещё куча интересных сводов знаний, в которых собраны по кусочкам разные знания, которые вообще-то нужны продвинутым аналитикам! Поехали: SWEBoK — Software Engineering, он же — ISO/IEC TR 19759:2015. Свод знаний по программной инженерии, ни много, ни мало! Современные программисты про него и не слышали. Тут нас могут интересовать разделы про требования, software architecture, software design и software construction (это всё разные понятия!), а ещё софт-скиллы и экономика разработки (это 11 и 12 главы). SEBoK — Systems Engineering, а это уже по системной инженерии в целом. Кстати, более-менее свежие идеи про работе с требованиями приходят именно из системной инженерии, это у них одна из основных практик. Тут всё начинается с самого начала: что такое система, что такое системное мышление, что такое модель и т.д. Из наших тем: бизнес-анализ и анализ миссии (как космические миссии, что-то более осмысленное и менее структурированное, чем проект), анализ потребностей стейкхолдеров, определение архитектуры; собственно системный анализ (этот термин мало где ещё встречается). Ещё из интересного: рассмотрены нюансы приложения инженерии к продуктам, сервисам и предприятиям (Часть 4). Системный анализ, при этом, понимается как работа по выбору решения: определение критериев оценки, оценивание проектных свойств разных вариантов решения, выбор итогового решения. Здесь же предполагается изучение компромиссов (Trade-Off Studies), включающее анализ эффективности, стоимости и технических рисков. Ну это на случай, если вы не знаете, чем должен заниматься системный аналитик — вот этим, в основном. EABoK — Enterprise Architecture, тут всё понятно. Непонятен только статус: на сайте MITRE лежит черновик от 2004 года (pdf), есть ли что новее, я не понял. В черновике, судя по всему, авторы пытаются не заблудиться между TOGAF, DODAF, Zachman Framework и другими способами описания EA, но у них не получается. BIZBoK — Business Architecture, свод знаний по бизнес-архитектуре. Стратегия, бизнес-возможности, структура организации, бизнес-инициативы, ценности, продукты, нормативка — всё тут. А также референсные модели бизнес-архитектуры для разных индустрий. BTABoK — Business Technology Architecture, это про цифровую трансформацию. Хотя сами авторы оплёвывают этот термин, заявляя, что это только чтобы у вас деньги выманить, а говорить нужно про цифровое превосходство (Digital Advantage). Дальше они также оплёвывают TOGAF, SAFe, BABoK и так далее. В целом, замах тут "как говорить с бизнесом про ИТ". Дико интересно, но местами неокончено. BPMCBOK — тут всё понятно, управление бизнес-процессами. Есть русский перевод, и даже довольно активное российское отделение соответствующей международной ассоциации. GISTBoK — это свод знаний по геоинформационным системам, про него мало что могу сказать, мало сталкивался с такими системами, но картинки красивые, и внутри довольно много хардкорной математики и программного кода (в отличие от остальных сводов, где максимум концептуальные схемки). DMBoK — Data Management, свод знаний по управлению данными. Всё, что вы хотели узнать про данные в любом виде (в том числе — про качество данных и интеграцию данных). Есть перевод и открытый конспект на русском, но при случае рекомендую обзавестись оригиналом, если вы много работаете с данными в каком-либо аспекте. Знаете ли вы ещё какие-нибудь своды знаний? А пользу в них видите?

Не понимаю, откуда берётся вопрос "куда развиваться дальше сеньор-аналитику?". Причем с ответами типа "идти в продакты / архитекторы / лиды аналитики". Очевидно же, что после сеньора нужно идти в стафф-аналитики, потом — в сеньор-стафф, потом — в принципал, и, наконец, в феллоу аналитика. Это же типовая линейка инженерных ступеней в западных компаниях. А то у нас, как обычно — краем уха услышали, что есть такие джуны-мидллы-сеньоры, побежали внедрять, до конца не дослушав. И что там после сеньора ещё целая лестница есть — так и не узнали. Нет после сеньора выбора: архитектор или управленческий трек. Это у вас в компании что-то неправильно поняли. Сеньор — это старший аналитик на одном проекте. Стафф — аналитик, курирующий несколько проектов. Принципал — это тот, кто закладывает принципы работы всех системных аналитиков в компании (опыт — 8+ лет). Феллоу — советник CTO или директора по системному анализу и проектированию систем (10+). Там ещё могут быть промежуточные уровни вроде "бизнес-партнер" (слышали же про HR BP? вот то же самое, только по технологиям) и distinguished (это перед fellow). И это всё должности специалистов! Людьми руководить не нужно, не менеджерский трек! Вопросов, как повысить зарплату очень ценному чуваку, не делая его начальником, не возникает — сделай ещё грейдов, бери, повышай. Начиная с уровня партнера это может называться не "системный анализ", а просто "технологии"; к этому моменту системный аналитик уже должен был повидать всякого и разобраться в деталях всех технологий и подходов к архитектуре. При этом необязательно становится архитектором, архитектор — проектирует решение, аналитик — задаёт границы решения и выявляет все аспекты, которые должны быть учтены. В российских компаниях даже должность специальная для этого предусмотрена: советник. Советник может быть у подразделения (обычно не ниже департамента, это как раз уровень стаффа), у директора, заместителя или президента (пред.правления, если у вас АО). Я сам когда-то работал советником директора по технологиям в одной финансовой организации — и это, пожалуй, была самая подходящая для меня роль и самое лучшее время. Ты — самый крутой эксперт по определенному вопросу в организации. Ты подчиняешься только первому или второму лицу. Тебе не нужно никем управлять (но можешь держать небольшой собственный аппарат, если нужно), но ты имеешь вес и к тебе прислушиваются. Ты можешь разрабатывать концептуальные вещи, а можешь включаться в конкретный проект, если его нужно усилить. Ты выступаешь, как внутренний консультант: можешь дать идею или проработать концепцию, но если исполнительное руководство не послушает тебя и её не реализует — это их проблема, а не твоя. Сплошной кайф. Жаль, что не все компании (и руководители) понимают всю полезность такой роли. Вопросов было бы сильно меньше.

Я уже тут как-то ссылался на Григория Добрякова, архитектора и ИТ-менеджера, очень люблю его посты про индустрию. Вот и опять: Такая боль у кандидатов с моделированием данных, вы бы знали! Даже не знаю у кого больнее: у системных аналитиков или у разработчиков. Я на собесах тупо начинаю с одной простой задачи: допустим, делаем микросервис, заказчик хочет в него положить данные о людях (ФИО) и городах (название), а также данные о том кто в каком городе родился, в каком учился, женился, работал, и так далее. И зачастую мы даже это смоделировать не можем. Disclaimer: сразу обозначу, что мы сначала уделяем много времени смолл-толку, разбалтываем кандидата, и я всегда вежливо уточняю «будет ли тебе комфортно сейчас поговорить о...» Но тем не менее! Половина кандидатов, даже с тимлидским опытом за плечами, вообще не слышат условий и начинают рассказ с выбора способа авторизации в админку. Что? А вот. Другие начинают рассказывать о том, что они сделают таблицу с заказами и положат туда информацию о покупках. Каких блин покупках?? А вот. Это же у нас покупатели, верно? Значит у них покупки... (никакие покупки в задаче не звучали) Абсолютное большинство в упор не может ответить на вопрос «давай всё же перечислим, какие у нас будут столбцы?».. Вести человека к варианту ответа «давайте для начала сделаем одну табличку на три столбца для фамилии, имени и отчества» приходится за ручку. И ради бога не стоит задавать вопрос «а как вы эту табличку назовёте». Я раньше задавал. На реляции с городами умирают все. За буквально годы задавания этой задачки я могу по пальцам перечислить людей, которые поставили посередине транзитивную таблицу из трёх столбцов «человек — город — тип отношения». Абсолютное большинство лепят дополнительные столбцы к табличке людей. И на мой следующий вопрос «хорошо, а теперь давайте сохраним информацию о том, в каком году человек там родился, в каком учился, в каком женился» — лепят ещё столбцы с годами. Не видя никаких проблем. Люди с 15 годами опыта Senior System Analyst. Люди с опытом тимлидства и проектирования архитектуры в резюме. Ноль сомнений. Последний раз я не выдержал и закруглил беседу, когда человек предложил положить информацию о городах в json в атрибуты человеков. Не как денормализованный кэш, а именно основные данные. А потом я их добиваю вопросом как к этому всему приделать REST API. Например, какие методы нужны для удаления информации о том, что некий Вася Пупкин жил в Москве с 2010 по 2012 год. Канонический REST, ага. Вы ж в резюме заявляли? — Ну это будет метод DELETE! — уверенно заявляет кандидат, но дальше вспоминает свою же структуру данных и начинает жалеть что вообще вписался в этот разговор. Нет, справедливости ради, встречаются жемчужины с которыми интересно разбирать нюансы и подсказывать куда можно копнуть. Но с остальными то что не так? В моей практике, изучение любого фреймворка в программировании всегда начиналось с ORM. Подробно разбиралось, как организовать данные, построить между ними реляции, открыть их во внешнее API с помощью контроллеров и предоставить элементарный CRUD-интерфейс. Да, можно критиковать ORM как инструмент, но в такой картине мира любой микросервис проектируется за пару чашек кофе. Логическую цепочку «Domain model — ERD — модели — реляции — ресурсы — CRUD API — унифицированные интеграции — низкие косты» не видит в принципе никто. Зато поп*здеть на тему REST vs GraphQL готов каждый второй, ага. Когда всё поломалось в этом мире? Что программируют эти программисты? Что проектируют эти блин системные аналитики? Ребята, а если у меня проект на 200+ классов предметной области (бывало), а мы тут с вами в двух путаемся, то что дальше будет? Что блин не так то?

Если вам нравится идея нарезки требований (решений) на уровни, то в Archimate есть, пожалуй, самая детальная нарезка в Layered Viewpoint, многослойном представлении архитектуры: 🟡 внешние акторы (клиенты, организации) 🟡 услуги, которые мы им предоставляем (бизнес-сервисы) 🟡 бизнес-процессы, при помощи которых предоставляются услуги 🔵 ИТ-сервисы, которые поддерживают процессы 🔵 прикладные ИТ-системы, которые предоставляют сервисы 🟢 Инфраструктурные сервисы, обеспечивающие работу ИТ-системы 🟢 Инфраструктура (оборудование, базовые ИТ-системы) Ко всему этому можно на любом уровне приписать стейкхолдеров с интересами, мотивацией, ограничениями, требованиями, ценностями. Вот эта разбивка на абстрактные сервисы, которые дают кому-то ценность, и конкретные системы, которые их предоставляют, очень понятна для архитектора и для многих руководителей (и я так много раз рисовал, даже ещё не зная, что в Архимейте это зашито в стандарте). Особенно заходит идея: как мы из разных сервисов будем собирать одну большую услугу/продукт, если их у нас много или они под каждый проект собираются уникальным образом. И какие мы будем в разных клиентских проектах использовать технологии для реализации одних и тех же сервисов: вот для этого проекта ещё по-старому вручную, вот для этого -- на прототипе -- nocode решении, а вот тут попробуем нашу новую платформу использовать. Удобно это всё зафиксировать на диаграмме, чтобы все понимали свой маневр.

Осенью на Infostart Tech Event меня попросили рассказать про уровни требований: все эти BRS, SRS и так далее. Вообще я не очень люблю эту историю с пачкой многоуровневых документов, но в двух случаях она оправдана: 1) Если вы их разрабатываете последовательно, и перед переходом к более детальному документу принимаете решение: идём дальше или нет? А ещё, по-хорошему, рассматриваете несколько вариантов, и выбираете из них. Тогда вам нужен предыдущий документ, чтобы вернуться к нему — начать заново или проверить соответствие. 2) Если команда между документами меняется. Это не очень хорошая история, но бывает. И документ тут — не самый лучший вариант, но уж какой есть, иногда только так. И, уж если вы всё-таки разрабатываете эти документы, как бы они не назывались, смысл их такой: 👉🏻 Что нужно? 👉🏻 Как делать будем? 👉🏻 Что в итоге сделали? 👉🏻 Как этим пользоваться? И — как и почему в каждом случае принимали решения. А то иногда смотришь, и думаешь — wtf?! А у людей ведь мысль какая-то была. В общем, держите всю презентацию, может пригодится.

Шикарная шпаргалка по различным стилям и протоколам API от Алекса Сюя (Alex Xu) и Postman. Это именно протоколы, стили и архитектуры, поэтому конкретных решений тут нет (а где же Kafka и RabbitMQ? Они в EDA и AMQP, соответственно). В статье текстом подробно описаны преимущества и недостатки каждого стиля и протокола. В принципе, это уже половина готового курса по технологиям API, дальше гуглить вглубь, если нужно подробнее разобраться. Ссылка: https://blog.postman.com/api-protocols-in-2023/

Сделал для вас памятку по ошибкам интеграции: на какие вопросы стоит ответить, чтобы охватить все возможные варианты ошибок. Все ошибки делятся: ➡️ по месту возникновения: - проблемы с клиентом (системой, которая запрашивает или передаёт данные) - проблемы с сервером (система, которая отвечает на запрос) - проблемы со средой передачи (сетью) - проблемы с промежуточными системами (шлюзами, брокерами, преобразователями и т.п.) ➡️ по времени возникновения: - при обращении к серверу - при передаче/преобразовании данных (особенно если у нас длинный или составной запрос) - при получении подтверждения успешного получения от сервера ➡️ по критичности: - ещё не ошибка, но при частом повторении станет ошибкой (например, система слишком долго отвечает) - разовая ошибка, можно продолжать работу - массовая ошибка, невозможно дальше продолжить работу - один из компонентов не отвечает, но система в целом работоспособна и может это выявить - система в целом не работоспособна, выявить может только внешний мониторинг ➡️ по уровню: - технические ошибки (нет связи, таймаут) - ошибки представления: не тот протокол или формат данных (ждали xml, пришел json) - логические или бизнес ошибки (со связью всё в порядке, но сами данные не такие, как требуется: чего-то не хватает или лишнее, но без понимания смысла данных распознать ошибку невозможно) Смотрим на возможные сочетания, принимаем решение: — в нашей системе такое может быть? — кто это может обнаружить? — как системы информируют друг друга, какие есть соглашения о кодах ошибок? — как мы это будем обрабатывать? Заносим каждую ситуацию в таблицу с конкретными данными. Можно таблицу разбить на несколько: по уровням ошибок (технические/бизнесовые) или по компонентам, которые могут ошибки обнаружить / попробовать исправить. Пользуйтесь!

Ну вот, в Zoom появился встроенный AI-суммаризатор разговоров, вот теперь мы всё узнаем о содержательности и смысле наших совещаний 😂😂😂 Всё по Азимову: "Лорд Дорвин за все пять дней обсуждения не сказал ни одной определенной фразы, причем вы этого и не заметили" Следующим шагом, наверное, будет AI-модератор, чтобы человечишки всё-таки приходили к каким-то решениям :)) (Картинка из поста https://www.facebook.com/kuzmenko.kira/posts/pfbid0Fd4VRYVWqan3iiRz2Mz85JUBJBCAQBevDHJvHMdmjRQbPAkd9ZHb2uYvWtpLu2mSl)