Еще разок про универсальщину. Попался прямо таки каноничный пример как делать не нужно.
Итак, есть вендор. В их системе весомая часть действий — это документ (так исторически сложилось).
Не важно, что происходит: создаём заявку, выполняем операцию, меняем состояние — всегда создаётся документ.
Для всех документов используется универсальный интерфейс:
мы указываем тип документа и передаём набор полей, который якобы его описывает.
Примерно вот так:
POST /documents
{
"type": "X",
"field1": "...",
"field2": "...",
"field3": "а может и не нужно"
}
Звучит гибко, но на практике это превращается в проблему:
- есть одна универсальная дата-модель, где все поля опциональные;
- невозможно понять, какие поля нужно заполнять и как именно;
- одно и то же поле может означать совершенно разные вещи в разных типах документов;
- без нормальной документации (а её, как правило, нет) пользоваться этим почти невозможно.
Ну и вишенка на торте — у документа может быть свой набор состояний или действий. Как результат — целый кабинет аналитиков и разработчиков пытается расшифровать что происходит и как с этим жить.
Вывод простой: даже если внутри системы всё построено на документах — не делайте универсальные интерфейсы. Типизированные контракты и явные модели почти всегда выигрывают у гибкости ради гибкости.