このプロジェクトについて
# Go RESTクライアントライブラリ
このプロジェクトは、JetBrains IDEやVS Code REST Client拡張機能で普及した`.http`ファイル形式で定義されたHTTPリクエストを実行するためのGoライブラリとコマンドラインツールを提供します。これらのツールとの完全な互換性を目指しており、開発者はIDEでの手動テストとGoでの自動エンドツーエンド（E2E）テストの両方に同じリクエストファイルを使用できます。
## 主な機能
- **JetBrains/VS Code互換性**: 人気のIDE拡張機能と同じ構文、変数、動作を使用して`.http`ファイルを解析します。
- **変数置換**: カスタム変数、環境変数、`{{$guid}}`、`{{$randomInt}}`、`{{$timestamp}}`、`{{$datetime}}`などのシステム変数をサポートします。
- **レスポンスチェーン**: 同じファイル内の他のリクエストからのレスポンスを参照できます（例: `{{authenticate.response.body.token}}`）。
- **リクエスト参照**: `@ref`（実行ごとにキャッシュ）または`@forceRef`（常に再実行）を使用して前提リクエストを実行し、`@import`を使用してファイル間で名前付きリクエストを共有できます。
- **リクエスト制御**: `@disabled`でリクエストをスキップし、`@sleep <ms>`で送信前に一時停止し、`@loop`でリクエストをループできます。
- **レスポンス検証**: `{{$any}}`、`{{$regexp}}`、`{{$anyGuid}}`などのプレースホルダーを使用して、レスポンスを`.hresp`ファイルと比較します。
- **ファイル内の複数リクエスト**: `###`でリクエストを区切ります。
- **E2Eテスト対応**: 自動統合テスト用に設計されています。
## HTTPファイル形式
`.http`ファイルは、HTTPリクエストを定義するプレーンテキストファイルです。リクエストは、オプションの名前、メソッド、URL、ヘッダー、ボディで構成されます。
```http
### リクエスト名
METHOD URL
Header1: value1
ボディコンテンツ
```
### 例
```http
@baseUrl = https://api.example.com
@userId = 123
### ユーザープロフィールを取得
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("リクエスト %d が失敗しました: %v", i+1, resp.Error)
} else {
log.Printf("リクエスト %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の使用方法
`restclient` CLIは、コマンドラインから`.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
```
### エラー時の失敗
HTTP 4xx/5xxレスポンスで終了コード1を返します:
```bash
restclient -f requests.http -E
```
### 出力形式
```bash
# ボディのみ
restclient -f requests.http -o body
# JSONパス抽出
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("検証に失敗しました:", 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 # すべてのチェックを実行（lint、test、build）
```
## ライセンス
MITライセンス
Comments
0 Rating appears after 10 ratings
Sign in to join the discussion.