#Command - Dòng lệnh

Trong NocoBase, lệnh (Command) được dùng để thực thi các thao tác liên quan đến ứng dụng hoặc Plugin trong dòng lệnh — ví dụ chạy tác vụ hệ thống, thực thi migration, khởi tạo cấu hình hoặc tương tác với instance ứng dụng đang chạy. Bạn có thể định nghĩa lệnh tùy chỉnh cho Plugin, sau khi đăng ký thông qua đối tượng app, có thể thực thi trong CLI dưới dạng nocobase <command>.

#Loại lệnh

Trong NocoBase, cách đăng ký lệnh chia làm hai loại:

#Lệnh động

Dùng app.command() để định nghĩa lệnh Plugin, chỉ thực thi được sau khi Plugin được bật. Tệp lệnh thường được đặt trong src/server/commands/*.ts của thư mục Plugin.

#Ví dụ

import { Application } from '@nocobase/server';

export default function (app: Application) {
  app
    .command('echo')
    .option('-v, --version')
    .action(async ([options]) => {
      console.log('Hello World!');
      if (options.version) {
        console.log('Current version:', await app.version.get());
      }
    });
}

Trong đó:

• app.command('echo') — Định nghĩa một lệnh tên là echo
• .option('-v, --version') — Thêm tùy chọn cho lệnh
• .action() — Định nghĩa logic thực thi lệnh
• app.version.get() — Lấy phiên bản ứng dụng hiện tại

#Thực thi lệnh

nocobase echo
nocobase echo -v

#Lệnh tĩnh

Đăng ký bằng Application.registerStaticCommand(), lệnh tĩnh không cần bật Plugin cũng có thể thực thi, phù hợp cho các tác vụ cài đặt, khởi tạo, migration hoặc debug. Thường được đăng ký trong phương thức staticImport() của lớp Plugin.

#Ví dụ

import { Application, Plugin } from '@nocobase/server';

export default class PluginHelloServer extends Plugin {
  static staticImport() {
    Application.registerStaticCommand((app: Application) => {
      app
        .command('echo')
        .option('-v, --version')
        .action(async ([options]) => {
          console.log('Hello World!');
          if (options.version) {
            console.log('Current version:', await app.version.get());
          }
        });
    });
  }
}

#Thực thi lệnh

nocobase echo
nocobase echo --version

Trong đó:

• Application.registerStaticCommand() sẽ đăng ký lệnh trước khi ứng dụng được khởi tạo
• Lệnh tĩnh thường được dùng để thực thi các tác vụ toàn cục không liên quan đến trạng thái ứng dụng hoặc Plugin

#Command API

Đối tượng lệnh cung cấp ba phương thức trợ giúp tùy chọn, dùng để kiểm soát context thực thi của lệnh:

#Mô tả cấu hình

• ipc() Thông thường, lệnh sẽ được thực thi trong một instance ứng dụng mới. Sau khi bật ipc(), lệnh sẽ tương tác với instance ứng dụng đang chạy thông qua giao tiếp giữa các tiến trình (IPC), phù hợp cho các lệnh thao tác thời gian thực (ví dụ làm mới cache, gửi thông báo).

• auth() Kiểm tra cấu hình database có khả dụng hay không trước khi thực thi lệnh. Nếu cấu hình database sai hoặc kết nối thất bại, lệnh sẽ không tiếp tục thực thi. Thường được dùng cho các tác vụ liên quan đến ghi hoặc đọc database.

• preload() Tải trước cấu hình ứng dụng trước khi thực thi lệnh, tương đương với việc thực thi app.load(). Phù hợp với các lệnh phụ thuộc vào cấu hình hoặc context Plugin.

Xem thêm các phương thức API tại AppCommand API.

#Ví dụ phổ biến

#Khởi tạo dữ liệu mặc định

app
  .command('init-data')
  .auth()
  .preload()
  .action(async () => {
    const repo = app.db.getRepository('users');
    await repo.create({ values: { username: 'admin' } });
    console.log('Initialized default admin user.');
  });

#Cho instance đang chạy tải lại cache (chế độ IPC)

app
  .command('reload-cache')
  .ipc()
  .action(async () => {
    console.log('Requesting running app to reload cache...');
  });

#Đăng ký tĩnh lệnh cài đặt

Application.registerStaticCommand((app) => {
  app
    .command('setup')
    .action(async () => {
      console.log('Setting up NocoBase environment...');
    });
});

#Liên kết liên quan

• Plugin — Vòng đời Plugin và API cốt lõi
• Tổng quan phát triển server — Tổng quan các module server
• Test — Cách viết kiểm thử Plugin server
• Migration — Migration dữ liệu và script nâng cấp
• Tổng quan phát triển Plugin — Giới thiệu tổng thể về phát triển Plugin
• AppCommand API — Tham chiếu API đầy đủ của AppCommand