Об этом проекте
# Библиотека Go REST Client
Этот проект предоставляет библиотеку Go и инструмент командной строки для выполнения HTTP-запросов, определённых в файлах `.http` — формате, популяризированном IDE JetBrains и расширением VS Code REST Client. Проект нацелен на полную совместимость с этими инструментами, позволяя разработчикам использовать одни и те же файлы запросов как для ручного тестирования в IDE, так и для автоматизированных сквозных (E2E) тестов на Go.
## Ключевые возможности
- **Совместимость с JetBrains/VS Code**: разбирает файлы `.http`, используя тот же синтаксис, переменные и поведение, что и популярные расширения IDE.
- **Подстановка переменных**: поддерживает пользовательские переменные, переменные окружения и системные переменные, такие как `{{$guid}}`, `{{$randomInt}}`, `{{$timestamp}}` и `{{$datetime}}`.
- **Связывание ответов**: ссылайтесь на ответы других запросов в том же файле, например `{{authenticate.response.body.token}}`.
- **Ссылки на запросы**: используйте `@ref` (кэшируется на время запуска) или `@forceRef` (всегда выполняет повторно) для запуска предварительных запросов, а `@import` — для совместного использования именованных запросов между файлами.
- **Управление запросами**: пропускайте запросы с помощью `@disabled`, делайте паузу перед отправкой с `@sleep <ms>` и зацикливайте запросы с `@loop`.
- **Проверка ответов**: сравнивайте ответы с файлами `.hresp` с заполнителями, такими как `{{$any}}`, `{{$regexp}}` и `{{$anyGuid}}`.
- **Несколько запросов в файле**: разделяйте запросы с помощью `###`.
- **Готовность к E2E-тестированию**: разработан для автоматизированных интеграционных тестов.
## Формат файла HTTP
Файлы `.http` — это обычные текстовые файлы, определяющие HTTP-запросы. Запрос состоит из необязательного имени, метода, URL, заголовков и тела.
```http
### Request Name
METHOD URL
Header1: value1
body content
```
### Пример
```http
@baseUrl = https://api.example.com
@userId = 123
### Get user profile
GET {{baseUrl}}/users/{{userId}}
Authorization: Bearer {{authToken}}
X-Request-ID: {{$guid}}
```
## Использование библиотеки
### Установка
```bash
go get github.com/bmcszk/go-restclient
```
### Выполнение запросов в Go
```go
package main
import (
"context"
"log"
"github.com/bmcszk/go-restclient"
)
func main() {
client, _ := restclient.NewClient(
restclient.WithVars(map[string]interface{}{
"authToken": "your-token-here",
}),
)
responses, _ := client.ExecuteFile(context.Background(), "requests.http")
for i, resp := range responses {
if resp.Error != nil {
log.Printf("Request %d failed: %v", i+1, resp.Error)
} else {
log.Printf("Request %d: %d %s", i+1, resp.StatusCode, resp.Status)
}
}
}
```
### Опции клиента
```go
client, err := restclient.NewClient(
restclient.WithBaseURL("https://api.example.com"),
restclient.WithDefaultHeader("X-API-Key", "secret"),
restclient.WithHTTPClient(customHTTPClient),
restclient.WithVars(variables),
)
```
## Использование CLI
CLI `restclient` запускает файлы `.http` из командной строки.
### Установка
```bash
go install github.com/bmcszk/go-restclient/cmd/restclient@latest
```
### Основные команды
```bash
restclient -f requests.http --all
restclient -f requests.http -n "get user"
restclient -f requests.http -i 0
restclient --version
```
### Список запросов
```bash
restclient -f requests.http --list
```
### Запуск одного запроса
По имени (без учёта регистра):
```bash
restclient -f requests.http -n "create user"
```
По индексу с отсчётом от 0:
```bash
restclient -f requests.http -i 0
```
### Переменные командной строки
```bash
restclient -f requests.http -D token=abc123 -D env=prod
```
### Предварительные запросы
```bash
restclient -f requests.http -n "get protected" -A authenticate
```
### Завершение с ошибкой при ошибках
Выход с кодом 1 при ответах HTTP 4xx/5xx:
```bash
restclient -f requests.http -E
```
### Форматы вывода
```bash
# Только тело
restclient -f requests.http -o body
# Извлечение по JSON path
restclient -f requests.http -o jsonpath "data.users[0].name"
# Формат переменной окружения
restclient -f requests.http -o env "token"
```
### Флаги CLI
| Короткий | Длинный | Описание |
| ----- | ---- | ----------- |
| `-f` | `--file` | Путь к файлу запросов (обязательно) |
| `-n` | `--name` | Запустить запрос по имени |
| `-i` | `--index` | Запустить запрос по индексу |
| | `--all` | Запустить все запросы в файле |
| `-e` | `--expected` | Файл ожидаемого ответа |
| | `--e-name` | Имя ожидаемого ответа |
| | `--e-index` | Индекс ожидаемого ответа |
| `-l` | `--list` | Список запросов |
| `-E` | `--fail-on-error` | Ошибка при 4xx/5xx |
| `-o` | `--output` | Формат вывода |
| `-A` | `--after` | Предварительный запрос |
| `-D` | `--define` | Определить переменную (можно повторять) |
## Проверка ответов
Создайте файлы `.hresp` для проверки ответов.
**responses.hresp:**
```http
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": "{{$anyGuid}}",
"name": "{{$any}}",
"createdAt": "{{$anyTimestamp}}"
}
```
**Проверка в Go:**
```go
err := client.ValidateResponses("responses.hresp", responses...)
if err != nil {
log.Fatal("Validation failed:", err)
}
```
### Заполнители для проверки
- `{{$any}}` — соответствует любому тексту
- `{{$regexp ``pattern``}}` — шаблон регулярного выражения (в обратных кавычках)
- `{{$anyGuid}}` — формат UUID
- `{{$anyTimestamp}}` — временная метка Unix
- `{{$anyDatetime 'format'}}` — дата и время (rfc1123, iso8601 или пользовательский формат)
## Сценарии использования
### Ручное тестирование
Используйте ваше любимое расширение IDE для тестирования API во время разработки.
### Автоматизированное E2E-тестирование
```go
func TestUserAPI(t *testing.T) {
client, _ := restclient.NewClient(
restclient.WithBaseURL(testServer.URL),
)
responses, err := client.ExecuteFile(context.Background(), "user_tests.http")
require.NoError(t, err)
err = client.ValidateResponses("user_expected.hresp", responses...)
require.NoError(t, err)
}
```
## Разработка
### Предварительные требования
- Go 1.21+
### Команды
```bash
make check # Run all checks (lint, test, build)
```
## Лицензия
MIT License
Comments
0 Rating appears after 10 ratings
Sign in to join the discussion.