Loading…

درباره فرمت‌دهنده آنلاین HCL / Terraform

Terraform، Packer و سایر ابزارهای HashiCorp همگی از HCL2 استفاده می‌کنند—و همگی زمانی که به صورت یکپارچه فرمت شده باشند، بهتر به نظر می‌رسند. این فرمت‌دهنده HCL پیکربندی شما را به یک بک‌اند امن ارسال می‌کند که قوانین سبک terraform fmt را برای تورفتگی، فاصله‌گذاری و چیدمان اعمال می‌کند، سپس HCL2 نرمال شده را بازمی‌گرداند در حالی که معناشناسی را دست نخورده باقی می‌گذارد.

ویژگی‌های کلیدی

  • فرمت‌دهی آگاه از HCL2 برای بلوک‌های سبک Terraform، ویژگی‌ها، لیست‌ها/نقشه‌ها و heredocها
  • تورفتگی و فاصله‌گذاری یکپارچه حول =، کاماها، آکولادها و بلوک‌های تو در تو
  • نظرات و خطوط خالی عمدی را تا حد امکان برای خوانایی حفظ می‌کند
  • با فایل‌های .tf، .hcl، .tfvars مبتنی بر HCL و فایل‌های Packer .pkr.hcl کار می‌کند
  • خروجی idempotent: اجرای مجدد فرمت‌دهنده نتیجه یکسانی می‌دهد
  • حداقل سطح تماس: یک عمل «Format» واحد، بدون تنظیمات سبک برای بحث
  • کپی یا دانلود یک‌کلیکی نتیجه فرمت شده از ویرایشگر
  • پردازش مبتنی بر سرور از طریق یک endpoint امن — عالی برای اصلاحات سریع؛ برای کدهای بسیار حساس، CLI محلی را ترجیح دهید

🔧 نحوه استفاده از فرمت‌دهنده HCL for hcl-formatter

1

۱. کد خود را پیست یا رها کنید

فایل HCL/Terraform خود را باز کنید (.tf, .tfvars مبتنی بر HCL, .hcl, .pkr.hcl و غیره) و محتوا را در ویرایشگر پیست کنید، یا اگر مرورگر شما پشتیبانی می‌کند فایل را رها کنید.

2

۲. کلیک روی «قالب‌بندی»

دکمه قالب‌بندی را کلیک کنید. پیکربندی شما به یک بک‌اند امن ارسال می‌شود که قوانین سبک terraform fmt را برای تورفتگی، فاصله‌گذاری و چیدمان اعمال می‌کند، سپس HCL2 قالب‌بندی شده را برمی‌گرداند.

3

۳. بررسی، کپی یا دانلود

نتیجه را در ویرایشگر بررسی کنید، سپس آن را به IDE خود برگردانید یا فایل قالب‌بندی شده را دانلود کرده و به مخزن خود commit کنید.

مشخصات فنی

مدل اجرا

قالب‌بند مبتنی بر سرور است و برای شبیه‌سازی نرمال‌سازی چیدمان سبک terraform fmt برای HCL2 طراحی شده است.

جنبهجزئیات
حالتمبتنی بر سرور (بدون WASM در مرورگر)
حوزهفاصله سفید، تورفتگی، فاصله‌گذاری، چیدمان پایه
بازچینیبدون بازچینی معنایی منابع یا بلوک‌ها
گزینه‌هاهیچ — یک عمل قالب‌بندی برای خروجی قابل پیش‌بینی
محدودیت‌هاتقریباً ۱-۲ مگابایت ورودی، ~۲۵ ثانیه زمان‌انتظار سرور (قابل تنظیم)
نگهداریپردازش موقت — ورودی پس از قالب‌بندی دور ریخته می‌شود
همانند هر ابزار آنلاین دیگر، از پیست کردن اسرار تولیدی خودداری کنید. برای کدهای حساس از terraform fmt یا packer fmt به صورت محلی استفاده کنید.

پوشش زبانی

سازه‌های رایج HCL2 مورد استفاده در Terraform و سایر ابزارهای HashiCorp را درک می‌کند.

سازهمثال‌هایادداشت‌ها
بلوک‌هاresource, variable, output, module, locals, job, taskساختار بلوک تو در تو حفظ شده است
ویژگی‌هاname = "web", count = 2فاصله‌گذاری حول = و بین ویژگی‌ها نرمال شده است
مجموعه‌ها[1, 2, 3], { key = value }طرح یکسان برای لیست‌ها و نقشه‌ها/اشیاء
Heredocs<<-EOF ... EOFنشانگرها حفظ شده‌اند؛ تورفتگی در صورت امکان نرمال شده است
توضیحاتتوضیحات به سبک # و //در صورت امکان برای حفظ هدف و مستندات نگهداری می‌شوند

نمونه کوچک قبل/بعد

یک مثال کوچک از پاکسازی تورفتگی و فاصله‌گذاری در یک منبع Terraform.

# قبل
resource "aws_s3_bucket" "b"{bucket="demo"
  tags={Name="demo"}}

# بعد
resource "aws_s3_bucket" "b" {
  bucket = "demo"

  tags = {
    Name = "demo"
  }
}
تبدیل فقط در طرح‌بندی: شناسه‌ها، عبارات و ارجاعات بدون تغییر باقی می‌مانند.

خطاها و موارد خاص

اگر قالب‌بندی با شکست مواجه شود یا خطایی بازگرداند، معمولاً به دلیل مشکلات تجزیه در ورودی HCL2 است.

علائمعلت محتملموارد بررسی
بدون خروجی / خطای تجزیهآکولاد، براکت یا پرانتز بسته نشدهجفت‌های { }، [ ]، ( ) را شمرده و تمام بلوک‌ها را ببندید
مشکلات Heredocترمیناتور گم شده یا ناهماهنگاطمینان حاصل کنید که نشانگرهایی مانند EOF دقیقاً و در خط خود ظاهر شوند
سبک‌های ترکیبیتب/فاصله یا کاراکترهای سرگردانتورفتگی را نرمال کنید، کاراکترهای کنترلی سرگردان را حذف کنید
سردرگمی .tfvarsسینتکس JSON در مقابل HCLبرای فایل‌های *.tfvars.json از فرمت‌دهنده JSON یا terraform fmt استفاده کنید

جایگزین‌های خط فرمان

برای گردش کار روزمره زیرساخت به عنوان کد، از فرمت‌دهنده‌های رسمی به صورت محلی و در CI استفاده کنید و این ابزار آنلاین را برای پاکسازی‌های سریع موردی نگه دارید.

macOS / Linux

Terraform: قالب‌بندی در محل

terraform fmt

فایل‌های .tf و .tfvars مبتنی بر HCL را در دایرکتوری جاری بازنویسی می‌کند.

Terraform: بررسی بازگشتی CI (بدون نوشتن)

terraform fmt -check -recursive

در صورت نیاز هر فایل به قالب‌بندی، غیرصفر خارج می‌شود - مناسب برای CI و هوک‌های پیش از commit.

Packer: قالب‌بندی تمپلیت

packer fmt path/to/template.pkr.hcl

فایل HCL مشخص شده Packer را در محل قالب‌بندی می‌کند.

ویندوز (PowerShell)

فرمت کردن تمام فایل‌های Terraform به صورت بازگشتی

Get-ChildItem -Recurse -Filter *.tf | ForEach-Object { terraform fmt $_.FullName }

terraform fmt را روی هر فایل .tf یافت شده در زیرشاخه جاری اجرا می‌کند.

بررسی فرمت به سبک CI

terraform fmt -check -recursive

در خطوط ساخت برای شکست خوردن هنگام منسوخ بودن فرمت استفاده کنید.

GitHub Actions

اگر فرمت‌بندی لازم باشد، ساخت را متوقف کن

steps:
  - uses: hashicorp/setup-terraform@v3
  - run: terraform fmt -check -recursive

وقتی هر فایل Terraform به درستی فرمت نشده باشد، گردش کار را متوقف می‌کند.

فرمت‌بندی خودکار روی درخواست‌های pull (اختیاری)

steps:
  - run: terraform fmt -recursive
  - run: git diff --quiet || (git config user.name "bot" && git config user.email "bot@example" && git commit -am "chore: terraform fmt" && git push)

terraform fmt را اعمال می‌کند و یک کامیت فقط برای فرمت‌بندی به شاخه بازمی‌گرداند.

برای کد زیرساخت تنظیم‌شده یا محرمانه، ابزارهای CLI محلی را ترجیح دهید و `terraform fmt -check -recursive` را در CI به جای ارسال فایل‌ها به فرمت‌کننده‌های آنلاین اجرا کنید.

کاربردهای عملی

بهداشت PR و بازبینی‌ها

فضاهای خالی و تورفتگی‌ها را یکسان کنید تا بازبین‌ها روی تغییرات واقعی زیرساخت تمرکز کنند.

  • قبل از باز کردن یک درخواست pull فرمت‌بندی را اجرا کنید
  • کاهش نظرات نکته‌بینانه سبک در بازبینی‌های Terraform
  • تفاوت‌های git را کوچک و معنادار نگه دارید

توسعه ماژول Terraform

ماژول‌ها را در بین تیم‌ها، مخازن و رجیستری‌ها یکسان نگه دارید.

  • تراز کردن بلوک‌های متغیر و خروجی در ماژول‌های مشترک
  • اطمینان از مطابقت پیکربندی‌های مثال با یک سبک خانه واحد

نگهبانی CI

از بررسی‌های terraform fmt در CI برای جلوگیری از انحراف سبک در طول زمان استفاده کنید.

  • افزودن `terraform fmt -check -recursive` به عنوان یک مرحله اجباری خط لوله
  • مسدود کردن ادغام‌ها تا زمانی که تمام فایل‌های .tf فرمت شوند

راه‌اندازی و مستندات

مثال‌های قابل خواندن به اعضای جدید تیم کمک می‌کنند تا هم Terraform و هم سبک خانه را سریع یاد بگیرند.

  • انتشار قطعات کد یکسان فرمت‌شده در READMEها
  • استفاده از مثال‌های تمیز در جلسات آموزشی داخلی Terraform

❓ Frequently Asked Questions

🔒آیا کد من به صورت محلی پردازش می‌شود؟

خیر. این فرمت‌کننده HCL مبتنی بر سرور است: ورودی شما به یک نقطه پایانی امن برای فرمت‌بندی ارسال می‌شود و HCL حاصل به مرورگر شما بازگردانده می‌شود. برای کد زیرساخت بسیار حساس یا تنظیم‌شده، اجرای `terraform fmt` (یا `packer fmt`) به صورت محلی را ترجیح دهید.

🛡️آیا می‌توانم رمزهای عبور را اینجا پیست کنم؟

ما اکیداً توصیه می‌کنیم که رمزهای عبور تولیدی را در هیچ ابزار آنلاینی پیست نکنید. حتی با وجود امنیت سرویس و طراحی آن برای پردازش موقت، اعتبارنامه‌های حساس یا با طول عمر طولانی باید فقط در فایل‌های محلی، مخازن رمز یا صندوق‌های CI نگهداری شوند — نه در ابزارهای مرورگر.

🧩آیا قالب‌بندی رفتار پیکربندی را تغییر می‌دهد؟

خیر. قالب‌بند بر روی چیدمان تمرکز دارد: فاصله‌های سفید، تورفتگی و فاصله‌گذاری. بلوک‌های منابع، آرگومان‌ها، عبارات و ارجاعات یکسان باقی می‌مانند، به شرطی که HCL اصلی معتبر باشد.

📄آیا می‌توانم فایل‌های .tfvars را قالب‌بندی کنم؟

بله، به شرطی که فایل .tfvars از نحو HCL استفاده کند. Terraform همچنین از متغیرهای مبتنی بر JSON از طریق `.tfvars.json` پشتیبانی می‌کند؛ آن‌ها از قوانین JSON پیروی می‌کنند و بهتر است توسط یک قالب‌بند JSON یا خود `terraform fmt` پردازش شوند.

⚙️این ابزار چه تفاوتی با `terraform fmt` دارد؟

`terraform fmt` قالب‌بند استاندارد همراه Terraform است و برای توسعه محلی و CI ایده‌آل است. این ابزار وب برای پاکسازی سریع و موردی زمانی که CLI در دسترس ندارید یا می‌خواهید یک قطعه کوتاه را در مرورگر مرتب کنید، طراحی شده است.

🧯چرا قالب‌بندی شکست خورد؟

اکثر شکست‌ها ناشی از خطاهای تجزیه هستند: پرانتز یا براکت بسته نشده، heredocهای نادرست، یا ترکیب tfvars به سبک JSON با نحو HCL. مشکل ساختاری را برطرف کنید (یا از گویش/قالب‌بند صحیح استفاده کنید) و دوباره امتحان کنید.

Pro Tips

CI Tip

از `terraform fmt -check -recursive` در CI استفاده کنید تا از انحراف قالب‌بندی در مخازن بزرگ زیرساخت جلوگیری شود.

Best Practice

از پیست کردن رمزهای عبور یا داده‌های مرتبط با state در ابزارهای آنلاین خودداری کنید؛ مثال‌های پیکربندی را پاکسازی نگه دارید و برای کد زیرساخت واقعی از قالب‌بندهای CLI محلی استفاده کنید.

Best Practice

خطوط جدید انتهایی و تورفتگی‌ها را در ویرایشگر خود نرمال کنید تا فایل‌های Terraform diffهای تمیز و پایدار در تمام پلتفرم‌ها تولید کنند.

Best Practice

یک هوک pre-commit اضافه کنید که `terraform fmt` را اجرا کند تا درخواست‌های pull از قبل قالب‌بندی شده ارسال شوند و گفت‌وگوهای بازبینی بر روی معماری و ریسک متمرکز بمانند.

Additional Resources

Terraform CLI: fmt
Documentation
مروری بر زبان Terraform (HCL2)
Documentation
زبان پیکربندی HashiCorp (HCL) – GitHub
Documentation
Packer CLI: fmt
Documentation

Other Tools