796e73ae5a
* refactor(doc): change to new structure * docs: add database docs * docs: add collection docs * docs: add db field examples * docs(api): fix filename and menu path * docs: add database docs * docs: add db operators doc * docs: add resourcer menu * docs: add resourcer docs * docs: fix api docs * docs: refactor api menu structure * feat: update docs (#830) * feat: updates * feat: update docs * chore: ignore docs from ci Co-authored-by: Junyi <mytharcher@users.noreply.github.com> Co-authored-by: mytharcher <mytharcher@gmail.com> * docs: add database methods docs * docs: add missed api * docs: fix api docs * feat: update development docs (#833) * feat: update development docs * feat: update docs * feat: update docs * docs: add first plugin example (#834) * feat: update docs * feat: update docs * docs: fix typo Co-authored-by: chenos <chenlinxh@gmail.com>
268 lines
7.5 KiB
Markdown
268 lines
7.5 KiB
Markdown
# Application
|
||
|
||
NocoBase 的应用程序类，服务端的应用进程将实例化该类并启动。因为继承自 [Koa](https://koajs.com/)，所以也可以直接调用 Koa 实例的方法。
|
||
|
||
同时因为 Koa 还继承自 [EventEmitter](https://nodejs.org/api/events.html#events_class_eventemitter)，所以也可以通过 `app.on` 监听事件。
|
||
|
||
## 构造函数
|
||
|
||
**签名**
|
||
|
||
* `constructor(options: ApplicationOptions)`
|
||
|
||
创建一个应用实例。
|
||
|
||
**参数**
|
||
|
||
| 参数名 | 类型 | 默认值 | 描述 |
|
||
| --- | --- | --- | --- |
|
||
| `options.database` | `IDatabaseOptions` or `Database` | `{}` | 数据库配置 |
|
||
| `options.resourcer` | `ResourcerOptions` | `{}` | 资源路由配置 |
|
||
| `options.cors` | `CorsOptions` | `{}` | 跨域配置，参考 [@koa/cors](https://npmjs.com/package/@koa/cors) |
|
||
| `options.dataWrapping` | `boolean` | `true` | 是否包装响应数据，`true` 则将把通常的 `ctx.body` 包装为 `{ data, meta }` 的结构。 |
|
||
| `options.registerActions` | `boolean` | `true` | 是否注册默认的 action |
|
||
| `options.i18n` | `I18nOptions` | `{}` | 国际化配置，参考 [i18next](https://www.npmjs.com/package/i18next) |
|
||
| `options.plugins` | `PluginConfiguration[]` | `[]` | 默认启用的插件配置 |
|
||
|
||
**示例**
|
||
|
||
```ts
|
||
import Application from '@nocobase/server';
|
||
|
||
const app = new Application({
|
||
database: {
|
||
dialect: 'mysql',
|
||
host: 'localhost',
|
||
port: 3306,
|
||
username: 'root',
|
||
password: '123456',
|
||
database: 'test',
|
||
},
|
||
resourcer: {
|
||
prefix: '/api',
|
||
},
|
||
cors: {
|
||
origin: '*',
|
||
}
|
||
});
|
||
```
|
||
|
||
## 实例成员
|
||
|
||
### `db`
|
||
|
||
应用初始化自动创建的数据库实例，通过 `@nocobase/database` 封装的数据库访问类，相关方法参考 [Database](./database)。
|
||
|
||
### `resourcer`
|
||
|
||
应用初始化自动创建的资源路由管理实例，相关方法参考 [Resourcer](./resourcer)。
|
||
|
||
### `cli`
|
||
|
||
应用初始化自动创建的命令行工具实例，相关方法参考 [CLI](../cli)。
|
||
|
||
### `acl`
|
||
|
||
应用初始化自动创建的访问控制表实例，相关方法参考 [ACL](./acl)。
|
||
|
||
### `i18n`
|
||
|
||
应用初始化自动创建的国际化工具实例，相关方法参考 [I18n](./i18n)。
|
||
|
||
### `appManager`
|
||
|
||
应用初始化自动创建的应用管理实例，相关方法参考 [AppManager](./app-manager)。
|
||
|
||
### `pm`
|
||
|
||
应用初始化自动创建的插件管理器实例，相关方法参考 [PluginManager](./plugin-manager)。
|
||
|
||
### `context`
|
||
|
||
继承自 koa 的 context，可以通过 `app.context` 访问，用于向每个请求注入上下文可访问的内容。参考 [Koa Context](https://koajs.com/#app-context)。
|
||
|
||
NocoBase 默认对 context 注入了以下成员，可以在请求处理函数中直接使用：
|
||
|
||
| 变量名 | 类型 | 描述 |
|
||
| --- | --- | --- |
|
||
| `ctx.app` | `Application` | 应用实例 |
|
||
| `ctx.db` | `Database` | 数据库实例 |
|
||
| `ctx.resourcer` | `Resourcer` | 资源路由管理器实例 |
|
||
| `ctx.action` | `Action` | 资源操作相关对象实例 |
|
||
| `ctx.i18n` | `I18n` | 国际化实例 |
|
||
| `ctx.getBearerToken()` | `Function` | 获取请求头中的 bearer token |
|
||
|
||
## 实例方法
|
||
|
||
### `getVersion()`
|
||
|
||
获取当前版本。
|
||
|
||
**签名**
|
||
|
||
* `getVersion(): string`
|
||
|
||
**示例**
|
||
|
||
```ts
|
||
console.log(app.getVersion()); // 0.7.4-alpha.7
|
||
```
|
||
|
||
### `plugin()`
|
||
|
||
向应用中注册插件的快捷方法，等同于 `app.pm.add()`，参考 [PluginManager](./plugin-manager#add)。
|
||
|
||
### `loadPluginConfig()`
|
||
|
||
批量注册插件与默认参数。
|
||
|
||
**签名**
|
||
|
||
* `loadPluginConfig(pluginsConfigurations: PluginConfiguration[]): void`
|
||
|
||
**参数**
|
||
|
||
| 参数名 | 类型 | 默认值 | 描述 |
|
||
| --- | --- | --- | --- |
|
||
| `pluginsConfigurations[]` | `string` | - | 插件的 npm 包名 |
|
||
| `pluginsConfigurations[]` | `[string, any]` | - | 插件的 npm 包名与默认参数 |
|
||
|
||
### `getPlugin()`
|
||
|
||
获取已注册的插件实例，等同于 `app.pm.get(name)`，参考 [PluginManager](./plugin-manager#get)。
|
||
|
||
### `use()`
|
||
|
||
注册应用级中间件的快捷方法，等同于 `koa.use()`。
|
||
|
||
### `on()`
|
||
|
||
订阅应用级事件，主要与生命周期相关，等同于 `eventEmitter.on()`。所有可订阅事件参考 [事件](#事件)。
|
||
|
||
### `collection()`
|
||
|
||
向数据库注册数据表模型的快捷方法，等同于 `app.db.collection()`，参考 [Database](./database#collection)。
|
||
|
||
### `resource()`
|
||
|
||
向资源路由管理器注册资源的快捷方法，等同于 `app.resourcer.define()`，参考 [Resourcer](./resourcer#define)。
|
||
|
||
### `actions()`
|
||
|
||
向资源路由管理器注册 action 的快捷方法，等同于 `app.resourcer.registerActions()`，参考 [Resourcer](./resourcer#registerActions)。
|
||
|
||
### `command()`
|
||
|
||
向命令行工具注册命令的快捷方法，等同于 `app.cli.command()`，参考 [cli](./cli)。
|
||
|
||
### `load()`
|
||
|
||
应用生命周期方法，用于加载所有已注册的插件，等同于 `app.pm.load()`，参考 [PluginManager](./plugin-manager#load)。
|
||
|
||
**签名**
|
||
|
||
* `async load(): Promise<void>`
|
||
|
||
### `start()`
|
||
|
||
启动应用，如果配置了监听的端口，将启动监听，之后应用即可接受 HTTP 请求。
|
||
|
||
**签名**
|
||
|
||
* `async start(options: StartOptions): Promise<void>`
|
||
|
||
**参数**
|
||
|
||
| 参数名 | 类型 | 默认值 | 描述 |
|
||
| --- | --- | --- | --- |
|
||
| `options.listen?` | `ListenOptions` | `{}` | HTTP 监听参数对象 |
|
||
| `options.listen.port?` | `number` | 13000 | 端口 |
|
||
| `options.listen.host?` | `string` | `'localhost'` | 域名 |
|
||
|
||
**事件**
|
||
|
||
`start()` 调用会触发两个事件：
|
||
|
||
* `'beforeStart'`：在应用启动前触发。
|
||
* `'afterStart'`：在应用启动后触发。
|
||
|
||
### `stop()`
|
||
|
||
停止应用，如果应用正在监听，将停止监听，并关闭数据库连接。
|
||
|
||
**签名**
|
||
|
||
* `async stop(options: any): Promise<void>`
|
||
|
||
| 参数名 | 类型 | 默认值 | 描述 |
|
||
| --- | --- | --- | --- |
|
||
| `options?` | `any` | - | 将透传至停止事件的参数 |
|
||
|
||
**事件**
|
||
|
||
`stop()` 调用会触发两个事件：
|
||
|
||
* `'beforeStop'`：在应用停止前触发。
|
||
* `'afterStop'`：在应用停止后触发。
|
||
|
||
### `destroy()`
|
||
|
||
销毁并停止应用，包含 `stop()` 的调用。
|
||
|
||
**事件**
|
||
|
||
`destroy()` 调用会触发两个事件：
|
||
|
||
* `'beforeDestroy'`：在应用销毁前触发。
|
||
* `'afterDestroy'`：在应用销毁后触发。
|
||
|
||
插件相关的销毁事件可以基于该事件进行扩展。
|
||
|
||
### `install()`
|
||
|
||
应用初始化安装调用接口，用于安装应用的基础数据，包括：
|
||
|
||
* 同步已通过 `db.collection()` 和 `db.import()` 注入的数据库表结构到数据库。
|
||
* 调用所有已注册插件实例的 `install()` 方法，执行相应安装过程。
|
||
|
||
**事件**
|
||
|
||
* `'beforeInstall'`：在应用安装前触发。
|
||
* `'afterInstall'`：在应用安装后触发。
|
||
|
||
### `upgrade()`
|
||
|
||
应用调用接口，当更新新版本代码后通过命令行工具调用，用于执行应用的升级过程，包括：
|
||
|
||
* 数据库迁移工具执行。
|
||
|
||
**事件**
|
||
|
||
* `'beforeUpgrade'`：在应用升级前触发。
|
||
* `'afterUpgrade'`：在应用升级后触发。
|
||
|
||
## 事件
|
||
|
||
应用生命周期会触发相应事件，扩展开发可以基于这些事件进行。
|
||
|
||
| 事件名称 | 是否异步 | 描述 |
|
||
| --- | --- | --- |
|
||
| `'beforeInstall'` | 是 | 安装前触发 |
|
||
| `'afterInstall'` | 是 | 安装后触发 |
|
||
| `'beforeUpgrade'` | 是 | 升级前触发 |
|
||
| `'afterUpgrade'` | 是 | 升级后触发 |
|
||
| `'beforeStart'` | 是 | 启动前触发 |
|
||
| `'afterStart'` | 是 | 启动后触发 |
|
||
| `'beforeStop'` | 是 | 停止前触发 |
|
||
| `'afterStop'` | 是 | 停止后触发 |
|
||
| `'beforeDestroy'` | 是 | 销毁前触发 |
|
||
| `'afterDestroy'` | 是 | 销毁后触发 |
|
||
|
||
**示例**
|
||
|
||
```ts
|
||
app.on('beforeStart', async () => {
|
||
console.log('app before start');
|
||
});
|
||
```
|