IT + Java

• Описание конечных точек (эндпойнтов).

• Форматы запросов и ответов.

• Методы аутентификации.

• Обработку ошибок.

• Примеры использования.

Представляем подборку лучших инструментов для создания API-документации.

Swagger

Swagger – один из самых популярных инструментов: он поддерживает много языков программирования и предоставляет удобный интерфейс для проектирования и документирования API. Swagger позволяет определять конечные точки, форматы запросов и ответов, а также методы аутентификации. Кроме того, он предоставляет интерактивные инструменты для исследования и тестирования API.

Apidog

Apidog – комплексный инструмент для разработки, документирования и управления API. Он предлагает автоматическую генерацию интерактивной документации и возможность тестирования API в реальном времени. Apidog также поддерживает генерацию кода на разных языках программирования и предоставляет широкие возможности для настройки стиля документации.

ReDoc

ReDoc – опенсорсный инструмент, поддерживающий спецификации OpenAPI 2.0 и 3.0. Он отлично подходит для публикации интерактивной API-документации и предлагает удобную навигацию с настраиваемым поиском, а также стильный, адаптивный дизайн с возможностью настройки тем.

DapperDox

DapperDox – опенсорсный OpenAPI-рендерер, совместимый с OAS 2.0 и 3.0. Он позволяет использовать контент в формате Markdown для создания диаграмм и предоставляет модуль исследования структуры API для практических экспериментов.

Theneo

Theneo – генератор документации, использующий ИИ для автоматического описания API. У него простой интерфейс, напоминающий Notion, и он поддерживает интеграции с Swagger, Postman и GitHub.

Sphinx

Sphinx – мощный генератор документации, широко используемый в Python-сообществе. Он поддерживает много языков и предлагает широкие возможности для настройки. Sphinx может генерировать документацию в разных форматах, включая HTML, PDF и ePub.

Javadoc

Javadoc специально разработан для документирования Java-кода. Он извлекает комментарии и аннотации из исходного кода для создания HTML-документации с подробным описанием классов, методов и полей.

DocFX

DocFX – генератор статических сайтов, разработанный Microsoft и с ноября 2022 года поддерживаемый сообществом .NET Foundation. Предлагает настраиваемые шаблоны для создания документации и лендингов.

Doxygen

Doxygen поддерживает C++, С, Objective-C, Python, Java, IDL, PHP, C# и Fortran, может генерировать документацию в разных форматах, включая HTML, PDF и LaTeX.

Slate

Slate фокусируется на простоте и удобстве использования, предоставляя удобный, современный, адаптивный интерфейс для API-документации. Он поддерживает Markdown, подсвечивает синтаксис больше 100 языков и предлагает интерактивную консоль для тестирования API-эндпойнтов.

Docusaurus

Docusaurus предназначен для создания современной интерактивной документации и любых других статических сайтов. Он поддерживает все популярные языки, предлагает настраиваемые шаблоны, имеет встроенную функцию поиска на базе Algolia, поддержку локализации и версионирования.

Приглашаем вас на вебинар «Как меняется математика в разных индустриях: от мобильных игр к фондовым рынкам», который состоится 22 августа в 20:00 по МСК. Там вы сможете:

• Узнать, как математические методы влияют на мобильные игры и фондовые рынки.

• Понять различия в математических подходах в разных сферах бизнеса.

• Изучить реальные кейсы применения математики в GameDev и финансах.

• Оценить, какие математические знания необходимы для успешной карьеры в Data Science.

Стать участником вебинара

😎 Автоматизация слепых SQL-инъекций на основе логических значений

Слепая SQL-инъекция на основе логического значения (Boolean-Based Blind SQL Injection) – тип SQL-инъекции, где атакующий не видит прямого вывода SQL-запроса, но может делать выводы на основе логических (истина/ложь) ответов от приложения (эти ответы могут проявляться в виде разных кодов состояния HTTP, разного содержимого ответа или реже разных заголовков).

Анализ ответов позволяет злоумышленникам определить структуру базы данных, а в дальнейшем – буквально символ за символом выяснить, какая информация в ней содержится. Пентестеры и этичные хакеры знают, что это один из самых трудоемких типов атак для ручной эксплуатации. Но несколько простых Python-скриптов помогают полностью автоматизировать процесс:

• Простейший метод – извлекать данные по одному символу, используя функции SUBSTRING() и ASCII() в MySQL. Это позволяет узнавать значение каждого символа в строке путем сравнения с ASCII-кодами.

• Оптимизированный подход – использовать алгоритм бинарного поиска. Это сокращает количество запросов для определения одного символа с 96 до 7, что значительно ускоряет процесс и делает атаку менее заметной.

• Дополнительные приемы для извлечения разных типов данных включают использование подзапросов для выбора данных из произвольных таблиц, объединение значений из нескольких строк в одну строку с помощью GROUP_CONCAT и преобразование разных типов данных (числа, даты и т. д.) в строки, которые легче извлечь.

Для дальнейшего ускорения процесса можно использовать многопоточность с помощью ThreadPoolExecutor из библиотеки concurrent.futures.

📶 Паттерны коммуникации в распределенных системах

Распределенные системы состоят из многих отдельных частей (или узлов), работающих вместе, но физически расположенных в разных местах. Эти части системы должны общаться друг с другом через сеть, чтобы система могла функционировать как единое целое. Хотя коммуникация критически важна, правильно ее организовать бывает непросто: разработчики иногда пытаются использовать один и тот же подход ко всем задачам коммуникации, что может быть неэффективно. Важно понимать, что существуют разные способы организации коммуникации, и выбор правильного метода зависит от конкретной задачи. Рассмотрим основные паттерны коммуникации, которые можно использовать для решения разных задач.

Запрос-ответ с HTTP

Этот синхронный паттерн коммуникации предполагает, что один сервис отправляет запрос другому сервису и ожидает ответа или ошибки, блокируя свою работу до получения результата. REST, наиболее популярный архитектурный стиль для этой модели коммуникации, использует методы протокола HTTP – GET, POST, PUT и DELETE.

Однако использование этого паттерна может привести к проблемам, если сервисы образуют цепочку взаимодействий: в таком случае сбой одного из сервисов может привести к отказу всей операции, а также к расточительному использованию ресурсов и каскадным сбоям.

Общие данные

Этот паттерн часто остается незамеченным, поскольку разработчики не всегда воспринимают его как модель коммуникации. В рамках этого подхода один компонент записывает данные в определенное место, а другой компонент считывает и обрабатывает эти данные. Например, один сервис может загрузить файл в облачное объектное хранилище (например, в корзину Amazon S3), а другой сервис затем извлекает этот файл для дальнейших действий.

Главное преимущество этого паттерна – простота реализации и возможность обеспечения взаимодействия между устаревшими и современными системами без проблем совместимости. Однако он не подходит для сценариев, требующих низкой задержки.

Асинхронный запрос-ответ

В отличие от синхронного подхода, запрос-ответ может быть реализован асинхронно и без блокировки. В этом случае получающий сервис должен явно знать место назначения для отправки ответа. Для реализации этого паттерна идеально подходят очереди сообщений, которые позволяют буферизовать несколько запросов.

Основная сложность здесь — корреляция между запросом и ответом: экземпляр сервиса, отправивший запрос, может отличаться от экземпляра, получающего ответ, поэтому требуется способ отслеживания запросов.

Коммуникация на основе событий

В этом подходе сервисы не общаются напрямую друг с другом, а генерируют события, которые могут быть использованы другими сервисами. Это требует наличия места для отправки данных о событиях и механизма, позволяющего получающим сервисам обнаруживать эти события. Брокеры сообщений, такие как RabbitMQ, могут обрабатывать оба этих аспекта. Издатели используют API для отправки событий в брокер, который управляет подписками и уведомляет подписчиков при поступлении события.

Этот паттерн идеально подходит для создания слабосвязанных взаимодействий между сервисами. Однако брокер сообщений должен обеспечивать надежную доставку событий, их упорядочивание и согласованность. Кроме того, добавляется дополнительный компонент в систему.

🛠️ Инструменты

Postgres Sandbox – ИИ-песочница для работы с PostgreSQL в браузере. Проект реализован на PGlite – легковесной версии PostgreSQL, скомпилированной в WebAssembly и упакованной в клиентскую библиотеку TypeScript. Это позволяет запускать базу данных PostgreSQL непосредственно в браузере, Node.js и Bun без необходимости устанавливать другие зависимости. Размер PGLite – всего 3 Мб после сжатия Gzip, при этом база поддерживает многие расширения PostgreSQL, включая pgvector.

textual-plotext – виджет-обертка библиотеки для построения графиков Plotext. Визуализирует данные из Python-скриптов прямо в терминале.

BunkerWeb – опенсорсный веб-фаервол (WAF), созданный на основе NGINX. Предназначен для защиты веб-сервисов – делает их безопасными по умолчанию. Легко интегрируется в существующие среды (Linux, Docker, Swarm, Kubernetes и т. д.), полностью адаптируется под ваши специфические требования. Предоставляет удобный веб-интерфейс и систему плагинов.

Kardinal – фреймворк для создания сверхлегких временных сред разработки внутри общего кластера Kubernetes. Позволяет быстро и эффективно создавать и удалять рабочие пространства для разработки, тестирования и демонстраций, минимизируя затраты ресурсов и стоимость эксплуатации.

Viking – инструмент для управления удаленными серверами (и группами серверов) через SSH.

Terminus – опенсорсная ОС на базе Kubernetes, которая позволяет создать домашнее облако на собственном сервере. Подходит для любых задач – локального хостинга LLM, хаба по управлению IoT-девайсами, персонального репозитория или рабочего пространства.

DeltaDB – легковесная, быстрая и масштабируемая база данных, созданная на основе polars и deltalake. Предназначена для разработчиков и организаций, которым нужно эффективное, простое и гибкое решение для обработки больших объемов данных с высокой скоростью и масштабируемостью.

emval – супербыстрый валидатор email-адресов для Python-приложений, написанный на Rust.

RustPython – интерпретатор Python, написанный на Rust.

Автор рассылки: Наталья Кайда

Второй Java-проект (тот который я переписал на PHP) был призван выводить операторам номера должников. Основная его фича заключалась в том, чтобы показывать каждому оператору свой набор абонентов. Соответственно будет ошибкой показывать двум операторам одного клиента. Ну, и тех клиентов, с которыми состоялся разговор тоже не следует отображать. Оператор видел список, звонил по порядку и проставлял статусы. С этим и происходила беда, иногда операторам выпадали номера, по которым уже звонили недавно. Причем могли выпасть другому оператору в тот же день. Эта проблему, как я понял на тот момент, заключалась как раз в сервере tomcat6, а именно был какой-то баг с потоками.

Код проекта архивировался, этот архив скармливался томкету, он его компилировал и запускал. То что он делал внутри себя с запросами я выяснить был не в состоянии. Поэтому сначала была попытка обновить tomcat до седьмой версии.

После обновления наступило "затишье", операторы перестали жаловаться. Точнее раньше приходил их старший менеджер и сообщал о проблеме (но что именно не так и какие действия совершались она сама не могла поведать). Но как оказалось это было случайностью. Или может просто рестарт приложения "чинил" временно проблему, а рестарт после обновления тоже происходил, что логично. Только не мог же я рестартовать приложение как магическое решение. Да и не факт, что это железно могло помочь.

Как-то в очередной раз пришла старшая оператор и прямо-таки психнула. По сути она опять ничего мне толком не сказала, но когда я сказал что быстро починить не удастся, то пообещала, что так мне это с рук не сойдет. До нее был другой менеджер, который тоже приходил с проблемами, но так как от меня толку не было, то через неделю он уволился. По крайней мере вижу свою вину в этом, потому что кого-кого, а менеджеров "босс" прессовал за любую мелочь. То есть раз я не мог помочь ему, он не мог решить проблему, и под давлением "босса" пришлось уволиться.

После того как проект был переписан произошла какая-то дичь. Проблемы с потоками и выводом повторных абонентов по идее не должно быть. И все же меня вызвали "на ковер" к "боссу", и там уже была эта "мадам". Она указала перстом на меня и говорит "его спрашивайте". А "босс" такой - "так это ты во всем виноват?". Максимально непонятно что у них там происходило до того как я вошел, и какая проблема случилась, но естественно я подумал что где-то допустил ошибку.

Загвоздка в том, что впоследствии я ее не нашел. Для выяснения ходил в офис к девочкам-операторам, смотрел как у них всех отображается, как все работает, перепроверял код и не нашел ошибок. Неделю я все это выяснял, и за это время не изменил ни строчки кода в этом проекте. Как назло все работало и никаких багов не было. Параллельно я уже начал искать новую работу, и получается эта неделя была последней. Всего в этой компании мне довелось проработать четыре месяца.

После ухода из той компании провайдера я заходил периодически на страницу проекта, чтобы проверить не поменялось ли чего. Через три месяца обнаружил, что код обратно вернулся на Java-версию. Это было очевидно, потому что изначально сайт был по SPA-технологии, то есть после выполнения запроса обновление страницы было без перезагрузки этой самой страницы. Я же переписал на PHP по технологии SSR, только в некоторых местах был добавлен AJAX. Страница входа точно была с перезагрузкой, даже если просто выводилась ошибка входа. Кроме того, закрыли доступ или удалили аккаунт и я больше не мог входить внутрь ЛК оператора.

Как вишенка на торте выкладываю переписку (с вырезанными персональными данными) с java-программистом, когда передавался проект, чтобы можно было погрузиться в атмосферу тех событий.

Дальше я неделю приходил на работу, где мне не давали никаких задач, я просто изучал проект и заодно азы Java. Познавал до набухания мозга что такое есть сервлет, зачем нужен TomCat и прочие явошные дела. Что-то у меня даже получалось, но это было копирование имеющегося кода с незначительными изменениями.

Наконец, менеджеры, которые работали с этим веб-приложением начали приходить с текущими проблемами. Видимо, решили что уже пора. Я их проблемы решить не мог, потому что там происходила непонятная магия с потоками. Предыдущий программист, с которым переписывались по скайпу, в этом деле не мог ничего подсказать, по всей видимости тоже не знал.

В итоге когда мозг совсем набух от влитых знаний, я принял самостоятельное волевое решение переписать проект на PHP, о котором никому не сообщил и принялся за переделку. На мой взгляд этот личный кабинет был очень простой и делать его на Java было неправильным решением. Я так понял, что тот, кто этим занимался, просто знал Java и ему было так удобно сделать. А то, что найти специалистов на замену будет сложновато как-то никто не думал. При этом я прибегнул к небольшой хитрости. Дело в том, что с этим проектом можно было работать только с ноутбука в офисе, во внутренней сети. Но я нашел лазейку, и отключил функцию засыпания ноутбука, когда крышка была закрыта. Уходя с работы, я просто закрывал крышку с незалоченным Windows, а из дома подключался к нему через удаленный рабочий стол и работал. Так я не был зависим только от рабочего времени и писал код вечером и ночью. Я только беспокоился на тему того, что кто-то надумает посмотреть что в ноуте в этом время, но вроде ничего такого не было.

За две недели все было готово. Новое веб-приложение на PHP я выкатил ночью в выходные. В понедельник ко мне прибежали менеджеры с разными проблемами. Вполне логично, что не все было сделано хорошо и некоторую бизнес-логику я упустил. Зато теперь я мог все это чинить, потому что код был полностью мой и я понимал все что он делает, поэтому за неделю все горячие проблемы разрешились.

В этой схеме все выглядело более менее гладко, если бы не человеческий фактор. Кое-какие функции я за незнанием бизнес-логики сделал по-своему, а большинство багов исправил. И это повлияло на то, что отдел операторов стал некачественно выполнять свою работу. Точнее они могли скрывать раньше свои косяки, ссылаясь на баги программы, но когда я эти баги исправил (но никому не сказал) - они продолжили это делать. Тут и случились нестыковки, но это уже другая история...