Коллекции, окружения и переменные в Postman

Главная идея

Три инструмента Postman решают одну задачу — не дублировать запросы:

• Коллекция — папка с запросами одного API или проекта, с подпапками, общей авторизацией и документацией.
• Переменная — именованное значение, которое подставляется в запрос: {{baseUrl}}/users.
• Окружение (environment) — набор переменных для конкретного стенда: локальный, dev, staging, production.

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

Как организовать коллекцию

Хорошая структура повторяет структуру API:

Shop API
├── Auth
│   ├── Login
│   └── Refresh token
├── Products
│   ├── List products
│   ├── Get product
│   └── Create product
└── Orders
    ├── Create order
    └── Get order

Практические правила:

• Названия запросов — человеческие, по действию: «Create order», а не «POST /orders 2».
• Авторизацию настройте на уровне коллекции, а в запросах оставьте Inherit auth from parent. Токен меняется в одном месте.
• Сохраняйте примеры ответов (Save as example) — они попадают в документацию и помогают тем, кто видит API впервые.

Окружения: dev, staging, production

Создайте окружение для каждого стенда с одинаковыми именами переменных:

В запросах используйте только переменные: {{baseUrl}}/products. Переключатель окружений находится в правом верхнем углу. Postman подсвечивает переменные цветом, а те, что не определены в текущем окружении, — красным.

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

Области видимости переменных

У Postman пять уровней. Если переменная с одним именем задана в нескольких местах, побеждает самая узкая область:

Приоритет: Local → Data → Environment → Collection → Global.

Переменные из скриптов

Токен удобно не копировать руками, а сохранять из ответа логина. Во вкладке скриптов, которые выполняются после запроса, добавьте:

const data = pm.response.json();
pm.environment.set("token", data.access_token);

Теперь после запроса Login все остальные запросы с {{token}} получат свежий токен.

Секреты и общие значения

У переменной есть общее значение, которое синхронизируется со всей командой, и текущее значение, которое хранится только у вас. Названия этих полей отличаются в разных версиях Postman, но принцип один:

• В общее значение кладите то, что не жалко показать: адреса, идентификаторы, пустые заглушки.
• Токены и пароли храните только в текущем значении и отмечайте тип secret — он скрывает значение на экране.
• Для чувствительных данных есть Postman Vault: секреты хранятся локально и подставляются через ссылки вида {{vault:имя}}.

Совместная работа и документация

• Team workspace — коллекции и окружения видны всей команде и обновляются у всех.
• Fork и pull request — можно сделать копию коллекции, изменить её и предложить изменения, как в Git.
• Экспорт в JSON — коллекцию и окружение можно выгрузить файлом и хранить в репозитории рядом с кодом.
• Документация — описания коллекции, папок и запросов пишутся в Markdown. Postman собирает из них страницу документации с примерами запросов и ответов.

Частые ошибки

• Адрес сервера записан прямо в запросе — при смене стенда приходится править всё вручную.
• Токены лежат в общем значении переменной и видны всей команде.
• Одноимённые переменные в глобальной области и окружении — непонятно, какая сработала.
• Нет описаний: через месяц никто не помнит, зачем нужен запрос «test 3».