2026-10-01

Коллекция final_v2: почему у каждого в команде своя копия

В рабочем чате лежат четыре файла: orders.postman_collection.json, orders_v2.json, orders_final.json и orders_v2_fixed.json. Их присылали разные люди в разные месяцы, и каждый был уверен, что его версия самая свежая. Новый разработчик скачивает все четыре и спрашивает, какая настоящая.

Ответа никто не знает. Автор первой уже полгода работает в другой компании.

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

В маленькой аккуратной команде такого может и не быть. В остальных это случается раньше, чем кажется.

Как одна коллекция становится четырьмя#

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

Дальше всё происходит само. Боря добавил авторизацию и прислал свою копию. Вика в это время поменяла адреса под новый стенд, но в своей копии, без Бориной авторизации. Обратно их никто не сливает: это долго, а запросы и так работают. У каждого работает своя версия.

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

Почему так выходит#

Коллекция принадлежит человеку, а не сервису: она живёт у того, кто её собрал. Пока он на связи, можно попросить свежую копию. Если он ушёл в отпуск или сменил работу, остаётся только то, что лежит в чате.

Второй симптом видно по именам. New Request, test2, Copy of create order понятны одному человеку, и то примерно до пятницы. Через месяц автор тоже не вспомнит, чем create order (1) отличается от Copy of create order, и на всякий случай оставит оба.

И третий: за актуальность коллекции никто не отвечает. Код ревьюят, тесты гоняют, документацию хотя бы иногда обновляют. Коллекцию считают чем-то вспомогательным, пока не наступает понедельник, когда без неё не выйти на новый стенд.

Как делиться коллекцией с командой: три способа и их цена#

Рабочих подходов три, и команды обычно смешивают два из них.

Репозиторий хорош тем, что у коллекции появляется история: видно, кто и когда поменял запрос. Bruno хранит коллекции обычными файлами в папке, которую удобно положить в Git, у Yaak есть похожий режим. Минус тот же, что у любого ручного процесса: после каждой правки нужно экспортировать и закоммитить, а если забыли, у всех снова разное. Аналитик и менеджер в репозиторий к тому же не пойдут.

Общее пространство снимает вопрос «у кого последняя версия»: она одна, и правки коллег видны сразу. Взамен все заводят аккаунт, кто-то раздаёт права, а данные лежат на чужом сервере.

Ссылка нужна для самого частого случая. Большинству людей коллекцию не нужно править. Им нужно понять, какие есть запросы, что туда отправить и что придёт в ответ. Для этого хватит страницы, которую можно открыть в браузере. Править её читатель не сможет, а вам придётся не забывать её обновлять.

Как делиться коллекцией в Postman#

В Postman у коллекции два пути к коллегам. Первый: экспорт в файл формата v2.1. Именно так и рождаются orders_v2.json и orders_final.json со всеми проблемами из начала статьи. Второй: общее рабочее пространство в облаке Postman, где коллекция одна на всех, а правки можно предлагать через форк и запрос на слияние. Для команды это значит аккаунты у всех и платный тариф: на бесплатном совместная работа сильно ограничена. Если коллекция уже разошлась файлами, её можно перенести и в другой клиент, вот что переносится из Postman.

Признаки живой коллекции#

Какой бы способ вы ни выбрали, живая коллекция узнаётся по пяти признакам.

У неё есть хозяин. Конкретный человек. «Вся команда» не считается. Он не обязан писать все запросы, но он знает, какая версия настоящая, и удаляет мусор.

Запросы названы по действию. «Отменить заказ» понятно без открытия. test2 не понятно даже после.

У запросов есть описание в две строки. Что делает, что нужно для отправки (токен, стенд, существующий заказ) и что вернётся. Роман писать не нужно, хватит того, что вы бы сказали коллеге голосом.

Есть пример ответа. По сохранённому ответу сразу видно, какие поля вернутся, даже если токена у коллеги ещё нет.

Есть одна точка входа. Ссылка в закрепе канала или в README. Не «поищи в чате, там Вика кидала».

Как это выглядит в Tetiva#

В Tetiva за три последних признака отвечают описания, примеры ответов и публикация.

У коллекции и у каждого запроса есть описание в Markdown, а к запросу можно сохранить примеры ответов. Если коллекцию нужно показать людям снаружи, коллекцию верхнего уровня можно опубликовать: получится страница вида share.tetiva.app/orders-7f3k9q2a. Ссылка не меняется, даже если коллекцию переименовать, поэтому её можно смело класть в закреп. Читателю аккаунт не нужен. Он может посмотреть запросы в браузере, забрать коллекцию к себе кнопкой «Открыть в Tetiva» или скачать файл для Postman.

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

От расползания версий больше всего помогает напоминание. Если коллекцию поменяли после публикации, на вкладке появляется пометка «Изменена после публикации» и точка у её названия. Страница сама не обновится, нужно нажать «Проверить и обновить…». Зато вы узнаете, что она отстала, раньше, чем вам об этом напишут в чат.

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

Уборка на 15 минут#

Для начала хватит одного захода.

1. Соберите все копии. Поищите в чате .json и слово «коллекция». Скорее всего, найдётся больше, чем вы думаете.
2. Выберите основу. Откройте каждую копию и отправьте три самых важных запроса. Какая отвечает без правок, та и основа. Недостающее из остальных перенесите руками.
3. Удалите test2 и все Copy of. Остальное переименуйте по действию и разложите по папкам.
4. Назначьте хозяина. Одного человека, вслух, на встрече.
5. Оставьте одну ссылку. Закрепите её в канале, а старые файлы подпишите «не использовать».

Раз в квартал хозяин повторяет пункты 3 и 5. Это те же 15 минут, только без археологии.

А orders_v2_fixed.json можно удалить. Боря поймёт.