×Закрыть

Як порозумітися бекендеру і фронтендеру, обираючи архітектуру

Понад 10 років я був веброзробником фронтенду та бекенду, тімлідом і техлідом у стартапах та продуктових компаніях, тому зі свого досвіду можу сказати, що ключовим в успішній реалізації проєктів для мене була ефективна комунікація та чітка документація у розподілених командах.

У матеріалі я сконцентруюся на технічній комунікації між бекенд- і фронтенд-розробниками, огляді архітектур, їхньому застосуванні для вирішення різних питань і, головне, на підходах та інструментах з документування інтерфейсів.

Мені часто доводилося починати проєкти, в яких не було жодної документації. Багато розробників вважає цей крок зайвим або ж таким, яким можна знехтувати в умовах стислих термінів на розробку. Проте майже кожен проєкт доходить до стадії стабілізації, релізу та підтримки, а кількість технічного боргу до цього моменту може за розмірами нагадувати ще один проєкт.

Тут маємо дві опції: або все переписати і просити людей працювати в понаднормовому режимі, щоб «гасити пожежі», або ж мати вичерпну документацію — пояснення, чому все працює таким чином, — і зберегти логіку проєкту та час розробників.

Ілюстрація Аліни Самолюк

Програмування за контрактом

Наразі найпопулярнішим підходом у програмуванні є командна крос-функціональна робота з вертикальною відповідальністю — за фічі, а не горизонтальною — за процеси. Відповідно кожен член команди є важливою частиною цілого і доволі складного організму.

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

Програмування за контрактом передбачає вичерпну документацію, яка є особливо потрібною у розробці з чітко розподіленими ролями бекенд- і фронтенд-розробників. Однак детальна документація є великим навантаженням і вимагає багато часу, якого завжди бракує.

Архітектура як основа комунікації

Під архітектурою ми розуміємо структуру директорій чи спосіб передачі даних у клієнт-серверній взаємодії. Ці тлумачення водночас правильні й не зовсім, тому що не повні.

Головне питання архітектури будь-якого проєкту полягає у створенні зв’язку між бізнес-потребами та технічними рішеннями. Іншими словами, архітектурне завдання полягає в тому, щоб перекласти ідею проєкту з мови бізнесу на мову технічну за допомогою абстракції та декомпозиції з урахуванням нефункціональних вимог. У такій інтерпретації треба враховувати їхню точність і детальність, як-от взаємодія між модулями чи компонентами системи.

Далі згадаємо кілька архітектурних патернів і підходів до організації взаємодії фронтенду та бекенду.

JSON-RPC

Remote Procedure Call (RPC) — один з найпростіших, проте від того не менш потужних інструментів для розробки клієнт-серверних застосунків. За основу JSON-RPC архітектури взятий найбільш природний спосіб комунікації — виклик функцій інтерфейсу за допомогою HTTP-протоколу.

З власного досвіду можу сказати, що для організації маленьких API, які концентруються навколо дій користувача, а не об’єктів бізнесу, або, як ще кажуть, об’єктів реального світу, ця архітектура підійде якнайкраще. Гарною передумовою для вибору цього методу є невеликий словник об’єктів і детермінована кількість дій над ними.

Також він вартий уваги, якщо потрібна розробка дизайну мікросервісної архітектури. Remote Procedure Call (RPC) для мікросервісів з правильною гранулярністю, які реалізують не лише CRUD-операції над об’єктами RPC, може вирішити питання словника і більш складних операцій, що виходять за стандартний набір.

Виникає питання, чому щось неможливо вкласти у CRUD-операції, тим паче, що тут маємо вузький діапазон для маніпуляцій. Але йдеться радше про оптимізацію кількості запитів, ніж про дизайн системи у поняттях об’єктів. До прикладу, в нас є канбан-дошка. Створюючи першу дошку, ми маємо розробити групу для користувачів, які будуть нею послуговуватися.

У CRUD-операціях це можливо зобразити у послідовності створення дошки, створення групи та зміни власника дошки, тобто з REST-підходом нам знадобиться три операції. У RPC-подібних системах ця операція може бути здійснена окремим запитом, який міститиме інформацію про нову дошку та групу користувачів.

RPC має прозорі переваги, але з архітектурного погляду складність виникає, коли з’являється потреба розширити систему додатковими функціями. Словник системи починає збільшуватися пропорційно до самої системи, виникає велика кількість нових процедур, що ускладнює її розробку та підтримку.

Застосування. Мікросервіси та немасштабні проєкти з невеликим словником об’єктів та детермінованою кількістю дій над ними.

➕ Найменша складність реалізації.

➖ Складність еволюції у разі зростання проєкту.

REST

Найбільш «упевненим» на сьогодні патерном є Representational State Transfer (REST). Він застосовується у більшості вебзастосунків і має низку переваг над RPC.

З практичного погляду можу сказати, що більшість проєктів у центрі системи мають об’єкти з простою взаємодією у вигляді CRUD-операцій, тож REST дає відповідний інструмент зображення цих об’єктів і роботи з ними.

З архітектурного погляду, а саме здатності до еволюції, REST має більший потенціал, ніж RPC, завдяки зрозумілій та чіткій семантиці дій над об’єктами, описаній у вигляді HTTP-методів. Іншими словами, цей підхід має більш ізольований рівень абстракції, гарно впливає на характеристики зв’язаності системи, а семантика запитів робить зрозумілою систему та інтерфейс навіть за відсутності документації.

Застосування. Моделювання та розробка застосунків із використанням об’єктів і CRUD-операціями над ними.

➕ Найбільш вживана архітектура на сьогодні. Побудована на основі можливостей НТТР-протоколу. Чітка і знайома семантика з іменниками та дієсловами.

➖ Не має нативного вирішення питання надлишкових чи недостатніх даних. Складність реалізації завдань, які не вкладаються в об’єктну модель.

GraphQL

Graph Query Language (GraphQL) — наймолодший патерн зі згаданих, який стрімко набуває популярності серед розробників. Ідея підходу з мовою запитів для Web API не є новою, прикладом такої є SQL-подібний інтерфейс Facebook (FQL).

GraphQL вже своєю назвою наштовхує на думку, що для обґрунтованого вибору цієї архітектури об’єкти, представлені в системі, повинні вкладатися у поняття «графа». Такий підхід є гарним рішенням для створення застосунків для соціальних мереж, які охоплюють велику кількість об’єктів зі щільною залежністю між ними.

GraphQL може виконувати функцію агрегаційного рівня між кількома API і цим об’єднувати їх під однією схемою. І, певно, це єдина архітектура, яка є самодокументованою, що значно економить час розробників.

Звучить привабливо, але GraphQL теж має проблеми, властиві архітектурі резолверів. Один з яскравих прикладів — це N+1 проблема, тобто неефективний підхід до роботи з базою даних, внаслідок якого виникає надмірна кількість запитів до одного і того ж об’єкта. Звісно, кожна проблема має вирішення, але треба бути готовим до таких ситуацій заздалегідь.

Застосування. Проєкти середнього і великого розміру з чіткою об’єктною моделлю та залежностями між об’єктами.

➕ Самодокументована схема даних, вбудована валідація. Можливість роботи з підписками. Конструювання запитів під потреби клієнта.

➖ Молода архітектура та ком’юніті навколо неї. Необхідність розв’язувати проблеми, властиві архітектурі резолверів. Складніша в розумінні за REST та RPC.

Документація як спосіб комунікації

Окрім знання патернів та їхнього правильного вибору, необхідно зважати на мову, зрозумілу клієнту. Тож кожен проєкт має мати свій транспарентний словник.

Комунікація між командою і замовником ведеться через безліч каналів: месенджери, конференції, документи, тікети у баг-трекерах і таск-менеджерах на кшталт Jira. Однак, якщо перейти на технічний рівень, зазвичай цього недостатньо. Технічна комунікація потребує більш структурованого і «сухого» підходу.

З власного досвіду знаю, якою великою є спокуса у маленькій команді знехтувати документацією і передавати всю необхідну інформацію — від деталей API до схем даних — особисто розробнику чи тестувальнику у звичайному месенджері або ж усно.

З часом збільшується кількість і складність деталей проєкту, команда. Кожному новому розробнику чи тестувальнику потрібно передавати одну і ту ж інформацію, що займає багато часу. Зі збільшенням функціональності проєкту з’являється потреба у регресійному тестуванні, іноді є важливими деталі, які вже ніхто не пам’ятає.

Отже, документація може у простий спосіб розв’язати питання передачі інформації новим розробникам і уникнути bus factor проєкту, який виникає при накопиченні знань в однієї людини. Які самі інструменти для документації я застосовував та їхнє порівняння, наводжу далі у статті.

Wiki, або Можливість для самостійних змін даних

Першим підходом, який спадає на думку, є наповнення простого текстового документа. Це важливий і гнучкий інструмент, адже структуру документації і її можливості ви визначаєте самостійно, залежно від потреби проєкту. Існує багато спеціалізованих редакторів, але головним недоліком цього підходу є необхідність постійно актуалізувати документацію вручну.

Попри те, що цей метод має вагомі недоліки, у більшості проєктів, з якими я мав справу, використовували саме його: деколи як основний, деколи як додатковий метод документування. Як і з усім іншим у сфері розробки, за свободу вибору формату документації та можливість робити з нею, що заманеться, доводиться платити зручністю у підтримці. Але вирішальним питанням, з моєї практики, стає можливість підлаштувати документацію одночасно під потреби розробки та клієнта і незалежність від сторонніх стандартів.

➕ Для використання plain text підходу буде достатньо домовитись про нотацію і формат даних. Є можливість використовувати будь-який текстовий редактор або систему бази знань.

➖ Постійно треба оновлювати документацію власноруч.

Postman

Цей потужний інструмент дає змогу створювати колекції із запитами, робити документацію API та використовувати її для автоматизації тестування. Також Postman дає можливість версіонувати колекції та поширювати у команді.

Функціонал Postman, безумовно, є ширшим, ніж у plain text, але він також не розв’язує питання зі своєчасним оновленням документації та колекцій, тобто залишається ризик неактуалізованої версії документації.

З власної практики можу сказати, що цей інструмент став одним з улюблених. І річ не в зручності інтерфейсу чи додаткових фічах, а в можливості інтегрувати процес тестування у розробку в найдоступніший спосіб. Справді, Postman я позиціонував би більше як інструмент для тестування API, ніж для документації, але не виключаючи останнього.

➕ Можливість автоматизованого тестування API, підтримка генерації документації.

➖ Необхідність підтримувати документацію та колекції в актуальному стані власноруч.

Swagger

Специфікація та інструмент для автоматизації документування, який має майже необмежену кількість можливостей для використання, генерації коду, перегляду документації, версіонування.

Цей інструмент можу назвати зробленим розробниками для розробників. Генерування документації з XDoc-коментарів є великою перевагою методу над першими двома підходами, оскільки, змінюючи код, ви можете одразу відредагувати застарілу документацію. Ця функція також спричинює дублювання інтерфейсу у коді та коментарях, тому потребує нашого контролю над актуалізацією документації.

Попри те, що OpenAPI є де-юре стандартом і видається найбільш серйозним інструментом з перелічених, на практиці його застосування розробники розглядають під кутом автоматизованої генерації коду та найменшого опору в документуванні. Проте автоматична генерація коду не завжди є оптимальною, саме тому більшість проєктів відмовляється від використання цього підходу. [TB3]

Є і деякі практичні переваги в OpenAPI, зокрема можливість використання їх у Postman, але все-таки, обравши цей шлях, ви будете обмежені у можливості вийти за межі специфікації.

➕ Документація змінюється разом з кодом, який сприяє її оновленню.

➖ Велика кількість дубльованої інформації в коді. Необхідність підтримувати актуальність документації власноруч.

GraphQL

Однією з найбільших переваг архітектури GraphQL у контексті взаємодії між розробкою і використанням API є самодокументування. Опис структур даних у лексиконі GraphQL є її основою. Отже, обираючи цей метод, ми отримуємо інфраструктуру навколо GraphQL, а саме сервер і клієнт Apollo чи будь-які інші реалізації, генерацію коду з документації та вбудовану перевірку схеми запиту.

Деякі проєкти роблять вибір на користь GraphQL саме тому, що код проєкту і є документацією, але треба зважати на те, що ця документація більш технічна. Тобто, якщо нагальна потреба у документації полягає лише у комунікації між розробниками, це «золоте руно», але якщо є необхідність у передачі цієї документації кінцевим користувачам або клієнту — все-таки ви не уникнете написання умовного Wiki.

➕ Код і є документацією. Автоматична перевірка коректності запиту.

➖ Прив’язка до обраної архітектури.

Висновки

У виборі інструментів, архітектурних підходів і комунікацій важливий контекст. Архітектура, як і документація, — не мета, а інструмент для вирішення завдань проєкту. Не існує срібної кулі для розв’язання всіх можливих питань усіх проєктів. Завжди потрібно робити вибір, часом компромісний, між метою проєкту, складністю бізнес-вимог, нефункціональними вимогами до продукту, питаннями комунікації в команді.

Попри те, що вибір архітектурних складових проєкту без контексту є вибором заради вибору, як на мене, під час вирішення, яким шляхом піти, «найменшим злом» буде відштовхуватись від REST API. Якщо під час формалізації вимог зрозумієте, що у вас невелика аплікація, завжди зможете розглянути застосування RPC-like підходу. І навпаки: якщо щільність зв’язків між об’єктами у системі велика і розробка запитів під усі можливі кейси фронтенду може внести багато хаосу, час подивитися у бік GraphQL.

З документуванням проєкту трохи інакше, тому що до сьогодні Wiki-системи та їхні аналоги займають почесне місце. І справді, якщо придивитись до більшості проєктів чи то комерційних, чи то open source — їхня документація має довільний формат, у якому можна якнайкраще донести думку. Звісно, якщо ви не маєте потреби в публічній документації для розробки, таких інструментів, як Swagger у випадку REST або RPC чи GraphQL зі своїми схемами, буде більш ніж достатньо.

👍НравитсяПонравилось2
В избранноеВ избранном3
Подписаться на автора
LinkedIn

Похожие статьи




Підписуйтесь: SoundCloud | Google Podcast | YouTube

23 комментария

Подписаться на комментарииОтписаться от комментариев Комментарии могут оставлять только пользователи с подтвержденными аккаунтами.

думаю, поєднувати опис типів міжпроцесного обміну і документування в одній невеличкій статті не було вдалою ідеєю.
то все заради GraphQL?
і, до речі, дуже дивне визначення архітектури як на мене.

Складність реалізації завдань, які не вкладаються в об’єктну модель.

Никогда не понимал этого пункта и почему у людей это вызывает какие-либо «сложности».
Любой процесс, задача — точно такой же объект как и все остальное, просто он может менять на сервере свое состояние вне зависимости от действия/бездействия спрашивающего.

Як порозумітися бекендеру і фронтендеру, обираючи архітектуру

бути фулстек

Просто не пишіть окремий фронтенд і не треба буде нічого передавати.

Для відображання даних є шаблони та рендерінг на сервері.

Договариваться надо быстро и без конфликтов. Всё равно потом переделывать!

С каких это пор протокол обмена стал архитектурой?

Наймати фулстекерів і не паритися)

Где два фуллстека — там три контракта между беком и фронтом

але GraphQL теж має проблеми, властиві архітектурі резолверів. Один з яскравих прикладів — це N+1 проблема, тобто неефективний підхід до роботи з базою даних, внаслідок якого виникає надмірна кількість запитів до одного і того ж об’єкта.

тому ми дивились-дивились на GraphQL, і бек і фронт — та й відмовились на користь свого тлумачення REST. з field, include, extra та mode та контекстними "where-join"ами для нашого домену

вийшло що отримавши такий запит — можна створити простенький план формування відповіді, та оптимально звертатится до БД
та й кеш частини інфи зробити — теж.

Необхідність підтримувати актуальність документації власноруч.

так, це проблема.
особливо коли програмісти відкладають на потім внесення змін в неї разом з змінами у коді.

Здається потрібно перефразувати 10 правило Грінспена: Any sufficiently complicated REST API contains ad hoc, informally-specified, bug-ridden, slow implementation of half of GraphQL.

ну да.
это проще, и быстрее.
и фронту и беку — заточенный под домен бизнес протокол.

нужно ж понимать почему появился GraphQL:
огромное количество, в сравнении с типичным, проектов фронтенд приложенй. разнейших.
большое количество разнообразных персистентных хранилищ на беке. структура связи между которыми тоже меняется.

вот чтобы ускорить разработку, и никто никого не ломал и не ждал в FB — и сделали там. для себя.

если у вас сложности как у FB — потому что сопоставимая по размеру компания, конечно GraphQL

а если с пяток фронтендеров, с пяток бекендеров — то на кой решать проблемы которых у вас нет?

мы и прикинули — морока фронтендерам, морока бекендерам. ради чего?
а-а-а, модно, для распальцовки.
нужна нам была распальцовка? нет
как нам поможет GraphQL? никак.

а с пушки по воробьям да, пусть «академики» стреляют.
ну и доклад конечно можно запилить, и выступить
Как мы микроскопом научились гвозди забивать

будут овации, да.

GraphQL имеет смысл тогда, когда реально есть какие-то данные которые можно представить как граф. И/или данных много и/или их имеет смысл запрашивать выборочно (отдавать только те 3 филда что запросили, а не все 333 и отдавать только ту часть графа, которая была запрошена). Но это вполне может быть и масштаб меньше FB. Никакой это не микроскоп, а такой же молоток как 100500 варинтов написать REST на любом языке. Не понимаю, в чем его «модность», «академичность», «распальцовочность» и т.д.

Просто запихать существующий десяток эндопинтов как GQL филды — смысла уже может и не быть. Хотя, опять же, более или менее строгая система типов, существующий неплохой тулинг, типа graphiql UI, интроспекция, валидация запроса на стороне клиента и т.д. Так что будет и не хуже чем, скажем REST + swagger. По крайней мере не будет сюрпризов в виде — swagger написанный ручками + имплементация, которая с ним не совпадает.

swagger написанный ручками

Кто-то пишет OpenAPI спеку руками?.. Жесть.

GraphQL имеет смысл тогда, когда реально есть какие-то данные которые можно представить как граф.

мы не на собеседовании.

Есть теория, а есть практика.
за использование GraphQL как на фронте, так и на беке — нужно платить.
за все нужно платить. и за «REST» тоже.
вопрос только — сколько и за что.

особенно когда плюшки — бесполезные.
можно долго и много рассказывать бедуину о качестве вот этих горных лыж.
купит? или выберет водный мотоцикл?

Не понимаю, в чем его «модность», «академичность», «распальцовочность» и т.д.

в том что принято начитывать «лекцию» как ваш комент — а когда доходит до реального проекта — появляются нюансы. и весьма болезненные. когда стоимость превышает выгоды.

опять же, если бы эта боль была только нашей, то мы бы задумались.
но о ней много где и у кого можно прочитать.
просто это не модно — плохое говорить о модной или супер-бупер технологии, о ее недостатках. айти тусовка запишет за недоверие такое в ретрограды и рукожопы :)

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

а домен меняется редко. типовые операции тоже.

Хотя, опять же, более или менее строгая система типов, существующий неплохой тулинг, типа graphiql UI, интроспекция, валидация запроса на стороне клиента и т.д.

если это — главные проблемы у вас, то да, берите GraphQL.

у нас давно нет проблем ни с типизацией, ни с валидацией, и проблемы сооовсем другие.
и это было изначально понятно, что проблемы с «типизацией» и с «валидацией» — не проблемы вообще, на таких масштабах и размерах команды.
а баг в джире, и то иногда, и на первой части разработки, который фиксается максимум за пару часов.

тем более валидация на стороне клиента — какой в ней смысл, если валидацию надо обязательно писать на беке? причем такую, что на клиент никак не пробосить данные для нее, даже если бы захотели и на клиенте продублировать?

правило ж № 1 — ничему нельзя доверять что приходит с фронта.
и сразу становится все проще, оказывается достаточно согласовать показ ответа об ошибке пользователю, и все, и можно «валидацию на клиенте» можно опустить. а когда руки дойдут, добавить проверку корректности введенного «емайл» и на клиент. если — либы такой до сих пор не было :)

конечно, если у вас миллионы клиентов в одну секунду работают, то надо бы разгрузить бек от этого.
у нас миллионов одноментно не будет :)

Но это вполне может быть и масштаб меньше FB.

да, и бложик можно размазать на микросервисы
а смысл?
здесь тоже самое — технология призвана решить проблемы больших команд и компаний.
а мелким то она зачем? даже средним — уже надо смотреть. бывает что надо. но всегда ли?
зачем карьерным самосвалом пару мешков картошки возить?

какую проблему решает GraphQL?
в вашем коменте из полезных вижу только

swagger написанный ручками + имплементация, которая с ним не совпадает.

так мы swagger не используем, и не планируем. пробовали, с ним тоже оказалось — головняка больше чем пользы :)
для нас. но я отношу наш проект к средним по сложности, потому что несколько подобных стартовало за последние годы, и умерло не справившись с реализацией в приемлимый срок.

swagger нужен если API публичный. для неизвестно кого.
а если он только для нас и партнеров?

то есть и это было бы — бесполезной фичей. но которую надо оплачивать.

да, проблема с докой есть.
но что называется — а у кого ее нет :) не с той, так с другой.

Просто запихать существующий десяток эндопинтов как GQL филды — смысла уже может и не быть.

и для пары десятков эндопинтов (коллекций доменных объектов), даже на старте разработки, нужен ли он?

нужна гибкость GraphQL тогда, когда мы даже нафантазировать не можем, какие сценарии на UI работы с сущностями будут предоставлены завтра пользователю.
он очень гибкий — фронтендеры могут ничего не заказывать у бекендеров для разработки UI
а бекендеры не знать что там будет на UI.
и между ними — куча спек по доменным объектам.
удобно. для проектов которые пилят десятки команд с каждой стороны

GraphQL как и почти всякая другая технология решает не техническую проблему — а человеческую.
коммуникационную. а если ее нет, или она не самая острая, то и решать им нечего.

а платить — придется.

Какой-то культ GraphQL, прямо. И человеческие проблемы решает и карьерным самосвалом работает, надо проверить — может и мусор выносить будет :)? Хотя по сути — это просто немного другой способ передачи параметров в POST запрос. И проблемы в более или менее сложном домене от того REST там или GraphQL — это будет пару процентов от проблем, котрые решаются в самой проблемной области. Просто GraphQL дает чуть более высокий уровень абстракции, который на чем-то сложнее простого круда может забрать на себя часть вопросов типа валидации и т.д. по списку. Причем сделает это в соответствии со стандартом.

В любом случае, не вижу повода гнуть пальцы от того что был использован GraphQL. ... как и гнуть пальцы от того, что он не был использован. Не подошел — так не подошел.

Хотя по сути — это просто немного другой способ передачи параметров в POST запрос

по сути — это усложнение реализации на фронте и беке.

Просто GraphQL дает чуть более высокий уровень абстракции

да.
а за более высокий уровень абстракции — нужно платить
за более низкий — тоже, в другой валюте.

за все надо платить

Причем сделает это в соответствии со стандартом.

толку с этого стандарта, если нам надо работать — с доменными объектами, а не с байтами :)

и на беке, спускаться с «более высокого уровня абстракции» к реалиям упомянутого SELECT N+1.
которого, кстати, у FB тоже может и не быть, потому что данные собираются с разных хранилищ, которые часто не реляционные, а такие же графовые как и ответ.
Отличный кейс для применения GraphQL — у нас нет реляционных хранилищ, поэтому нам и незачем решать проблему N+1.
у нас монга, и 2 бекендера. а вот фронтенд пилят — 10+ фронтендеров.
да, стоит подумать про GraphQL как способе доступа к монге для фронтендеров

Не подошел — так не подошел.

он многим не подходит :)

но есть — резюме драйв девелопмент. поэтому — пихают

пальцы я не гну.
просто когда намекают что у чего-то нет недостатков, оно такое блестящее и крутое, я отвечаю

так достоинства и есть недостатки, и наоборот. в зависимости от того — как ты монетку повернешь. орел и решка — неразлучны.

Какой-то культ GraphQL, прямо

у кого?

Какой-то культ GraphQL, прямо

Ты не поверишь, но у некоторых он таки есть.
Типа вы еще на ресте? Фууу, весь мир на графкл уже давно! Графкл это новый рест!
Да ко мне самому приходил человек от бизнеса и говорил «нам нужен графкл». На вопрос «зачем?» он не смог ответить вообще ничего кроме «нууу ээ он щас у всех есть передовой типа»

А у нас «swagger» используется как описание интерфейса и сразу по его правилам автоматом проходит валидация полученных данных на бекэнде. Очень удобно просто качественно описал интерфейс и не нужно отдельно морочиться кастомной валидацией в коде реально экономит много времени разработчиков и тестировщиков. И еще один плюс это возможность автоматом сгенерить клиентов и проверки ответов для авто-тестов АПИ минус 8-16 часов тестировщика на одном большом эндпоинте, а когда их у вас 100-200 то это прилично экономит бюджет. И да «GraphQL» нам тоже пока не зашел, хорошо организовать на нем политики доступа к данным для большого количества юзер ролей пока не получилось так легко как это делается в RBAC с тем же Restful API

сразу по его правилам автоматом проходит валидация полученных данных на бекэнде.

у нас валидацию выполняют модели. с описанием бизнес-правил, или, если сложнее, выполняемым кодом.

со swaggerа модели — не представляю как сгенерить
он к ним вообще не имеет никакого отношения, в общем случае

Очень удобно просто качественно описал интерфейс и не нужно отдельно морочиться кастомной валидацией в коде реально экономит много времени разработчиков и тестировщиков

интерфейс — чего описываете?
например — как вы опишите «интерфейс корректного бухгалтерского счета для проводки с этой сущностью»?
а счет можно выбрать в UI. ессно. там он предлагается из списка корректных. но
правило № 1 — ничему нельзя доверять что приходит с фронта

И еще один плюс это возможность автоматом сгенерить клиентов и проверки ответов для авто-тестов

а что они тестируют, если нет данных для автотестов?

минус 8-16 часов тестировщика на одном большом эндпоинте

эндпойнты мы не тестируем. какой смысл?
интеграционными тестами обкладываются генераторы ответа
тестировщик тут не нужен совсем

а тестировать пару строк преобразования внутренних структур данных в json — а что там тестировать?

а когда их у вас 100-200 то это прилично экономит бюджет.

да, если вы тестировщиком тестируете эндпойнты, то конечно
он точно ипанется от такой работы :)

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

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

Можете рассказать подробнее о каких валидациях идет речь?
Так же не очень понятно за счет чего происходит экономия времени тестировщика. Если есть какое-то ограничение (например, на длину строки) должен быть тест который это проверит, ибо кто-то может убрать/поменять это правило в АПИ, но при этом не изменить логику, которая завязана на это ограничение (например, упадет запись в БД, для длинных строк)

Выглядит спорно, т.к.:
1. Задефайнили API с модельками.
2. Сгенерили OpenAPI спецификацию по ней и получили Swagger UI, где девелоперу можно руками по-быстрому дёрнуть любой эндпойнт.
3. (опционально) Потратили время на допиливание напильником стандартных swagger-codegen темплейтов для клиентского кода, который из коробки работает далеко не всегда хорошо. Хотя, для одной-двух технологий в долгосрочной перспективе может быть оправданно, возникает вопрос: как сгенеренный сваггером тест может проверить что-нибудь существенное, если он генерится по одному темплейту для всех эндпойнтов? Т.е., что именно он у Вас проверяет?
4. Валидация полученных данных (простая, а-ля «строка не более Х символов») происходит:
4.1. При десериализации модели с помощью десериализатора, если повесить валидацию на сами модели.
4.2. После десериализации, но перед выполнением реквеста, с помощью компонента бэкенда.
4.3. Во время выполнения реквеста (плохо).

Если убрать Swagger/OpenAPI из цепочки, на п. 4 это никак не влияет, т.к. API является source of truth, а не спецификация, которая поверх неё сгенерирована. Или Вы пишете сначала спецификацию OpenAPI руками?..

Написанное выше базируется на подготовке автогенерации SDK под несколько платформ с помощью swagger-codegen. Возможно, в ASP.NET Core просто очень хорошая интеграция со сваггером, поэтому сам фреймворк делает всю работу по валидации входящих данных в том числе, а на других платформах всё печальнее, но не знаю, не знаю...

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

Аналогичные мысли о сути графкл

Подписаться на комментарии