Finch CLI

ابزار خط فرمان finch هر آنچه خارج از یک app در حال اجرا رخ می‌دهد را مدیریت می‌کند: قالب‌بندی پروژه جدید، نصب dependency ها، اجرای سرور توسعه، کامپایل باینری production، و تولید فایل‌های boilerplate. این ابزار دستورات رایج دارت را پوشش می‌دهد و وظایف مختص فینچ را نیز به آن اضافه می‌کند.

مجموعه دومی از دستورات نیز وجود دارد که درون یک app در حال اجرا در دسترس هستند (migrate، route، language، info، به‌علاوه هر دستور سفارشی که ثبت می‌کنید) — این‌ها در Commands پوشش داده شده‌اند و بخشی از finch -h در زیر نیستند. این تمایز مهم است: finch <command> پیش از وجود app شما اجرا می‌شود، درحالی‌که یک دستور app-runtime نمونه واقعی FinchApp را اجرا می‌کند و می‌تواند به route ها، دیتابیس، و پیکربندی app دسترسی داشته باشد. برای دیدن نحوه ارتباط این دو، به Running an Application (بخش «ارسال آرگومان‌ها») مراجعه کنید.

نصب

dart pub global activate finch

دستورات

برای مشاهده تمام دستورات موجود finch -h را اجرا کنید:

finch -h

✔ templates
        Show the list of available templates
✔ create
        Make new project
        -p, --path       Path of the project
        -n, --name       Name of project
        -d, --docker     Use docker
        -t, --template   Project template [simple, example,...]
✔ get
        Get packages of project, (dart pub get)
✔ runner
        Build runner of project, (dart pub run build_runner build)
✔ run
        Run project, (dart run)
        -p, --path       Path of app file
        -a, --args       Arguments for app file
✔ serve
        Serve project with file watcher
        -p, --path         Path of app file
        -a, --args         Arguments for app file
        -tp, --terminalPort Port for the terminal WebSocket that streams
                            console output and accepts remote commands
                            (default: 8282)
✔ build
        Build Project (dart compile exe)
        -c, --cli        Build for cli
        -a, --appPath    Path of app file
        -l, --langPath   Languages path
        -p, --publicPath Public path
        -w, --widgetPath Widgets path
        -e, --envPath    Envitoment file (.env) path
        -o, --output     Output path
        -t, --type       Type of build (zip, exe)
✔ migrate
        Migrate project to new version of Finch
        -c, --create     Create new project and move files
        -n, --name       Name of migration file (only for create option)
        -s, --sqlite     Migrate SQLite files
✔ test
        Unit test of project, (dart test)
        -r, --reporter   Set how to print test results
✔ make:controller
        Make new controller
        -n, --name       Name of controller
        -p, --path       Path of controller (default: ./lib/controllers/)
✔ make:service
        Make new service
        -n, --name       Name of service
        -p, --path       Path of service (default: ./lib/services/)
✔ make:middleware
        Make new middleware
        -n, --name       Name of middleware
        -p, --path       Path of middleware (default: ./lib/middleware/)
✔ make:migration
        Make new migration
        -n, --name       Name of migration
        -p, --path       Path of migration (default: ./lib/migrations/)
        -s, --sqlite     Create migration for SQLite

        -h, --help       Show the help
        -v, --version    Finch Version
        -u, --update     Update Finch

نکته: finch migrate در این سطح بالا فقط از ساخت فایل مهاجرت (--create --name ...) پشتیبانی می‌کند؛ حتی با --sqlite نیز مهاجرت‌های معلق را اعمال نمی‌کند. برای دستوری که واقعاً آن‌ها را اجرا می‌کند، به بخش «اجرای مهاجرت‌ها» در پایین همین صفحه مراجعه کنید.

مثال‌های رایج

ساخت پروژه جدید با قالب example

finch create -n my_app -t example

مشاهده قالب‌های موجود پروژه

finch templates

لیست قالب‌های رسمی (هر یک متکی به یک ریپازیتوری GitHub با نام <template>-finch-docker) را واکشی می‌کند که می‌توانید آن را به finch create -t <key> پاس دهید.

اجرای سرور توسعه با file watcher

دستور serve فایل‌های widget و زبان را رصد می‌کند و آن‌ها را بدون راه‌اندازی مجدد سرور بارگذاری می‌کند:

finch serve

یا با تعیین نقطه ورود:

finch serve -p lib/serve.dart

در پشت صحنه، run/serve برنامه شما را به‌عنوان یک child process اجرا می‌کنند (dart run [--enable-asserts] [vm-service flags] <path> <args>) و یک پرامپت تعاملی کوچک را در ترمینال شما روی آن نگه می‌دارند — کلید r را برای راه‌اندازی مجدد child process، c را برای پاک کردن صفحه، i را برای نمایش نسخه/اطلاعات دارت، h را برای نمایش تاریخچه دستورات، و q را برای خروج فشار دهید. serve علاوه بر این یک WebSocket را روی --terminalPort (پیش‌فرض 8282) باز می‌کند که همین پرامپت را منعکس می‌کند و local debugger در مرورگر به آن متصل می‌شود.

ساخت باینری برای production

finch build -a lib/app.dart -o ./build/app

تولید فایل‌های boilerplate

finch make:controller -n Product
finch make:service -n Payment
finch make:middleware -n RateLimit
finch make:migration -n add_users_table
finch make:migration -n add_users_table -s   # برای SQLite به‌جای MySQL

ساخت فایل مهاجرت

finch migrate --create --name add_users_table
finch migrate --create --name add_users_table --sqlite

این فقط یک فایل مهاجرت خالی و جدید را در مسیر مهاجرت پیکربندی‌شده شما ایجاد می‌کند (برای pathMigrationMySQL/pathMigrationSQLite به Configuration مراجعه کنید) — تغییرات واقعی schema/داده را همان‌طور که در Database Migration شرح داده شده، در آن بنویسید.

اجرای مهاجرت‌ها

اجرای مهاجرت‌ها یک دستور app-runtime است، نه یک flag سطح بالای finch — باید درون FinchApp واقعی شما اجرا شود تا بتواند از اتصال‌های دیتابیس پیکربندی‌شده شما استفاده کند. آن را با پاس دادن --args از طریق finch run/finch serve، یا با فراخوانی مستقیم نقطه ورود برنامه خود با dart run اجرا کنید:

# اعمال مهاجرت‌های MySQL معلق
finch run --args="migrate --init"

# اعمال مهاجرت‌های SQLite معلق
finch run --args="migrate_sqlite --init"

# ترکیب هر دو در یک فراخوانی با --and (همان‌طور که در Dockerfile نمونه استفاده شده)
finch run --args="migrate --init --and migrate_sqlite --init"

# معادل آن، بدون عبور از finch CLI اصلاً
dart run lib/app.dart migrate --init

برای فهرست کامل دستورات app-runtime (route، language، info، و هر دستور سفارشی که ثبت می‌کنید) به Commands و برای نوشتن و rollback کردن مهاجرت‌ها به Database Migration مراجعه کنید.

بررسی مسیرهای ثبت‌شده

route نیز یک دستور app-runtime است، بنابراین به همان روش فراخوانی می‌شود:

# نمای جدولی
finch run --args="route"

# با ستون‌های اضافه (controller، function، middlewares، ...)
finch run --args="route --detail"

# به‌صورت JSON، مثلاً برای انتقال به ابزار دیگر
finch run --args="route --json"