프로젝트 소개
# 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("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 사용법
`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("Validation failed:", err)
}
```
### 검증 자리 표시자
- `{{$any}}` - 모든 텍스트와 일치
- `{{$regexp ``pattern``}}` - 정규식 패턴(백틱 사용)
- `{{$anyGuid}}` - UUID 형식
- `{{$anyTimestamp}}` - Unix 타임스탬프
- `{{$anyDatetime 'format'}}` - 날짜시간(rfc1123, iso8601 또는 사용자 정의)
## 사용 사례
### 수동 테스트
개발 중 API를 테스트하려면 선호하는 IDE 확장 프로그램을 사용합니다.
### 자동화된 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 # 모든 검사 실행(린트, 테스트, 빌드)
```
## 라이선스
MIT 라이선스
Comments
0 Rating appears after 10 ratings
Sign in to join the discussion.