diff --git a/docs/menus.ts b/docs/menus.ts index b6a0cfb811..96cbbf77ab 100644 --- a/docs/menus.ts +++ b/docs/menus.ts @@ -72,6 +72,7 @@ export default { }, '/development/guide/ui-router', '/development/guide/settings-center', + '/development/guide/commands', ], }, { diff --git a/docs/zh-CN/development/guide/commands.md b/docs/zh-CN/development/guide/commands.md index 61c515e7b4..5334d3b8db 100644 --- a/docs/zh-CN/development/guide/commands.md +++ b/docs/zh-CN/development/guide/commands.md @@ -1 +1,98 @@ -# Commands +# 命令行 + +## 简介 + +NocoBase Server Application 除了用作 WEB 服务器以外,也是个强大可扩展的 CLI 工具。 + +新建一个 `app.js` 文件,代码如下: + +```ts +const Application = require('@nocobase/server'); + +// 此处省略具体配置 +const app = new Application({/*...*/}); + +app.runAsCLI(); +``` + +以 `runAsCLI()` 方式运行的 app.js 是一个 CLI,在命令行工具就可以像这样操作了: + +```bash +node app.js install # 安装 +node app.js start # 启动 +``` + +为了更好的开发、构建和部署 NocoBase 应用,NocoBase 内置了许多命令,详情查看 [NocoBase CLI](/api/cli) 章节。 + +## 自定义 Command + +NocoBase CLI 的设计思想与 [Laravel Artisan](https://laravel.com/docs/9.x/artisan) 非常相似,都是可扩展的。NocoBase CLI 基于 [commander](https://www.npmjs.com/package/commander) 实现,可以这样扩展 Command: + +```ts +app + .command('echo') + .option('-v, --version'); + .action(async ([options]) => { + console.log('Hello World!'); + if (options.version) { + console.log('Current version:', app.getVersion()); + } + }); +``` + +这个方法定义了以下命令: + +```bash +yarn nocobase echo +# Hello World! +yarn nocobase echo -v +# Hello World! +# Current version: 0.7.4-alpha.7 +``` + +更多 API 细节可参考 [Application.command()](/api/server/application#command) 部分。 + +## 示例 + +### 定义导出数据表的命令 + +如果我们希望把应用的数据表中的数据导出成 JSON 文件,可以定义一个如下的子命令: + +```ts +import path from 'path'; +import * as fs from 'fs/promises'; + +class MyPlugin extends Plugin { + load() { + this.app + .command('export') + .option('-o, --output-dir') + .action(async (options, ...collections) => { + const { outputDir = path.join(process.env.PWD, 'storage') } = options; + await collections.reduce((promise, collection) => promise.then(async () => { + if (!this.db.hasCollection(collection)) { + console.warn('No such collection:', collection); + return; + } + + const repo = this.db.getRepository(collection); + const data = repo.find(); + await fs.writeFile(path.join(outputDir, `${collection}.json`), JSON.stringify(data), { mode: 0o644 }); + }), Promise.resolve()); + }); + } +} +``` + +注册和激活插件之后在命令行调用: + +```bash +mkdir -p ./storage/backups +yarn nocobase export -o ./storage/backups users +``` + +执行后会生成 `./storage/backups/users.json` 文件包含数据表中的数据。 + +## 小结 + +本章所涉及示例代码整合在 [packages/samples/command](https://github.com/nocobase/nocobase/tree/main/packages/samples/command) 包中,可以直接在本地运行,查看效果。 diff --git a/packages/samples/command/README.md b/packages/samples/command/README.md new file mode 100644 index 0000000000..c3e6dad7aa --- /dev/null +++ b/packages/samples/command/README.md @@ -0,0 +1,20 @@ +# Command sample + +## Register + +```ts +yarn pm add sample-command +``` + +## Activate + +```bash +yarn pm enable sample-command +``` + +## Try command + +```bash +mkdir -p ./storage/backups +yarn nocobase export -o ./storage/backups users +``` diff --git a/packages/samples/command/client.d.ts b/packages/samples/command/client.d.ts new file mode 100755 index 0000000000..765db9222a --- /dev/null +++ b/packages/samples/command/client.d.ts @@ -0,0 +1,4 @@ +// @ts-nocheck +export * from './lib/client'; +export { default } from './lib/client'; + diff --git a/packages/samples/command/client.js b/packages/samples/command/client.js new file mode 100755 index 0000000000..238820257c --- /dev/null +++ b/packages/samples/command/client.js @@ -0,0 +1,30 @@ +"use strict"; + +function _getRequireWildcardCache(nodeInterop) { if (typeof WeakMap !== "function") return null; var cacheBabelInterop = new WeakMap(); var cacheNodeInterop = new WeakMap(); return (_getRequireWildcardCache = function _getRequireWildcardCache(nodeInterop) { return nodeInterop ? cacheNodeInterop : cacheBabelInterop; })(nodeInterop); } + +function _interopRequireWildcard(obj, nodeInterop) { if (!nodeInterop && obj && obj.__esModule) { return obj; } if (obj === null || typeof obj !== "object" && typeof obj !== "function") { return { default: obj }; } var cache = _getRequireWildcardCache(nodeInterop); if (cache && cache.has(obj)) { return cache.get(obj); } var newObj = {}; var hasPropertyDescriptor = Object.defineProperty && Object.getOwnPropertyDescriptor; for (var key in obj) { if (key !== "default" && Object.prototype.hasOwnProperty.call(obj, key)) { var desc = hasPropertyDescriptor ? Object.getOwnPropertyDescriptor(obj, key) : null; if (desc && (desc.get || desc.set)) { Object.defineProperty(newObj, key, desc); } else { newObj[key] = obj[key]; } } } newObj.default = obj; if (cache) { cache.set(obj, newObj); } return newObj; } + +var _index = _interopRequireWildcard(require("./lib/client")); + +Object.defineProperty(exports, "__esModule", { + value: true +}); +var _exportNames = {}; +Object.defineProperty(exports, "default", { + enumerable: true, + get: function get() { + return _index.default; + } +}); + +Object.keys(_index).forEach(function (key) { + if (key === "default" || key === "__esModule") return; + if (Object.prototype.hasOwnProperty.call(_exportNames, key)) return; + if (key in exports && exports[key] === _index[key]) return; + Object.defineProperty(exports, key, { + enumerable: true, + get: function get() { + return _index[key]; + } + }); +}); diff --git a/packages/samples/command/package.json b/packages/samples/command/package.json new file mode 100644 index 0000000000..878de2e646 --- /dev/null +++ b/packages/samples/command/package.json @@ -0,0 +1,16 @@ +{ + "name": "@nocobase/plugin-sample-command", + "version": "0.7.4-alpha.7", + "main": "lib/server/index.js", + "dependencies": {}, + "devDependencies": { + "@nocobase/client": "0.7.4-alpha.7", + "@nocobase/server": "0.7.4-alpha.7", + "@nocobase/test": "0.7.4-alpha.7" + }, + "peerDependencies": { + "@nocobase/client": "*", + "@nocobase/server": "*", + "@nocobase/test": "*" + } +} diff --git a/packages/samples/command/server.d.ts b/packages/samples/command/server.d.ts new file mode 100755 index 0000000000..e70edb928a --- /dev/null +++ b/packages/samples/command/server.d.ts @@ -0,0 +1,4 @@ +// @ts-nocheck +export * from './lib/server'; +export { default } from './lib/server'; + diff --git a/packages/samples/command/server.js b/packages/samples/command/server.js new file mode 100755 index 0000000000..d06a7eb92c --- /dev/null +++ b/packages/samples/command/server.js @@ -0,0 +1,30 @@ +"use strict"; + +function _getRequireWildcardCache(nodeInterop) { if (typeof WeakMap !== "function") return null; var cacheBabelInterop = new WeakMap(); var cacheNodeInterop = new WeakMap(); return (_getRequireWildcardCache = function _getRequireWildcardCache(nodeInterop) { return nodeInterop ? cacheNodeInterop : cacheBabelInterop; })(nodeInterop); } + +function _interopRequireWildcard(obj, nodeInterop) { if (!nodeInterop && obj && obj.__esModule) { return obj; } if (obj === null || typeof obj !== "object" && typeof obj !== "function") { return { default: obj }; } var cache = _getRequireWildcardCache(nodeInterop); if (cache && cache.has(obj)) { return cache.get(obj); } var newObj = {}; var hasPropertyDescriptor = Object.defineProperty && Object.getOwnPropertyDescriptor; for (var key in obj) { if (key !== "default" && Object.prototype.hasOwnProperty.call(obj, key)) { var desc = hasPropertyDescriptor ? Object.getOwnPropertyDescriptor(obj, key) : null; if (desc && (desc.get || desc.set)) { Object.defineProperty(newObj, key, desc); } else { newObj[key] = obj[key]; } } } newObj.default = obj; if (cache) { cache.set(obj, newObj); } return newObj; } + +var _index = _interopRequireWildcard(require("./lib/server")); + +Object.defineProperty(exports, "__esModule", { + value: true +}); +var _exportNames = {}; +Object.defineProperty(exports, "default", { + enumerable: true, + get: function get() { + return _index.default; + } +}); + +Object.keys(_index).forEach(function (key) { + if (key === "default" || key === "__esModule") return; + if (Object.prototype.hasOwnProperty.call(_exportNames, key)) return; + if (key in exports && exports[key] === _index[key]) return; + Object.defineProperty(exports, key, { + enumerable: true, + get: function get() { + return _index[key]; + } + }); +}); diff --git a/packages/samples/command/src/client/index.tsx b/packages/samples/command/src/client/index.tsx new file mode 100644 index 0000000000..db735f78df --- /dev/null +++ b/packages/samples/command/src/client/index.tsx @@ -0,0 +1,5 @@ +import React from 'react'; + +export default React.memo((props) => { + return <>{props.children}; +}); diff --git a/packages/samples/command/src/index.ts b/packages/samples/command/src/index.ts new file mode 100644 index 0000000000..7ddad58145 --- /dev/null +++ b/packages/samples/command/src/index.ts @@ -0,0 +1 @@ +export { default } from './server'; diff --git a/packages/samples/command/src/server/actions/.gitkeep b/packages/samples/command/src/server/actions/.gitkeep new file mode 100644 index 0000000000..e69de29bb2 diff --git a/packages/samples/command/src/server/collections/.gitkeep b/packages/samples/command/src/server/collections/.gitkeep new file mode 100644 index 0000000000..e69de29bb2 diff --git a/packages/samples/command/src/server/index.ts b/packages/samples/command/src/server/index.ts new file mode 100644 index 0000000000..e5ba8e482d --- /dev/null +++ b/packages/samples/command/src/server/index.ts @@ -0,0 +1,43 @@ +import path from 'path'; +import * as fs from 'fs/promises'; + +import { InstallOptions, Plugin } from '@nocobase/server'; + +export class CommandPlugin extends Plugin { + getName(): string { + return this.getPackageName(__dirname); + } + + beforeLoad() { + // TODO + } + + async load() { + this.app + .command('export') + .option('-o, --output-dir') + .action(async (options, ...collections) => { + const { outputDir = path.join(process.env.PWD, 'storage') } = options; + await collections.reduce((promise, collection) => promise.then(async () => { + if (!this.db.hasCollection(collection)) { + console.warn('No such collection:', collection); + return; + } + + const repo = this.db.getRepository(collection); + const data = repo.find(); + await fs.writeFile(path.join(outputDir, `${collection}.json`), JSON.stringify(data), { mode: 0o644 }); + }), Promise.resolve()); + }); + } + + async disable() { + // this.app.resourcer.removeResource('testHello'); + } + + async install(options: InstallOptions) { + // TODO + } +} + +export default CommandPlugin; diff --git a/packages/samples/command/src/server/models/.gitkeep b/packages/samples/command/src/server/models/.gitkeep new file mode 100644 index 0000000000..e69de29bb2 diff --git a/packages/samples/command/src/server/repositories/.gitkeep b/packages/samples/command/src/server/repositories/.gitkeep new file mode 100644 index 0000000000..e69de29bb2