عن المشروع
# مكتبة عميل REST بلغة Go
يوفر هذا المشروع مكتبة بلغة Go وأداة سطر أوامر لتنفيذ طلبات HTTP المعرفة في ملفات `.http`، وهي الصيغة التي شاع استخدامها بواسطة بيئات 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}}`.
- **طلبات متعددة في ملف واحد**: افصل بين الطلبات باستخدام `###`.
- **جاهز للاختبارات الشاملة**: مصمم للاختبارات التكاملية الآلية.
## صيغة ملف 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),
)
```
## استخدام سطر الأوامر
تقوم أداة `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
restclient -f requests.http -o jsonpath "data.users[0].name"
# صيغة متغير البيئة
restclient -f requests.http -o env "token"
```
### خيارات سطر الأوامر
| قصير | طويل | الوصف |
| ----- | ---- | ----------- |
| `-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``}}` - نمط regex (بين علامتي backtick)
- `{{$anyGuid}}` - صيغة UUID
- `{{$anyTimestamp}}` - طابع زمني Unix
- `{{$anyDatetime 'format'}}` - تاريخ ووقت (rfc1123 أو iso8601 أو مخصص)
## حالات الاستخدام
### الاختبار اليدوي
استخدم امتداد IDE المفضل لديك لاختبار واجهات برمجة التطبيقات أثناء التطوير.
### الاختبار الآلي الشامل
```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.