Классный референс для проектирования API, респект компаниям, которые собирают и шарят знания🔥
Forwarded from Системный сдвиг
Postman, кроме того, что производит инструмент для тестирования API, ещё собирает лучшие практики проектирования.
Для этого у них есть отдельная команда Postman Open Technologies, которая также собирает информацию о стандартах, отраслевых форматах и спецификациях, открытых API.
Каталог практик и паттернов оформлен как рабочее пространство Postman: https://www.postman.com/postman/workspace/postman-open-technologies-openapi-governance-templates/overview (открывается прямо в Postman!)
Смысл каталога в том, чтобы не придумывать каждый раз "как мы будем возвращать сумму платежа" или "как будем делать пагинацию", а брать готовое решение.
На текущий момент там описаны следующие паттерны:
🔸 Форматы данных:
🔹Коды стран (ISO 3166)
🔹Коды валют (ISO 4217)
🔹Дата, время и временные промежутки (ISO 8601)
🔹Числа с десятичными дробями
🔹Кастомные заголовки HTTP
🔹Расширенное описание ошибки (RFC 9457 - кстати, очень хороший формат для передачи смысла ошибки HTTP)
🔸Управление кэшированием:
🔹Параметр Cache-control
🔹Параметр Etag
🔹Параметр Expires
🔸Фильтрация:
🔹Параметры поискового запроса
🔹Точное соответствие
🔹Диапазон значений поля
🔹Выбор полей для ответа
🔸Пагинация:
🔹Заголовки page and per_page (rfc 5988)
🔹Курсор / NextRecordKey
🔹Параметры Limit и Offset
🔸Сортировка:
🔹По одному полю - параметры sort_by, sort_order
🔹По нескольким полям
🔸Версионирование:
🔹На уровне URL API
🔹На уровне отдельного ресурса
🔹Через заголовок Accept-Version
🔹Через заголовок Accept
🔸Информация:
🔹Контакты разработчиков
🔹Лицензия
🔹Условия использования
🔹Заголовок Sunset (предупреждение, что ресурс станет недоступным в определенное время)
Набор паттернов интересный, я, например, про RFC 9457, версионирование на уровне ресурсов и Sunset header раньше не слышал.
Для этого у них есть отдельная команда Postman Open Technologies, которая также собирает информацию о стандартах, отраслевых форматах и спецификациях, открытых API.
Каталог практик и паттернов оформлен как рабочее пространство Postman: https://www.postman.com/postman/workspace/postman-open-technologies-openapi-governance-templates/overview (открывается прямо в Postman!)
Смысл каталога в том, чтобы не придумывать каждый раз "как мы будем возвращать сумму платежа" или "как будем делать пагинацию", а брать готовое решение.
На текущий момент там описаны следующие паттерны:
🔸 Форматы данных:
🔹Коды стран (ISO 3166)
🔹Коды валют (ISO 4217)
🔹Дата, время и временные промежутки (ISO 8601)
🔹Числа с десятичными дробями
🔹Кастомные заголовки HTTP
🔹Расширенное описание ошибки (RFC 9457 - кстати, очень хороший формат для передачи смысла ошибки HTTP)
🔸Управление кэшированием:
🔹Параметр Cache-control
🔹Параметр Etag
🔹Параметр Expires
🔸Фильтрация:
🔹Параметры поискового запроса
🔹Точное соответствие
🔹Диапазон значений поля
🔹Выбор полей для ответа
🔸Пагинация:
🔹Заголовки page and per_page (rfc 5988)
🔹Курсор / NextRecordKey
🔹Параметры Limit и Offset
🔸Сортировка:
🔹По одному полю - параметры sort_by, sort_order
🔹По нескольким полям
🔸Версионирование:
🔹На уровне URL API
🔹На уровне отдельного ресурса
🔹Через заголовок Accept-Version
🔹Через заголовок Accept
🔸Информация:
🔹Контакты разработчиков
🔹Лицензия
🔹Условия использования
🔹Заголовок Sunset (предупреждение, что ресурс станет недоступным в определенное время)
Набор паттернов интересный, я, например, про RFC 9457, версионирование на уровне ресурсов и Sunset header раньше не слышал.
🔥54👍5
Классная метафора Кента Бека про уровень воды во время прогулки по острову.
Несколько предположений:
- Вода всегда на одном уровне (нет)
- Следует во что бы то не стало забираться на вершину (нет)
- У нас только один остров (нет)
- Мы можем навсегда обосноваться на одном острове (нет)
Ну и в конце про мою любимую адаптивность:
Подробнее в статье https://tidyfirst.substack.com/p/design-is-an-island, рекомендую подписаться ✍️
Несколько предположений:
- Вода всегда на одном уровне (нет)
- Следует во что бы то не стало забираться на вершину (нет)
- У нас только один остров (нет)
- Мы можем навсегда обосноваться на одном острове (нет)
Ну и в конце про мою любимую адаптивность:
Being prepared for both overland and underwater travel is the best preparation for software design success.
Подробнее в статье https://tidyfirst.substack.com/p/design-is-an-island, рекомендую подписаться ✍️
Substack
Design is an Island
First published April 2009.
👍13❤5
Интересная заметка. Аргументы против выглядят немного притянуто, но использование
https://www.infoworld.com/article/3714840/avoid-using-enums-in-the-domain-layer-in-c-sharp.html
record вместо enum выглядит интересно, что только у дотнета по перформансу?https://www.infoworld.com/article/3714840/avoid-using-enums-in-the-domain-layer-in-c-sharp.html
InfoWorld
Avoid using enums in the domain layer in C#
Understand the pitfalls of using enumeration types in the domain layer of your .NET applications and the advantages of using record types instead.
👍6
Любите ли вы AI так как люблю его я?)
Сегодня в 20:00 МСК Staffan Palopää проведетсеанс черной магии с последующим разоблачением демонстрационную сессию использования генеративного ИИ для EventStorming. Подключайтесь в зум или ютуб. Запись обычно у них доступна и после.
Сегодня в 20:00 МСК Staffan Palopää проведет
Virtual Domain-Driven Design
DDD & Domain Modeling: Using AI to Accelerate Design - with Staffan Palopää
DDD & Domain Modeling can take a long time to learn and understand. This could be one of the biggest impediments for increased adoption of DDD. With the help of AI, we can speed up the learning process dramatically. We can create domain models (from prompts)…
👍11🔥3
Просматриваю новый техрадар. Пока единственное что отметил: большой уклон в сторону LLM. Среди техник, например, 8 из 14 непосредственно связаны с LLM/GenAI. Забавно что на холд при этом предлагается поставить "Overenthusiastic LLM use". Увлекайтесь, но не сильно 😄
😁8❤3👍1
Попалась классная статья про рефакторинг. Бывают, конечно, и более сложные кейсы, но в целом согласен по всем пунктам.
https://open.substack.com/pub/danielmoka/p/refactor-like-a-pro
https://open.substack.com/pub/danielmoka/p/refactor-like-a-pro
Craftbettersoftware
Refactor like a PRO
The art of continuous, safe and aggressive refactoring
👍18
ArchDays выкатили видео доклада Влада Хононова https://www.youtube.com/watch?v=rH3u9DvOlPk
Я сам не посмотрел еще - поделитесь вашим мнением🙏
Я сам не посмотрел еще - поделитесь вашим мнением🙏
YouTube
Сложность и модулярность две стороны одной медали. Влад Хононов.
Выступление на ArchDays 2023. Забронируйте участие на следующей конференции: https://archconf.ru/arch
При проектировании систем мы стремимся достичь модульности и избежать сложности. Но довольно часто происходит обратное. Почему?
Чтобы ответить на этот вопрос…
При проектировании систем мы стремимся достичь модульности и избежать сложности. Но довольно часто происходит обратное. Почему?
Чтобы ответить на этот вопрос…
👍28
Сегодня начались доклады на DDD Europe 2024. Первый день называется DDD foundation. Доклады по достаточно базовым вещам - но надеюсь услышать что-то полезное энивей.
Я пропустил первый доклад от Майкла Физерса и сейчас слушаю про транзакции, легаси и прочее. Stay tuned 🤙
Я пропустил первый доклад от Майкла Физерса и сейчас слушаю про транзакции, легаси и прочее. Stay tuned 🤙
🔥13👍10❤1
const ABCTwoSomeText: React.FC<ABCTwoSomeTextProps> = ({ softName }) => {
return (
<>
<Text size="small" className="mt10x">
<Trans i18nKey="some:abc->abcTwo->access" values={{ softName }} />
</Text>
=========> {/* Will be useful in the future */}
{/* <Text size="small">
<Trans i18nKey="some:abc->abcTwo->accessDate" values={{sfotName, date: moment(date).format("DD.MM.YYYY")}} />
</Text> */}
</>
);
};
export default ABCTwoSomeText;🙈2
Кажется в умных книжках все уши прожужали, что закомментированный код это зло. Но тем не менее это встречается повсеместно и даже опытные люди могут не придавать значения.
Я не буду писать почему закомментированный код это плохо. Давайте разберемся откуда берется закомментированный код и каковы причины.
Первый вариант. Была реализована некоторая функциональность, которая теперь не нужна. Что делает разработчик в рамках новой таски? Правильно, комментит код! Почему он выбирает такой путь?
- Так проще! И на самом деле при большом давлении сроков мы выбираем здесь и сейчас не самые оптимальные решения.
- Разработчик не уверен в решении. Мы комментим, запускаем код, оцениваем результат глазами или через тесты. Если нет результата - комментим что-то другое, раскомменчиваем пока не получим нужное поведение. Получили? Льем в репу, ведь (см. пункт первый) так проще!
- Разработчик не верит продакту/аналитику/постановщику задачи. У многих был опыт когда фичу требовали вернуть. И проще просто раскомментить нужный кусок, чем что-то делать средствами гита.
Второй вариант. Мы что-то сделали в рамках большой фичи, но некоторая малая часть не получила пока что аппрув. Вот этот кусочек и комментим для прекрасного будущего. Причины, в целом, те же самые: когнитивный перегруз, давление дедлайнов, поломанная коммуникация с продактом, недоверие коду, нехватка практики с гитом, фича-флагами и тп.
Третий вариант, который приходит в голову - копипаста чужого кода и отсекание комментами всего ненужного (почувствуй себя великим скульптором!). Но по большей части этот вариант сводится к первым двум.
Что же делать? Можно пообещать разные кары и периодически публично высмеивать коллег. Можно настроить проверки в гите и реджектить такие коммиты. Но это борьба с последствиями. И она может только частично замаскировать существующие проблемы.
Попробуем повлиять на причины.
Инструментарий.
Не все знают гит в совершенстве. И в этом нет ничего стыдного, ведь почти всю работу с гитом сейчас забрали IDE. Но можно регулярно рассказывать на внутренних митапах и прикапывать полезные команды и подходы в базе знаний. Нет митапов и базы знаний? Заведите, это очень полезные практики.
Коммуникация с продактом.
Зачастую у нас нет прямого влияния на продакта. Но есть способы которые мне помогали: обратная связь, коучинг и обучение. Да, вы можете развивать вашего продакта, учить его, наставлять. Хорошие продакты готовы принимать новое и не воротят нос, если вы с ними разговаривает не на языке красоты кода, а объясняете влияние тех или иных решений на систему.
Давление сроков.
Уже много раз писал, что жесткие дедлайны портят код. Как бы умные дядьки типа Фаулера не убеждали нас, что качественный код писать быстрее и дешевле, под давлением сроков многие из нас выберут срезать углы здесь и сейчас (и получить даже за это квартальную премию), хоть суммарно это и приведет к удорожанию поддержки и разработки. Старайтесь избегать дедлайнов там где это возможно. Если вы даете примерную дату релиза, то убедитесь, что все воспринимают это именно как прогноз, а не дедлайн. Если ваш продакт или проджект менеджер привык к ковровым дедлайнам - расскажите про последствия, можно с примерами из вашей кодовой базы.
Неуверенность в решении.
Что нам дает уверенность в нашем решении? Компилятор, юнит-тесты, автотесты, регресс, телеметрия с прода, продуктовые метрики и иной фидбек. Чем быстрее мы можем получить обратную связь, тем более мы уверены в нашем коде. Инвестируйте в автотесты, практикуйте TDD, BDD, Test-First и другие подобные практики. Также нам поможет правильная нарезка на модули-сервисы, снижение coupling, единая ответственность и другие подобные подходы.
Как мне видится, эти причины носят достаточно общий характер и работа с ними не толькосделает ваши волосы шелковистыми уберет закомментированный код из репы, но и в целом повысит инженерную и продуктовую культуру в компании.
А как у вас?
Я не буду писать почему закомментированный код это плохо. Давайте разберемся откуда берется закомментированный код и каковы причины.
Первый вариант. Была реализована некоторая функциональность, которая теперь не нужна. Что делает разработчик в рамках новой таски? Правильно, комментит код! Почему он выбирает такой путь?
- Так проще! И на самом деле при большом давлении сроков мы выбираем здесь и сейчас не самые оптимальные решения.
- Разработчик не уверен в решении. Мы комментим, запускаем код, оцениваем результат глазами или через тесты. Если нет результата - комментим что-то другое, раскомменчиваем пока не получим нужное поведение. Получили? Льем в репу, ведь (см. пункт первый) так проще!
- Разработчик не верит продакту/аналитику/постановщику задачи. У многих был опыт когда фичу требовали вернуть. И проще просто раскомментить нужный кусок, чем что-то делать средствами гита.
Второй вариант. Мы что-то сделали в рамках большой фичи, но некоторая малая часть не получила пока что аппрув. Вот этот кусочек и комментим для прекрасного будущего. Причины, в целом, те же самые: когнитивный перегруз, давление дедлайнов, поломанная коммуникация с продактом, недоверие коду, нехватка практики с гитом, фича-флагами и тп.
Третий вариант, который приходит в голову - копипаста чужого кода и отсекание комментами всего ненужного (почувствуй себя великим скульптором!). Но по большей части этот вариант сводится к первым двум.
Что же делать? Можно пообещать разные кары и периодически публично высмеивать коллег. Можно настроить проверки в гите и реджектить такие коммиты. Но это борьба с последствиями. И она может только частично замаскировать существующие проблемы.
Попробуем повлиять на причины.
Инструментарий.
Не все знают гит в совершенстве. И в этом нет ничего стыдного, ведь почти всю работу с гитом сейчас забрали IDE. Но можно регулярно рассказывать на внутренних митапах и прикапывать полезные команды и подходы в базе знаний. Нет митапов и базы знаний? Заведите, это очень полезные практики.
Коммуникация с продактом.
Зачастую у нас нет прямого влияния на продакта. Но есть способы которые мне помогали: обратная связь, коучинг и обучение. Да, вы можете развивать вашего продакта, учить его, наставлять. Хорошие продакты готовы принимать новое и не воротят нос, если вы с ними разговаривает не на языке красоты кода, а объясняете влияние тех или иных решений на систему.
Давление сроков.
Уже много раз писал, что жесткие дедлайны портят код. Как бы умные дядьки типа Фаулера не убеждали нас, что качественный код писать быстрее и дешевле, под давлением сроков многие из нас выберут срезать углы здесь и сейчас (и получить даже за это квартальную премию), хоть суммарно это и приведет к удорожанию поддержки и разработки. Старайтесь избегать дедлайнов там где это возможно. Если вы даете примерную дату релиза, то убедитесь, что все воспринимают это именно как прогноз, а не дедлайн. Если ваш продакт или проджект менеджер привык к ковровым дедлайнам - расскажите про последствия, можно с примерами из вашей кодовой базы.
Неуверенность в решении.
Что нам дает уверенность в нашем решении? Компилятор, юнит-тесты, автотесты, регресс, телеметрия с прода, продуктовые метрики и иной фидбек. Чем быстрее мы можем получить обратную связь, тем более мы уверены в нашем коде. Инвестируйте в автотесты, практикуйте TDD, BDD, Test-First и другие подобные практики. Также нам поможет правильная нарезка на модули-сервисы, снижение coupling, единая ответственность и другие подобные подходы.
Как мне видится, эти причины носят достаточно общий характер и работа с ними не только
А как у вас?
👍22🔥16
Недавно Дима Павлов рассказывал про корпкультуру в целом и в Додо в частности (https://news.1rj.ru/str/on_vision/314)
И очень классно, когда эта культура не только есть, не только поддерживается, но и зафиксирована в виде какого-то артефакта, который можно давать на входе и шарить наружу.
Внезапно для себя узнал, что у Thoughtworks (это те самые кто выпускает техрадар и у кого работает Мартин Фаулер) есть такой артефакт – Sensible defaults.
На мой взгляд, Thoughtworks подобрали очень крутое и точное название. И отсылка к нашей терминологии , и некоторая минималистичность, и разумность без лишнего пафоса.
Что внутри - набор принципов и практик, которые считаются хорошими отправными точками. Например:
- Relentlessly pursue value and business benefits
- Ensure visibility of work
- Prioritize asking hard questions
- Incorporate observability for monitoring functional and infrastructure components
etc.
Рекомендую ознакомиться - буквально 30 страниц, разбитых на блоки.
Хотите обсудить или узнать глубже? У меня есть анонс для вас от Жени @elukianov и Сергея @Bukharovsi_sg
Записываться у бота
Культура – это то, как люди ведут себя в трудных ситуациях и на распутье. В критические моменты мы откатываемся к базовым настройкам. То, какие поступки мы при этом совершаем – это и есть культура.
И очень классно, когда эта культура не только есть, не только поддерживается, но и зафиксирована в виде какого-то артефакта, который можно давать на входе и шарить наружу.
Внезапно для себя узнал, что у Thoughtworks (это те самые кто выпускает техрадар и у кого работает Мартин Фаулер) есть такой артефакт – Sensible defaults.
На мой взгляд, Thoughtworks подобрали очень крутое и точное название. И отсылка к нашей терминологии , и некоторая минималистичность, и разумность без лишнего пафоса.
Что внутри - набор принципов и практик, которые считаются хорошими отправными точками. Например:
- Relentlessly pursue value and business benefits
- Ensure visibility of work
- Prioritize asking hard questions
- Incorporate observability for monitoring functional and infrastructure components
etc.
Рекомендую ознакомиться - буквально 30 страниц, разбитых на блоки.
Хотите обсудить или узнать глубже? У меня есть анонс для вас от Жени @elukianov и Сергея @Bukharovsi_sg
В следующий Понедельник, 15 Июля в 19:00 собираемся на стрим обсуждать Sensible Defaults: кодекс поведения четких разработчиков.
В этот раз начнем с разрабов, секьюрити и девопса
Формат: Встрерча в Zoom, бурное обсуждение. Лимит 1.5 часа, приносить свое пиво, чай, кофе. Приготовьтесь живо участвовать в обсуждении!
Записываться у бота
Telegram
На вижене!
Вчера выступал на панельной дискуссии про корпоративную культуру. Культуролог из меня ещё тот, поэтому уберите слабонервных HR от телевизора. Делюсь тезисами.
Корпоративная культура есть, неважно занимаемся мы ей или нет. Как зима всегда наступает в декабре…
Корпоративная культура есть, неважно занимаемся мы ей или нет. Как зима всегда наступает в декабре…
👍15
DDDevotion
Недавно Дима Павлов рассказывал про корпкультуру в целом и в Додо в частности (https://news.1rj.ru/str/on_vision/314) Культура – это то, как люди ведут себя в трудных ситуациях и на распутье. В критические моменты мы откатываемся к базовым настройкам. То, какие поступки…
tw_report_sensible_defaults_ebook.pdf
3.3 MB
👍6🔥2
Друзья из Health Samurai проводят 8 августа архитектурный митап: про модели, cqrs — всё что мы любим 💪
🔥2
Forwarded from Vladislav Chikishev
Всем привет!
Самураи организуют онлайн-митап по архитектуре систем и кода. Мероприятие состоится 8 августа в 17:00 (Por). Поделимся нашими инсайтами, опытом и хотим послушать вас :)
Будет 2 доклада по 25 минут и время на вопросы и обсуждение:
🔉 Системы движимые моделями
— Николай Рыжиков, CTO at Health Samurai
🔉 CQRS в действии
— Артем Бурыкин, Founder at AVE Systems
Приглашаем опытных инженеров и архитекторов. Участие бесплатное, необходима регистрация!
Подробности про мероприятие 👉 здесь
Самураи организуют онлайн-митап по архитектуре систем и кода. Мероприятие состоится 8 августа в 17:00 (Por). Поделимся нашими инсайтами, опытом и хотим послушать вас :)
Будет 2 доклада по 25 минут и время на вопросы и обсуждение:
🔉 Системы движимые моделями
— Николай Рыжиков, CTO at Health Samurai
🔉 CQRS в действии
— Артем Бурыкин, Founder at AVE Systems
Приглашаем опытных инженеров и архитекторов. Участие бесплатное, необходима регистрация!
Подробности про мероприятие 👉 здесь
👍24🙈1