curl در لینوکس: گفت‌وگو با HTTP و API از خط فرمان

قبل از باز کردن Postman یا نوشتن اسکریپت تست، اغلب یک سؤال ساده دارید: آیا این URL از این سرور پاسخ می‌دهد و با چه کدی؟ curl کلاینت انتقال داده از خط فرمان است که برای HTTP/HTTPS در کار روزمرهٔ توسعه و عملیات تقریباً همه‌جا هست. قدرت آن در کنترل دقیق هدر، متد، بدنه و مشاهدهٔ جزئیات پروتکل است — نه فقط «دانلود فایل».

مقایسه با wget در مقالهٔ بعدی می‌آید؛ اینجا خود curl برای API و عیب‌یابی.

پاسخ کوتاه

برای دیدن پاسخ: `curl -sS URL`. برای کد وضعیت و هدر: `curl -sS -D - -o /dev/null URL` یا `curl -I`. برای POST JSON هدر Content-Type و `-d` را بگذارید. `-v` یا `--trace-time` برای عیب‌یابی TLS و مسیر.redirect. همیشه در اسکریپت `-f` یا چک کردن کد خروج/وضعیت را جدی بگیرید تا شکست HTTP خاموش نماند.

curl آینهٔ رفتار کلاینت است؛ اگر اینجا درست است و مرورگر نه، فرق هدر و کوکی را بجویید نه «خراب بودن سرور» را.

GET ساده و سکوت مفید

bash

curl https://example.com/ curl -sS https://example.com/ | head curl -sS -o body.txt -w '%{http_code}\n' https://example.com/

-s پیشرفت را خاموش می‌کند؛ -S خطا را حتی در حالت silent نشان می‌دهد — ترکیب رایج اسکریپت‌ها. -w متغیرهای خروجی مثل http_code را بعد از تمام شدن چاپ می‌کند.

هدر و متد

bash

curl -I https://example.com/ curl -sS -D - -o /dev/null https://example.com/ curl -X OPTIONS -sS -D - -o /dev/null https://api.example.com/v1/items

-I معادل GET با بدنه‌نخواستن برای بسیاری سرورها نیست؛ HEAD می‌فرستد. برای دیدن هدرهای پاسخ یک GET واقعی، -D - همراه دور ریختن بدنه تمیزتر است.

POST و JSON

bash

curl -sS -X POST https://api.example.com/v1/items \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer TOKEN' \ -d '{"name":"demo","ok":true}'

از فایل:

bash

curl -sS -X POST https://api.example.com/v1/items \ -H 'Content-Type: application/json' \ --data-binary @payload.json

توکن را در تاریخچهٔ شل سخت‌کد نکنید؛ از متغیر محیطی یا فایل با مجوز محدود بخوانید.

bash

curl -sS -H "Authorization: Bearer ${API_TOKEN}" https://api.example.com/v1/me

فرم، آپلود، دانلود

bash

curl -sS -F 'file=@./report.pdf' https://example.com/upload curl -sS -L -o image.png https://example.com/image.png curl -sS -C - -O https://example.com/big.iso

-L ریدایرکت را دنبال می‌کند (مراقب حلقه و تغییر متد باشید). -C - ادامهٔ دانلود ناقص، -O نام فایل را از URL می‌گیرد.

TLS، زمان و عیب‌یابی

bash

curl -v https://example.com/ 2>&1 | head -n 40 curl -sS --connect-timeout 3 --max-time 10 https://example.com/ curl -sS -w 'dns:%{time_namelookup} connect:%{time_connect} tls:%{time_appconnect} total:%{time_total}\n' -o /dev/null https://example.com/

هرگز در production به‌عادت `curl -k` نزنید مگر برای آزمایش کنترل‌شده با گواهی خودامضا؛ مشکل گواهی را درست کنید. جزئیات بیشتر زمان‌بندی به عیب‌یابی شبکه کمک می‌کند.

کد خروج در برابر کد HTTP

به‌صورت پیش‌فرض curl حتی با پاسخ 404 ممکن است کد خروج صفر بدهد چون انتقال موفق بوده. برای شکست‌خوردن روی خطای HTTP:

bash

curl -sS -f https://example.com/missing || echo "HTTP error or transfer fail"

یا کد را با -w بخوانید و در اسکریپت شاخه بزنید. این تفاوت علت باگ‌های CI است که «curl سبز بود ولی API خطا داد».

پروکسی و محیط

bash

curl -sS -x http://proxy.example.com:8080 https://example.com/ env | grep -i proxy

متغیرهای http_proxy/HTTPS_PROXY روی رفتار اثر می‌گذارند؛ در عیب‌یابی سازمانی اول محیط را چک کنید.

جدول میانبر روزمره

اشتباه‌های رایج

• فراموش Content-Type در POST و تعجب از 415.
• چسباندن توکن در اسکرین‌شات و لاگ CI.
• استفاده از -k همه‌جا و پنهان شدن حملهٔ MITM.
• فرض اینکه wget و curl همیشه یک رفتار ریدایرکت دارند.

خلاصه

curl ابزار دقیق حرف زدن با HTTP از ترمینال است: متد، هدر، بدنه، زمان، TLS. با -sS و -w اسکریپت‌پذیرش کنید، با -v عیب‌یابی کنید، و کد HTTP را از موفقیت انتقال جدا بفهمید. برای انتخاب بین curl و wget مقالهٔ بعدی را ببینید.

سوالات متداول

چرا در مرورگر ۲۰۰ است ولی curl گواهی خطا می‌دهد؟

ذخیرهٔ اعتماد CA روی سیستم curl، SNI، یا تفاوت IPv4/IPv6. -v و زنجیرهٔ گواهی را ببینید؛ گاهی مرورگر از store جدا استفاده می‌کند.

چطور چند هدر بفرستم؟

چند بار `-H 'Name: value'` تکرار کنید.

منابع و مراجع

• curl — command line tool and library: https://curl.se/
• curl man page online: https://curl.se/docs/manpage.html
• HTTP response status codes (MDN): https://developer.mozilla.org/en-US/docs/Web/HTTP/Status