В рамках микросервисов есть OpenAPI - там и код и документация в одном. Я к тому, что даже если вы доку написали один раз ее потом всю жизнь надо поддерживать. У вас есть на это бюджет, желание и ресурсы? Если нет, то выход один - код лучшая документация (@ValeryGL). Просто не надо разделять их. Отдельная документация устаревает в момент сохранения файла (а то и раньше). В итоге дока как-бы есть, но ее как бы и нет. По этому только доко-генерация (которую можно и не делать) и редкие статейки на вики, которое никто не читает :)
А вот по отоплению как раз есть. Только работает для батарей с регуляторами и внутриквартирным бойлером. Идея в том, что на каждой батарее стоят умные вентили с датчиком температуры воздуха (да, они греются от батареи, но как-то работают причем достаточно точно) и блок управления бойлером. Блок может работать или по цифровому протоколу, если бойлер поддерживает, или просто вкл/выкл - это любой бойлер может. Идея в том что любой датчик может сказать или "я-бы погрелся, если еще кто-то мерзнет" или "мне совсем холодно - включайся, чан железный". При этом если в комнате тепло, то датчики отключают батарею в этой комнате. Получается экономно и реально работает. Есть коммерческие системы. Например Tado.
А ваш комментарий только подтверждает мой :) Есть всего два способа работы с прото - proto first когда вы генерируете исходник по proto и code first когда соотвественно наоборот. Если код генерится по прото, то я ожидаю что когда я тыкну F12 в студии она покажет мне прото. Ан нет она показывает сгенерированый класс, который читать разумеется невозможно. Проблема это среды или прото? А какая разница? Это в любом случае моя проблема.
Не по исходникам же типов потому что типы генерируют сами протобуфы.
Как раз по ним! В простом случае вообще без аннотаций, а в пределе с аннотациями включающими ID. Proto как такового не создается, но gRPC сервер отдает описание нормально. Генерировать прото по исходника супер удобно и если у вас моно репа/один язык, то смысла писать прото отдельно достаточно мало.
А проблемы есть например между Java и C# - Java сервер не любит отсутствие обязательных полей. Таки да, это проблема что C# клиент не проверяет при отправке что не все заполнено, но какая разница? Видно это только в рантайме.
А можно поинтересоваться - зачем вам вся эта макулатура? Что есть конечная цель? Ну вот допустим у вас на руках большой проект. В нем 100500 sequence diagrams, описана схема данных (а так ее что не видно через FK в SQL базах или по связям в ORM?) и все такое. Что теперь вы будете с этим делать и что будут делать другие? Давайте оставим за скобками проблемы аудита. Нужна документация программистам? Они будут ее читать? Не джуны, а все остальные. Если не будут, то скорее всего она вам и не нужна. Я ничего не скажу про аналитиков - им надо - вот и пусть пишут и поддерживают. Мне кажется, что единственная документация - это код и все что из него можно сгенерировать. Все остальное или не нужно или устарело.
Proto создает либо огромные проблемы с читаемостью (goto definition показывает сгенерированный класс, который читать невозможно) либо проблемы с межьязыкоровой совместимостью когда proto создается динамически по исходникам. Он конечно быстрый и все такое, но неудобный.
Я в 90х начинал с графовой (сетевой) базы. Достоинства там - нет поиска (в том смысле что искать по базе не надо вообще - на все и так есть указатели), размер гораздо меньше реляционных. Но недостаток все перевешивает - все запросы к базе фактически зашиты в ее структуру. Может сейчас чего и придумали, но тогда поддерживать ее был сущий ад.
А про статью чтоб два раза не вставать - у таски для разработчика есть всего два состояния - "никто не смотрит" и "сделано". Если появляется "в работе" значит или декомпозиция сделана неправильно (задача слишком большая) или бюрократы захватили планету (по-моему это как раз вариант из статьи). Когда у таски есть готова к тестированию, готова к мерджу, смерджена... мне это напоминает сцену из фильма "Космические М...звоны" (он-же Космические Яйца):
- "Приготовиться к перометке вперед!"
- "Есть приготовиться к перемотке вперед!"
- "Перемотка вперед!"
- "Есть перемотка вперед!"
Это они так видео перематывали :) Посмотрите на диаграмму "работа с историей" и поплачьте. Как-то проще надо быть.
Конфигурация Кубера - аццкий ад. Вместо просто тупо UI предлагается выучить как писать связанную (!) конфигурацию в текстовом редакторе без всякой поддержки. Предлагается пользоваться командной строкой для управдения, редактирования конфигурации и мониторинга. Открою вам тайну, граждане, kubectl не для людей. Он для приложений, которые по-идее должны обеспечивать UI. Да UI обертки есть, но не из коробки и ооочень далекие от WYSIWYG. Я что-то не знаю ни одной, где-бы в один прекрасный момент не появился-бы диалог редактирования Yaml.
Связь между объектами... в текстовых файлах... редактировать руками... Ну да, ну да. Ошибся в labels - нет ошибок, но ничего не работает. Ой, а тут имя секрета надо... а оно относится к внутренним secret store Kubernetes или к секретам GKE импортированным через внешние secret storage? И много-много такого-же.
Отдельные лучи ненависти Gateway/VirtualService - если не работает логов нет, если вы не админ всея кластера. А я не админ! Я админ в своем неймспейсе, и даже default не вижу.
А дальше больше если у вас не один жалкий вэб сервачок (пусть даже масштабирующийся на 100500 инстансов) а меш микросервисов. Руками-ж каждый писать неохота - слишком одинаковые. Ну так helm/tanka в помощь. А вот теперь скажите почему 1) опять свзязь между объектами руками 2) для темплейтов выбран самый извращенный, самый нечитаемый, самый никому неизвестный язык разметки?
Вобщем извините, если кого за живое задел, но накипело. Как будто и небыло тех 20-30 лет развития UI/UX и мы опять вернулись во времена начала CP/M / IBM360 / PDP11
Отлично. Теперь вместо жесткой гарантии получения данных мы получили слабое связывание и отстутствие гарантий вообще. Для страничек в интернете - прекрасно. Для финансовой системы немедленная смерть. (Да есть паттерны типа event sourcing, но они настолько сложны в разработке... и избыточны в большенстве случаев)
Вот пример - синий сервис требует данные фиолетового и они на pub/sub. От фиолетового ничего не пришло. Это он лежит? Это ничего не случислось? Или еще: все то-же самое, но от фиолетового пришло. Ура? А это точно последние данные? Ах там таймстамп-же есть? Ну и что - обновиться через милисекунду оно все равно могло.
Вот и получаются гибридные pub/sub и request/response. А там не только все плюсы, но и все минусы обоих.
Для интраверта контакты не необходимое зло, а ужас и отвращение. Интроверт искренне непонимает зачем, а главное нафига ему этот весь нетворкинг. При отсутствии мотивации к каким-либо контактам о каких советах идет речь?
Automapper просто не работает при количестве объектов в несколько тысяч. Ну как не работает... добавляет 2 минуты к старту системы. Не верю в мепперы как класс.
Чего так привязались к прочтенным книгам-то? Я перестал их читать, когда понял, что все новые мысли от 100-страничной книги можно обычно прочитать в оглавлении по пути домой, понять о чем книга и распознаьть, что ты этим уже много лет как пользуешься. Я конечно не аналитик, но все-же...
Вспомнить статью на Хабре? Смеетесь? Я помню пришествие чОрного властелина и... все. Тут технических статей просто нет. Есть коментарии.
Cтатья может быть полезна для кандидатов.
Да. Особенно, если они идут к вам. Разные видения кандитатов у разных интервьюверов. Мне все равно что кандидат читал или не читал, где и сколько работал. Мне важно что он понимает, что конкретно он делал на проекте, что он понимает как работает инструмент c которым он работал и зачем вообще проект существовал.
Ну так просмотрщики, не редакторы-же. Автор рассматривает редакторы общего назначения, что на мой взляд не верно. Если лог такой маленький что лезет в редактор, так и смотрите его FAR'ом или абсолютно любым другим редактором. А то начинается "долго стартует", "не может загрузить" и т.д. :)
Вообще говоря автор занался откровенно не тем. Вот смотрите: логи большие, по-этому открывать их именно в редакторах - это использовать редактор не по назначению. От этого и проблемы типа "файл слишком большой" и "долго открывается". Для просмотра надо пользоваться (неожиданно!) просмотрщиком. Он не грузит файл в память и открывает все мгновенно. Однако лог - информация структурированая. И использовать просто просмотрщик - это терять структуру. Просмотр части лога - это занятие от безисходности, когда нормальные инструменты помочь не могут.
Какие нормальные? Это конечно-же индексаторы логов - Splunk, ElasticSearch и что там еще появилось. В Splunk можно писать довольно сложные запросы, которые сделают всю работу за вас - нечего глаза на логах ломать. Это вам не grep! Это нормальный язык работы с именно логами. Если Splunk'у помочь и немного разметить сообщения (я не люблю логи в Json - я все еще иногда их глазами читаю), то он может выделять значения, агрегировать, строить условия. И на худой конец можно посмотреть кусок сырого лога выше/ниже выбранной строки. А еще он агрегирует логи со многих машин и можно следить за распределенными транзакциями.
Проблемы пустого ответа просто нет! Тут решается абсолютно искусственная, надуманая проблема. Вот смотрите: в статье постулируется как данность что 1) эндпоинты с одним методом распространены на столько, что вообще заслуживают внимания 2) что для эндпоинтов нужен базовый класс/интерфейс. Оба утверждения на мой взгляд неверны. Эндпоинтов с одним методом исчезающе мало и ежели таковые все-же распространены в приложении для них вообще не надо ничего базового, как и для всех остальных. Чего плохого в стандартном, рекомендуемом методе (просто отрастить от ControllerBase)? Помнить как называется класс для пустого возвращаемого значения надо только при использовании данной библиотеки. Т.е. проблема искусственно создана и успешно решается.
Кроме того даже если принять положения статьи - однометодовые эндпоинты реализуются сильно по-разному. Возвращаемое значение может быть как сам класс так и Task<Result>, ActionResult, ActionResult<Result> и т.д. Даже если библиотека все это поддерживает, то полезность ее как-бы размывается.
До кучи. У методов эндпоинта есть атрибуты. Библиотека тут не поможет (ну и не помешает конечно). А именно в атрибутах все веселье - авторизация, методы, собственно путь...
А что не так с public abstract?
Не так с ним то, что он вообще есть. В чем его смысл? Дать по рукам джуну, чтоб писал как все? Ну а как ему надо видео стрим вернуть или еще чего сподвыподвертом?
Не знаю... мне кажется в данном случае лучше быть проще и вообще не использовать тулы типа предлагаемого.
Именно! Builder - бельмо в глазу. И исполльзуется он ровно в одном месте - инициализация ASP.NET (Microsoft DI на самом деле) и более нигде! Это в Джаве он распространет, а в шарпе нет.
Как я сказал второе место - это LINQб но там реально новый язык введен. Со своими правилами оформления и очень ограниченым набором методов, которые к тому-же применимы к любым коллекциям, а не являются позиционными для определенных типов объектов.
Why are we removing password-expiration policies? [...] Periodic password expiration is an ancient and obsolete mitigation of very low value, and we don’t believe it’s worthwhile for our baseline to enforce any specific value. By removing it from our baseline rather than recommending a particular value or no expiration, organizations can choose whatever best suits their perceived needs without contradicting our guidance. At the same time, we must reiterate that we strongly recommend additional protections even though they cannot be expressed in our baselines.
В рамках микросервисов есть OpenAPI - там и код и документация в одном. Я к тому, что даже если вы доку написали один раз ее потом всю жизнь надо поддерживать. У вас есть на это бюджет, желание и ресурсы? Если нет, то выход один - код лучшая документация (@ValeryGL). Просто не надо разделять их. Отдельная документация устаревает в момент сохранения файла (а то и раньше). В итоге дока как-бы есть, но ее как бы и нет. По этому только доко-генерация (которую можно и не делать) и редкие статейки на вики, которое никто не читает :)
А вот по отоплению как раз есть. Только работает для батарей с регуляторами и внутриквартирным бойлером. Идея в том, что на каждой батарее стоят умные вентили с датчиком температуры воздуха (да, они греются от батареи, но как-то работают причем достаточно точно) и блок управления бойлером. Блок может работать или по цифровому протоколу, если бойлер поддерживает, или просто вкл/выкл - это любой бойлер может. Идея в том что любой датчик может сказать или "я-бы погрелся, если еще кто-то мерзнет" или "мне совсем холодно - включайся, чан железный". При этом если в комнате тепло, то датчики отключают батарею в этой комнате. Получается экономно и реально работает. Есть коммерческие системы. Например Tado.
А ваш комментарий только подтверждает мой :) Есть всего два способа работы с прото - proto first когда вы генерируете исходник по proto и code first когда соотвественно наоборот. Если код генерится по прото, то я ожидаю что когда я тыкну F12 в студии она покажет мне прото. Ан нет она показывает сгенерированый класс, который читать разумеется невозможно. Проблема это среды или прото? А какая разница? Это в любом случае моя проблема.
Как раз по ним! В простом случае вообще без аннотаций, а в пределе с аннотациями включающими ID. Proto как такового не создается, но gRPC сервер отдает описание нормально. Генерировать прото по исходника супер удобно и если у вас моно репа/один язык, то смысла писать прото отдельно достаточно мало.
А проблемы есть например между Java и C# - Java сервер не любит отсутствие обязательных полей. Таки да, это проблема что C# клиент не проверяет при отправке что не все заполнено, но какая разница? Видно это только в рантайме.
А можно поинтересоваться - зачем вам вся эта макулатура? Что есть конечная цель? Ну вот допустим у вас на руках большой проект. В нем 100500 sequence diagrams, описана схема данных (а так ее что не видно через FK в SQL базах или по связям в ORM?) и все такое. Что теперь вы будете с этим делать и что будут делать другие? Давайте оставим за скобками проблемы аудита. Нужна документация программистам? Они будут ее читать? Не джуны, а все остальные. Если не будут, то скорее всего она вам и не нужна. Я ничего не скажу про аналитиков - им надо - вот и пусть пишут и поддерживают. Мне кажется, что единственная документация - это код и все что из него можно сгенерировать. Все остальное или не нужно или устарело.
Proto создает либо огромные проблемы с читаемостью (goto definition показывает сгенерированный класс, который читать невозможно) либо проблемы с межьязыкоровой совместимостью когда proto создается динамически по исходникам. Он конечно быстрый и все такое, но неудобный.
Я в 90х начинал с графовой (сетевой) базы. Достоинства там - нет поиска (в том смысле что искать по базе не надо вообще - на все и так есть указатели), размер гораздо меньше реляционных. Но недостаток все перевешивает - все запросы к базе фактически зашиты в ее структуру. Может сейчас чего и придумали, но тогда поддерживать ее был сущий ад.
Это, кстати, единственно верная методология.
А про статью чтоб два раза не вставать - у таски для разработчика есть всего два состояния - "никто не смотрит" и "сделано". Если появляется "в работе" значит или декомпозиция сделана неправильно (задача слишком большая) или бюрократы захватили планету (по-моему это как раз вариант из статьи). Когда у таски есть готова к тестированию, готова к мерджу, смерджена... мне это напоминает сцену из фильма "Космические М...звоны" (он-же Космические Яйца):
- "Приготовиться к перометке вперед!"
- "Есть приготовиться к перемотке вперед!"
- "Перемотка вперед!"
- "Есть перемотка вперед!"
Это они так видео перематывали :) Посмотрите на диаграмму "работа с историей" и поплачьте. Как-то проще надо быть.
"Ио-хо-хо" - это у пиратов :) У Санты "Хо Хо Хо!"
Конфигурация Кубера - аццкий ад. Вместо просто тупо UI предлагается выучить как писать связанную (!) конфигурацию в текстовом редакторе без всякой поддержки. Предлагается пользоваться командной строкой для управдения, редактирования конфигурации и мониторинга. Открою вам тайну, граждане, kubectl не для людей. Он для приложений, которые по-идее должны обеспечивать UI. Да UI обертки есть, но не из коробки и ооочень далекие от WYSIWYG. Я что-то не знаю ни одной, где-бы в один прекрасный момент не появился-бы диалог редактирования Yaml.
Связь между объектами... в текстовых файлах... редактировать руками... Ну да, ну да. Ошибся в labels - нет ошибок, но ничего не работает. Ой, а тут имя секрета надо... а оно относится к внутренним secret store Kubernetes или к секретам GKE импортированным через внешние secret storage? И много-много такого-же.
Отдельные лучи ненависти Gateway/VirtualService - если не работает логов нет, если вы не админ всея кластера. А я не админ! Я админ в своем неймспейсе, и даже default не вижу.
А дальше больше если у вас не один жалкий вэб сервачок (пусть даже масштабирующийся на 100500 инстансов) а меш микросервисов. Руками-ж каждый писать неохота - слишком одинаковые. Ну так helm/tanka в помощь. А вот теперь скажите почему 1) опять свзязь между объектами руками 2) для темплейтов выбран самый извращенный, самый нечитаемый, самый никому неизвестный язык разметки?
Вобщем извините, если кого за живое задел, но накипело. Как будто и небыло тех 20-30 лет развития UI/UX и мы опять вернулись во времена начала CP/M / IBM360 / PDP11
Отлично. Теперь вместо жесткой гарантии получения данных мы получили слабое связывание и отстутствие гарантий вообще. Для страничек в интернете - прекрасно. Для финансовой системы немедленная смерть. (Да есть паттерны типа event sourcing, но они настолько сложны в разработке... и избыточны в большенстве случаев)
Вот пример - синий сервис требует данные фиолетового и они на pub/sub. От фиолетового ничего не пришло. Это он лежит? Это ничего не случислось? Или еще: все то-же самое, но от фиолетового пришло. Ура? А это точно последние данные? Ах там таймстамп-же есть? Ну и что - обновиться через милисекунду оно все равно могло.
Вот и получаются гибридные pub/sub и request/response. А там не только все плюсы, но и все минусы обоих.
Нет счастья. Надо думать над каждой связью.
"Мышки, станьте ёжиками"
Для интраверта контакты не необходимое зло, а ужас и отвращение. Интроверт искренне непонимает зачем, а главное нафига ему этот весь нетворкинг. При отсутствии мотивации к каким-либо контактам о каких советах идет речь?
Automapper просто не работает при количестве объектов в несколько тысяч. Ну как не работает... добавляет 2 минуты к старту системы. Не верю в мепперы как класс.
Чего так привязались к прочтенным книгам-то? Я перестал их читать, когда понял, что все новые мысли от 100-страничной книги можно обычно прочитать в оглавлении по пути домой, понять о чем книга и распознаьть, что ты этим уже много лет как пользуешься. Я конечно не аналитик, но все-же...
Вспомнить статью на Хабре? Смеетесь? Я помню пришествие чОрного властелина и... все. Тут технических статей просто нет. Есть коментарии.
Да. Особенно, если они идут к вам. Разные видения кандитатов у разных интервьюверов. Мне все равно что кандидат читал или не читал, где и сколько работал. Мне важно что он понимает, что конкретно он делал на проекте, что он понимает как работает инструмент c которым он работал и зачем вообще проект существовал.
Это не критика статьи даже, а так наблюдение.
Ну так просмотрщики, не редакторы-же. Автор рассматривает редакторы общего назначения, что на мой взляд не верно. Если лог такой маленький что лезет в редактор, так и смотрите его FAR'ом или абсолютно любым другим редактором. А то начинается "долго стартует", "не может загрузить" и т.д. :)
Ну не знаю. У меня нескольго гигабайт ротируемых логов с примерно 20 хостов и по 7-8 сервисов на каждом. Что тут ПКМ->Открыть?
Вообще говоря автор занался откровенно не тем. Вот смотрите: логи большие, по-этому открывать их именно в редакторах - это использовать редактор не по назначению. От этого и проблемы типа "файл слишком большой" и "долго открывается". Для просмотра надо пользоваться (неожиданно!) просмотрщиком. Он не грузит файл в память и открывает все мгновенно. Однако лог - информация структурированая. И использовать просто просмотрщик - это терять структуру. Просмотр части лога - это занятие от безисходности, когда нормальные инструменты помочь не могут.
Какие нормальные? Это конечно-же индексаторы логов - Splunk, ElasticSearch и что там еще появилось. В Splunk можно писать довольно сложные запросы, которые сделают всю работу за вас - нечего глаза на логах ломать. Это вам не grep! Это нормальный язык работы с именно логами. Если Splunk'у помочь и немного разметить сообщения (я не люблю логи в Json - я все еще иногда их глазами читаю), то он может выделять значения, агрегировать, строить условия. И на худой конец можно посмотреть кусок сырого лога выше/ниже выбранной строки. А еще он агрегирует логи со многих машин и можно следить за распределенными транзакциями.
Читать логи редактором? Фу!
Проблемы пустого ответа просто нет! Тут решается абсолютно искусственная, надуманая проблема. Вот смотрите: в статье постулируется как данность что 1) эндпоинты с одним методом распространены на столько, что вообще заслуживают внимания 2) что для эндпоинтов нужен базовый класс/интерфейс. Оба утверждения на мой взгляд неверны. Эндпоинтов с одним методом исчезающе мало и ежели таковые все-же распространены в приложении для них вообще не надо ничего базового, как и для всех остальных. Чего плохого в стандартном, рекомендуемом методе (просто отрастить от ControllerBase)? Помнить как называется класс для пустого возвращаемого значения надо только при использовании данной библиотеки. Т.е. проблема искусственно создана и успешно решается.
Кроме того даже если принять положения статьи - однометодовые эндпоинты реализуются сильно по-разному. Возвращаемое значение может быть как сам класс так и Task<Result>, ActionResult, ActionResult<Result> и т.д. Даже если библиотека все это поддерживает, то полезность ее как-бы размывается.
До кучи. У методов эндпоинта есть атрибуты. Библиотека тут не поможет (ну и не помешает конечно). А именно в атрибутах все веселье - авторизация, методы, собственно путь...
Не так с ним то, что он вообще есть. В чем его смысл? Дать по рукам джуну, чтоб писал как все? Ну а как ему надо видео стрим вернуть или еще чего сподвыподвертом?
Не знаю... мне кажется в данном случае лучше быть проще и вообще не использовать тулы типа предлагаемого.
Именно! Builder - бельмо в глазу. И исполльзуется он ровно в одном месте - инициализация ASP.NET (Microsoft DI на самом деле) и более нигде! Это в Джаве он распространет, а в шарпе нет.
Как я сказал второе место - это LINQб но там реально новый язык введен. Со своими правилами оформления и очень ограниченым набором методов, которые к тому-же применимы к любым коллекциям, а не являются позиционными для определенных типов объектов.
Регулярно меняйте пароль? Ну ну. https://docs.microsoft.com/en-us/archive/blogs/secguide/security-baseline-final-for-windows-10-v1903-and-windows-server-v1903
Вот и я про то-же. По-моему вот так оно выглядит лучше и читается проще: