نام (NAME)

buf-generate - تولید کد با استفاده از افزونه‌های protoc

خلاصه دستور (SYNOPSIS)

buf generate [flags]

توضیحات (DESCRIPTION)

این دستور از یک فایل الگوی با ساختار زیر استفاده می‌کند:

# buf.gen.yaml
# نسخه الگوی تولید کد.
# مقادیر معتبر عبارتند از v1beta1، v1 و v2.
# الزامی.
version: v2
# هنگامی که clean برابر با true باشد، دایرکتوری‌ها، فایل‌های zip و/یا فایل‌های jar مشخص‌شده در
# فیلد "out" برای همه افزونه‌ها پیش از اجرای تولید کد حذف می‌شوند. پیش‌فرض false است.
# اختیاری.
clean: true
# افزونه‌هایی که باید اجرا شوند.
# الزامی.
plugins:
    # استفاده از افزونه میزبانی‌شده در buf.build/protocolbuffers/go در نسخه v1.28.1.
    # در صورت عدم ذکر نسخه، از آخرین نسخه افزونه استفاده می‌شود.
    # یکی از مقادیر "remote" ،"local" و "protoc_builtin" الزامی است.
  - remote: buf.build/protocolbuffers/go:v1.28.1
    # دایرکتوری خروجی نسبی.
    # الزامی.
    out: gen/go
    # بازبینی (revision) افزونه راه دور برای استفاده؛ شماره ترتیبی که Buf
    # هنگام بازسازی یا بسته‌بندی مجدد افزونه آن را افزایش می‌دهد.
    revision: 4
    # گزینه‌های ارائه‌شده به افزونه.
    # می‌تواند یک رشته منفرد یا فهرستی از رشته‌ها باشد.
    # اختیاری.
    opt: paths=source_relative
    # آیا برای فایل‌های واردشده (imported) نیز کد تولید شود یا خیر.
    # اختیاری.
    include_imports: false
    # آیا برای انواع شناخته‌شده (Well-Known Types) کد تولید شود یا خیر.
    # اختیاری.
    include_wkt: false
    # تنها این انواع را برای این افزونه لحاظ کن.
    # اختیاری.
    types:
      - "foo.v1.User"
    # این انواع را برای این افزونه مستثنی کن.
    # اختیاری.
    exclude_types:
      - "buf.validate.oneof"
      - "buf.validate.message"
      - "buf.validate.field""
    # نام یک افزونه محلی اگر در "${PATH}" قابل کشف باشد یا مسیر آن در سیستم فایل.
  - local: protoc-gen-es
    out: gen/es
    include_imports: true
    include_wkt: true
    # فراخوانی کامل یک افزونه محلی می‌تواند به صورت یک فهرست مشخص شود.
  - local: ["go", "run", "path/to/plugin.go"]
    out: gen/plugin
    # راهبرد تولید کد مورد استفاده. دو گزینه وجود دارد:
    #
    # 1. "directory"
    #
    #   این گزینه موجب می‌شود buf فایل‌های ورودی را بر اساس دایرکتوری تفکیک کند و فراخوانی‌های افزونه را به صورت موازی انجام دهد.
    #   این تقریباً معادل هم‌روندی عبارت زیر است:
    #
    #     for dir in $(find . -name '*.proto' -print0 | xargs -0 -n1 dirname | sort | uniq); do
    #       protoc -I . $(find "${dir}" -name '*.proto')
    #     done
    #
    #   تقریباً تمام افزونه‌های Protobuf یا به این نیاز دارند یا با آن کار می‌کنند،
    #   و این مقدار توصیه‌شده و پیش‌فرض است.
    #
    # 2. "all"
    #
    #   این گزینه موجب می‌شود buf یک فراخوانی منفرد با تمام فایل‌های ورودی انجام دهد.
    #   این تقریباً معادل دستور زیر است:
    #
    #     protoc -I . $(find . -name '*.proto')
    #
    #   این برای برخی افزونه‌ها که انتظار دارند همه فایل‌ها به یک‌باره به آن‌ها داده شوند لازم است.
    #   همچنین این تنها راهبرد برای افزونه‌های راه دور (remote) است.
    #
    # در صورت حذف، "directory" استفاده می‌شود. اکثر کاربران نیازی به تنظیم این گزینه ندارند.
    # اختیاری.
    strategy: directory
    # "protoc_builtin" افزونه‌ای را مشخص می‌کند که همراه با protoc ارائه می‌شود، بدون پیشوند "-protoc-gen".
  - protoc_builtin: java
    out: gen/java
    # مسیر به protoc. در صورت عدم تعیین، نسخه نصب‌شده protoc در "${PATH}" استفاده می‌شود.
    # اختیاری.
    protoc_path: path/to/protoc
# حالت مدیریت‌شده (Managed mode) گزینه‌های فایل و/یا فیلد را به صورت بلادرنگ تغییر می‌دهد.
managed:
  # فعال‌سازی حالت مدیریت‌شده.
  enabled: true
  # هر قاعده بازنویسی (override rule) یک گزینه، مقدار آن گزینه و
  # در صورت تمایل فایل‌ها/فیلدهایی را که بازنویسی روی آن‌ها اعمال می‌شود مشخص می‌کند.
  #
  # گزینه‌های فایل پذیرفته‌شده عبارتند از:
  #  - java_package
  #  - java_package_prefix
  #  - java_package_suffix
  #  - java_multiple_files
  #  - java_outer_classname
  #  - java_string_check_utf8
  #  - go_package
  #  - go_package_prefix
  #  - optimize_for
  #  - csharp_namespace
  #  - csharp_namespace_prefix
  #  - ruby_package
  #  - ruby_package_suffix
  #  - objc_class_prefix
  #  - php_namespace
  #  - php_metadata_namespace
  #  - php_metadata_namespace_suffix
  #  - cc_enable_arenas
  #
  # یک قاعده بازنویسی می‌تواند روی یک گزینه فیلد اعمال شود.
  # گزینه‌های فیلد پذیرفته‌شده عبارتند از:
  #  - jstype
  #
  # اگر چندین بازنویسی برای یک گزینه یکسان روی یک فایل یا فیلد اعمال شود،
  # آخرین قاعده اثرگذار خواهد بود.
  # اختیاری.
  override:
      # تنظیم "go_package_prefix" به "foo/bar/baz" برای تمام فایل‌ها.
    - file_option: go_package_prefix
      value: foo/bar/baz
      # تنظیم "java_package_prefix" به "net.foo" برای فایل‌های موجود در "buf.build/foo/bar".
    - file_option: java_package_prefix
      value: net.foo
      module: buf.build/foo/bar
      # تنظیم "java_package_prefix" به "dev" برای "file.proto".
      # این مقدار "net.foo" را برای "file.proto" از قاعده قبلی بازنویسی می‌کند.
    - file_option: java_package_prefix
      value: dev
      module: buf.build/foo/bar
      path: file.proto
      # تنظیم "go_package" به "x/y/z" برای تمام فایل‌های موجود در دایرکتوری "x/y/z".
    - file_option: go_package
      value: foo/bar/baz
      path: x/y/z
      # تنظیم "jstype" فیلد به "JS_NORMAL".
    - field_option: jstype
      value: JS_STRING
      field: foo.v1.Bar.baz
  # غیرفعال کردن حالت مدیریت‌شده تحت شرایط خاص.
  # اولویت بالاتری نسبت به "overrides" دارد.
  # اختیاری.
  disable:
      # هیچ گزینه‌ای را برای فایل‌های موجود در این پیمانه تغییر نده.
    - module: buf.build/googleapis/googleapis
      # هیچ گزینه‌ای را برای این فایل تغییر نده.
    - module: buf.build/googleapis/googleapis
      path: foo/bar/file.proto
      # مقدار "java_multiple_files" را برای هیچ فایلی تغییر نده.
    - file_option: java_multiple_files
      # مقدار "csharp_namespace" را برای فایل‌های موجود در این پیمانه تغییر نده.
    - module: buf.build/acme/weather
      file_option: csharp_namespace
# ورودی‌هایی که باید برای آن‌ها کد تولید شود.
# ورودی‌های اینجا در صورتی که ورودی به عنوان آرگومان خط فرمان مشخص شود نادیده گرفته می‌شوند.
# هر ورودی یکی از مقادیر "directory" ،"git_repo" ،"module" ،"tarball" ،"zip_archive" ،
# "proto_file" ،"binary_image" ،"json_image" ،"text_image" و "yaml_image" است.
# اختیاری.
inputs:
    # مسیر به یک دایرکتوری.
  - directory: x/y/z
    # نشانی وب یک مخزن گیت.
  - git_repo: https://github.com/acme/weather.git
    # شاخه‌ای که باید کلون شود.
    # اختیاری.
    branch: dev
    # زیردایرکتوری در مخزن برای استفاده.
    # اختیاری.
    subdir: proto
    # عمق کلون کردن.
    # اختیاری.
    depth: 30
    # نشانی وب یک پیمانه BSR.
  - module: buf.build/acme/weather
    # تنها برای این انواع کد تولید کن.
    # اختیاری.
    types:
      - "foo.v1.User"
      - "foo.v1.UserService"
    # این انواع را مستثنی کن.
    # اختیاری.
    exclude_types:
      - "buf.validate"
    # تنها برای فایل‌های موجود در این مسیرها کد تولید کن.
    # در صورت خالی بودن، شامل تمام مسیرها می‌شود.
    paths:
      - a/b/c
      - a/b/d
    # برای فایل‌های موجود در این مسیرها کد تولید نکن.
    exclude_paths:
      - a/b/c/x.proto
      - a/b/d/y.proto
    # نشانی وب یا مسیر به یک فایل tarball.
  - tarball: a/b/x.tar.gz
    # مسیر نسبی درون بایگانی جهت استفاده به عنوان دایرکتوری پایه.
    # اختیاری.
    subdir: proto
    # طرح فشرده‌سازی که در صورت عدم تعیین از پسوند فایل برداشت می‌شود.
    # پسوندهای ".tgz" و ".tar.gz" به طور خودکار از Gzip استفاده می‌کنند.
    # پسوند ".tar.zst" به طور خودکار از Zstandard استفاده می‌کند.
    # اختیاری.
    compression: gzip
    # خواندن در مسیر نسبی و حذف تعدادی از اجزای مسیر.
    # اختیاری.
    strip_components: 2
    # نشانی وب یا مسیر به یک بایگانی zip.
  - zip_archive: https://github.com/googleapis/googleapis/archive/master.zip
    # تعداد دایرکتوری‌هایی که باید حذف شوند.
    # اختیاری.
    strip_components: 1
    # مسیر به یک فایل proto خاص.
  - proto_file: foo/bar/baz.proto
    # آیا برای فایل‌های هم‌پکیج نیز کد تولید شود یا خیر، پیش‌فرض false است.
    # اختیاری.
    include_package_files: true
    # تصویر Buf در قالب باینری.
    # سایر قالب‌های تصویر عبارتند از "yaml_image" ،"text_image" و "json_image".
  - binary_image: image.binpb.gz
    # طرح فشرده‌سازی فایل تصویر که در صورت عدم تعیین از پسوند فایل برداشت می‌شود.
    # اختیاری.
    compression: gzip

به عنوان مثال، در اینجا یک نمونه معمولی از "buf.gen.yaml" برای go و grpc آورده شده است، با این فرض که "protoc-gen-go" و "protoc-gen-go-grpc" در "$PATH" شما قرار دارند:

# buf.gen.yaml
version: v2
plugins:
  - local: protoc-gen-go
    out: gen/go
    opt: paths=source_relative
  - local: protoc-gen-go-grpc
    out: gen/go
    opt:
      - paths=source_relative
      - require_unimplemented_servers=false

به طور پیش‌فرض، دستور buf generate به دنبال فایلی با این ساختار به نام "buf.gen.yaml" در دایرکتوری جاری شما می‌گردد. این فایل را می‌توان به عنوان الگویی برای مجموعه‌ای از افزونه‌ها که می‌خواهید فراخوانی کنید در نظر گرفت.

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

استفاده از buf.gen.yaml به عنوان الگو، دایرکتوری جاری به عنوان ورودی:

$ buf generate

مشابه مقادیر پیش‌فرض (الگوی "buf.gen.yaml"، دایرکتوری جاری به عنوان ورودی):

$ buf generate --template buf.gen.yaml .

پرچم --template داده‌های YAML یا JSON را نیز به عنوان ورودی می‌پذیرد، بنابراین می‌توان بدون فایل نیز از آن استفاده کرد:

$ buf generate --template '{"version":"v2","plugins":[{"local":"protoc-gen-go","out":"gen/go"}]}'

دانلود مخزن و تولید کدهای پایه طبق الگوی bar.yaml:

$ buf generate --template bar.yaml https://github.com/foo/bar.git

تولید خروجی در دایرکتوری bar/ با اضافه کردن پیشوند bar/ به دستورالعمل‌های out در الگو:

$ buf generate --template bar.yaml -o bar https://github.com/foo/bar.git

مسیرها در الگو و پرچم -o به صورت نسبی نسبت به دایرکتوری جاری تفسیر می‌شوند، بنابراین می‌توانید فایل‌های الگوی خود را در هر مکانی قرار دهید.

اگر تنها می‌خواهید کدهای پایه را برای زیرمجموعه‌ای از ورودی‌های خود تولید کنید، می‌توانید این کار را از طریق --path انجام دهید، به عنوان مثال:

تنها برای فایل‌های موجود در دایرکتوری‌های proto/foo و proto/bar تولید کد کن:

$ buf generate --path proto/foo --path proto/bar

تنها برای فایل‌های proto/foo/foo.proto و proto/foo/bar.proto تولید کد کن:

$ buf generate --path proto/foo/foo.proto --path proto/foo/bar.proto

تنها برای فایل‌های موجود در دایرکتوری proto/foo روی مخزن گیت تولید کد کن:

$ buf generate --template buf.gen.yaml https://github.com/foo/bar.git --path proto/foo

توجه داشته باشید که تمام مسیرها باید در یک پیمانه یکسان قرار داشته باشند. برای نمونه، اگر پیمانه‌ای در "proto" دارید، نمی‌توانید "--path proto"; را مشخص کنید، اما "--path proto/foo"; مجاز است زیرا "proto/foo" درون "proto" قرار دارد.

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

نقاط درج (Insertion points) به ترتیبی که افزونه‌ها در الگو مشخص شده‌اند پردازش می‌شوند.

گزینه‌ها (OPTIONS)

--clean[=false] پیش از تولید، دایرکتوری‌ها، فایل‌های jar یا فایل‌های zip را که افزونه‌ها در آن‌ها می‌نویسند حذف کن. امکان پاکسازی دارایی‌های موجود بدون نیاز به فراخوانی rm -rf را فراهم می‌کند

--config="" فایل buf.yaml یا داده‌های مورد استفاده برای پیکربندی

--disable-symlinks[=false] عدم دنبال کردن پیوندهای نمادین هنگام خواندن منابع یا پیکربندی از سیستم فایل محلی به طور پیش‌فرض، پیوندهای نمادین در این CLI دنبال می‌شوند، اما در Buf Schema Registry هرگز دنبال نمی‌شوند

--error-format="text" قالب خطاهای ساخت که در stderr چاپ می‌شوند. باید یکی از مقادیر [text,json,msvs,junit,github-actions,gitlab-code-quality] باشد

--exclude-path=[] مستثنی کردن فایل‌ها یا دایرکتوری‌های خاص، مثلاً "proto/a/a.proto"، "proto/a" در صورت تعیین چندباره، اجتماع آن‌ها در نظر گرفته می‌شود

--exclude-type=[] انواعی (بسته، پیام، شمارشگر، افزونه، سرویس، متد) که باید از این تصویر مستثنی شوند. هنگام تعیین، تصویر حاصل توصیف‌کننده‌های انواع مشخص‌شده را حذف کرده و هرگونه ارجاع به آن‌ها را برمی‌دارد، مانند فیلدهایی که از نوع یک پیام یا شمارشگر مستثنی‌شده هستند، یا گزینه‌های سفارشی متصل به یک افزونه مستثنی‌شده. نام یک نوع ممکن است با ".**" پایان یابد تا عنصر نام‌برده و هر آنچه در زیر آن قرار دارد، مانند یک بسته و تمام زیربسته‌های آن، به صورت بازگشتی مستثنی شوند. تصویر ابتدا با انواع لحاظ‌شده فیلتر می‌شود و سپس با انواع مستثنی‌شده کاهش بیشتری می‌یابد. استفاده از این پرچم بر فایل buf.gen.yaml تقدم دارد

-h, --help[=false] راهنما برای generate

--include-imports[=false] تولید تمام موارد واردشده به جز انواع شناخته‌شده (Well-Known Types)

--include-wkt[=false] تولید انواع شناخته‌شده (Well-Known Types). بدون تنظیم include-imports-- بر روی true نمی‌تواند روی true تنظیم شود

-o, --output="." دایرکتوری پایه برای تولید خروجی. این به دایرکتوری‌های out در الگوی تولید کد پیشوند زده می‌شود

--path=[] محدود کردن به فایل‌ها یا دایرکتوری‌های خاص، مثلاً "proto/a/a.proto"، "proto/a" در صورت تعیین چندباره، اجتماع آن‌ها در نظر گرفته می‌شود

--template="" فایل الگوی تولید یا داده‌های مورد استفاده. باید در قالب YAML یا JSON باشد

--type=[] انواعی (بسته، پیام، شمارشگر، افزونه، سرویس، متد) که باید در این تصویر گنجانده شوند. در صورت تعیین، تصویر حاصل تنها شامل توصیف‌کننده‌هایی برای شرح انواع درخواستی خواهد بود. نام یک نوع ممکن است با ".**" پایان یابد تا عنصر نام‌برده و تمام موارد درون آن، مانند یک بسته و تمام زیربسته‌های آن، به طور بازگشتی لحاظ شوند. استفاده از این پرچم بر فایل buf.gen.yaml تقدم دارد

گزینه‌های به ارث رسیده از دستورات والد (OPTIONS INHERITED FROM PARENT COMMANDS)

--debug[=false] فعال‌سازی ثبت وقایع خطایابی

--log-format="color" قالب ثبت وقایع [text,color,json]

--timeout=0s مدت زمان تا پایان مهلت زمانی؛ تعیین 0 به معنی عدم پایان مهلت است

همچنین ببینید (SEE ALSO)

buf(1)

تاریخچه (HISTORY)

2026-07-17 تولید خودکار توسط spf13/cobra