Ваше первое рабочее пространство

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

• Время: 15 минут.
• Вам понадобится: Echolot и Git для последней части (git --version в Терминале; macOS предложит его установить).
• Вы узнаете: как рабочее пространство устроено на диске и почему его безопасно коммитить.

1. Создайте рабочее пространствоCopy Anchor Link

1. В окне Добро пожаловать в Echolot выберите Новое рабочее пространство…. Из окна рабочего пространства выберите Файл › Новое рабочее пространство… (⌥⌘N).
2. В панели Новое рабочее пространство назовите его Alpenglow Shop и выберите папку, например ~/Projects. Расширение .echolot Echolot добавит сам.
3. Нажмите Создать.

Откроется окно с надписью Рабочее пространство пусто. На диске Alpenglow Shop.echolot — это папка, в которой лежат workspace.toml и пустая папка requests. В Finder она выглядит как один файл, и двойной щелчок по ней открывает рабочее пространство.

2. Отправьте первый запросCopy Anchor Link

1. Выберите Новый запрос на пустой странице или Файл › Новый запрос (⌘N). Запрос появится в боковой панели, и его имя можно сразу менять.

2. Введите List products и нажмите ↩.

3. Оставьте метод GET. В поле URL введите:

   Скопировать текст

   https://demo.echolot.dev/v1/products?category=tents

   Параметр запроса отображается и на вкладке Параметры, где его можно изменить в виде таблицы.

4. Выберите Отправить (⌘R или ⌘↩).

В области ответа видны 200 OK, время и размер. Вкладка Тело содержит товары в формате JSON. Переключите её вид на JSON-дерево, чтобы сворачивать и разворачивать список. Каждая вкладка описана на странице об ответах.

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

3. Разложите запросы по папкеCopy Anchor Link

1. Выберите Файл › Новая папка (⇧⌘N), введите Catalog и нажмите ↩.
2. Перетащите List products на Catalog.
3. Щёлкните Catalog правой кнопкой и выберите Новый запрос. Назовите его Get product.
4. Задайте ему URL https://demo.echolot.dev/v1/products/TNT-MH-2P и отправьте.

Вы получите одну палатку, Matterhorn 2P, с ценой и наличием в Цюрихе и Берне. Каждый запрос — отдельный файл: requests/catalog/get-product.req.toml. Папки также могут задавать авторизацию, переменные и скрипты для всех запросов в них; см. папки.

4. Вынесите адрес в окружениеCopy Anchor Link

Если вписывать адрес сервера в каждый запрос, сменить сервер трудно. Вместо этого вынесите его в окружение.

1. Выберите Вид › Окружения (⌥⌘E) или откройте меню окружений в заголовке страницы и выберите Управление окружениями….
2. Нажмите + (Добавить окружение). Появится Новое окружение. Измените его Имя на Demo.
3. Выберите Добавить переменную. Задайте Имя baseURL и Значение https://demo.echolot.dev/v1.
4. Добавьте второе окружение с именем Local, в котором baseURL равна http://localhost:8787/v1. Это демо-API, запущенное на вашем Mac; для этого руководства запускать его не нужно.
5. В меню окружений в заголовке страницы выберите Demo.
6. Вернитесь к List products и измените его URL на {{baseURL}}/products?category=tents. То же сделайте для Get product: {{baseURL}}/products/TNT-MH-2P.

Пока вы вводите {{, список предлагает ваши переменные. В URL {{baseURL}} показывается как токен; наведите на него указатель, чтобы увидеть его значение в текущем окружении. Отправьте оба запроса ещё раз: они по-прежнему доходят до демо-API. Выберите Local, и они пошли бы на ваш Mac — без каких-либо других изменений.

5. Сохраните пароль в секретеCopy Anchor Link

Для входа в магазин нужен пароль. Пароль никогда не должен попадать в файл, который вы коммитите.

1. На странице Окружения выберите Demo и нажмите Добавить переменную.

2. Назовите её password и отметьте флажок Секрет. Поле значения превратится в поле пароля с надписью Не задано на этом Mac.

3. Введите alpenglow и нажмите ↩ (или выберите Сохранить). Значок ключа показывает, что значение лежит в Связке ключей.

4. Создайте папку Auth и в ней запрос Sign in. Задайте метод POST и URL {{baseURL}}/auth/token.

5. На вкладке Тело выберите JSON и введите:

   Скопировать текст

   { "email": "heidi@alpenglow.ch", "password": "{{password}}" }

6. Отправьте его.

Ответ — 200 OK с access_token. Заголовок Content-Type: application/json для тела JSON Echolot добавляет сам. Откройте environments/demo.toml: переменная password там есть, с secret = true и без значения. Значение хранится только в Связке ключей на этом Mac, поэтому каждый, кто открывает рабочее пространство, задаёт своё; см. секреты.

Следующее руководство использует этот токен для запросов, которым он нужен.

6. Поместите рабочее пространство в GitCopy Anchor Link

У Echolot нет собственных команд Git: рабочее пространство — это обычные файлы TOML, так что с Git вы работаете так же, как с кодом.

1. Внизу боковой панели откройте меню рабочего пространства и выберите Показать в Finder. Перетащите папку Alpenglow Shop.echolot на значок Терминала или перейдите в неё через cd.

2. Выполните:

   Скопировать текст

   git init
   git add .
   git commit -m "Alpenglow Shop: catalog and sign-in"

Что вы закоммитили:

Alpenglow Shop.echolot/
├── workspace.toml
├── environments/
│   ├── demo.toml
│   └── local.toml
└── requests/
    ├── _folder.toml
    ├── auth/
    │   ├── _folder.toml
    │   ├── sign-in.req.toml
    │   └── sign-in.body.json
    └── catalog/
        ├── _folder.toml
        ├── get-product.req.toml
        └── list-products.req.toml

Ничего секретного в этом нет, и .gitignore не нужен: ответы и история хранятся вне рабочего пространства, в собственном хранилище Echolot. Каждый файл записывается каждый раз одинаково, поэтому в diff видно только то, что вы изменили.

Когда кто-то другой забирает изменения, открытое окно подхватывает их само. Если файл изменился на диске, пока в нём есть ваши несохранённые правки, появляется полоса Этот запрос изменился на диске: выберите Взять с диска или Оставить мои. Подробнее — в разделе Git и команды.

ДальшеCopy Anchor Link

• Цепочка запросов: передайте токен из Sign in каждому запросу, которому он нужен.
• Защищённые окружения: пусть Echolot спрашивает перед каждой отправкой на важный сервер.
• Файлы рабочего пространства: каждый файл и поле.