mirror of
https://gitee.com/nocobase/nocobase.git
synced 2025-05-06 22:19:25 +08:00
1052 lines
18 KiB
Markdown
1052 lines
18 KiB
Markdown
---
|
||
title: '@nocobase/database'
|
||
order: 1
|
||
# toc: menu
|
||
group:
|
||
order: 1
|
||
title: 核心库
|
||
---
|
||
|
||
# @nocobase/database
|
||
|
||
## 介绍
|
||
|
||
用于配置数据表（Table），提供数据操作（Model），可单独使用。核心主要有两个东西：
|
||
|
||
- Table：描述数据的类型、结构和关系
|
||
- Model：数据库操作
|
||
|
||
<Alert title="Table 和 Model 的关系" type="warning">
|
||
Model 是动态的，由 Table 初始化，一般并不需要单独配置。Model 目前已经适配了 Sequelize.Model，如果需要，后续还可以适配 Mongoose.Model 等。Table 也可以更进一步抽象，提供更灵活的适配方法。
|
||
</Alert>
|
||
|
||
## 安装
|
||
|
||
```bash
|
||
yarn add @nocobase/database
|
||
```
|
||
|
||
## Usage
|
||
|
||
```ts
|
||
import Database from '@nocobase/database';
|
||
|
||
const db = new Database({
|
||
// 省略配置信息
|
||
});
|
||
|
||
const table = db.table({
|
||
name: 'posts',
|
||
fields: [
|
||
{ type: 'string', name: 'title' },
|
||
],
|
||
});
|
||
|
||
table.addField({ type: 'text', name: 'content' });
|
||
|
||
await table.sync();
|
||
|
||
const Post = db.getModel('posts');
|
||
|
||
const post = await Post.create({
|
||
title: '这是标题',
|
||
content: '这是内容',
|
||
});
|
||
```
|
||
|
||
## Field Types
|
||
|
||
<Alert title="注意" type="warning">
|
||
在 NocoBase 里，Field Type 表示字段的数据类型。
|
||
</Alert>
|
||
|
||
在 JSON 里，数据有六种基本类型：
|
||
|
||
- boolean
|
||
- string
|
||
- number
|
||
- object
|
||
- array
|
||
- null
|
||
|
||
其中表示数据的结构有两种：
|
||
|
||
- object
|
||
- array
|
||
|
||
两种结构可以内嵌，再结合其他数据类型，可以呈现出无数种结构化的数据。JSON 数据是可以直接储存的，但是可能会产生冗余，所以在关系型数据库的设计规范中，会根据需要把 object 或 array 的数据存放在另一张表里，然后通过主外键字段建立关联。在关系型数据库里，数据有四种基本关系：
|
||
|
||
- O2O/hasOne - 一对一
|
||
- O2M/hasMany - 一对多
|
||
- M2O/belongsTo - 多对一
|
||
- M2M/belongsToMany - 多对多
|
||
- Polymorphic - 多态（反模式）
|
||
|
||
字段的数据类型（Field Type）也由此扩展而来，以下为 JSON 类型与字段数据类型的对应关系：
|
||
|
||
- boolean：boolean
|
||
- string：string、text、time、date
|
||
- number：integer、float、double、decimal、real
|
||
- object：hasOne、belongsTo
|
||
- array：hasMany、belongsToMany
|
||
- null：不填写时为空，需要区分空字符串
|
||
- json：一种特殊的数据类型，即使是根节点也可以存任意类型数据
|
||
|
||
除此之外，字段类型还提供了 virtual 的情况，是一种虚拟字段
|
||
|
||
### boolean
|
||
|
||
布尔型
|
||
|
||
### integer
|
||
|
||
整型
|
||
|
||
### float
|
||
|
||
单精度浮点型
|
||
|
||
### double
|
||
|
||
双精度浮点型
|
||
|
||
### decimal
|
||
|
||
货币类型
|
||
|
||
### string
|
||
|
||
字符串
|
||
|
||
### text
|
||
|
||
长文本
|
||
|
||
### date
|
||
|
||
日期，包括时间
|
||
|
||
### dateonly
|
||
|
||
日期，不包括时间
|
||
|
||
### time
|
||
|
||
时间
|
||
|
||
### json <Badge>待完善</Badge>
|
||
|
||
JSON 是个特殊的数据类型，在不同数据库里有所不同，目前只兼容了 PostgreSQL 的一些情况。
|
||
|
||
### virtual
|
||
|
||
虚拟字段
|
||
|
||
```ts
|
||
interface VirtualOptions {
|
||
|
||
name: string;
|
||
|
||
type: 'virtual';
|
||
|
||
get?(this: M): unknown;
|
||
|
||
set?(this: M, val: unknown): void;
|
||
}
|
||
```
|
||
|
||
### formula <Badge>待完善</Badge>
|
||
|
||
计算公式，一种特殊的虚拟字段
|
||
|
||
```ts
|
||
interface FormulaOptions {
|
||
|
||
name: string;
|
||
|
||
type: 'formula';
|
||
|
||
/**
|
||
* 计算公式
|
||
*/
|
||
formula: string;
|
||
|
||
/**
|
||
* 输出格式
|
||
*/
|
||
format: 'string' | 'number';
|
||
}
|
||
```
|
||
|
||
### reference <Badge>未实现</Badge>
|
||
|
||
引用
|
||
|
||
```ts
|
||
interface ReferenceOptions {
|
||
|
||
name: string;
|
||
|
||
type: 'reference';
|
||
|
||
/**
|
||
* 数据路径
|
||
*/
|
||
dataIndex: string;
|
||
}
|
||
```
|
||
|
||
### password
|
||
|
||
密码
|
||
|
||
```ts
|
||
interface PasswordOptions {
|
||
|
||
name: string;
|
||
|
||
type: 'password';
|
||
|
||
/**
|
||
* 暂时只支持 bcrypt 算法
|
||
*
|
||
* 默认值：bcrypt
|
||
*/
|
||
algo: 'bcrypt' | 'argon2';
|
||
}
|
||
```
|
||
|
||
### sort
|
||
|
||
顺序类型
|
||
|
||
```ts
|
||
interface SortOptions {
|
||
|
||
name: string;
|
||
|
||
type: 'sort';
|
||
|
||
/**
|
||
* 限定范围
|
||
*/
|
||
scope?: string[];
|
||
|
||
/**
|
||
* 新值创建策略
|
||
*
|
||
* max: 使用最大值
|
||
* min: 使用最小值
|
||
*
|
||
* Defaults to 'max'
|
||
*/
|
||
next?: 'min' | 'max';
|
||
}
|
||
```
|
||
|
||
### radio
|
||
|
||
radio 类型
|
||
|
||
```ts
|
||
interface RadioOptions {
|
||
|
||
name: string;
|
||
|
||
type: 'radio';
|
||
|
||
/**
|
||
* 限定范围
|
||
*/
|
||
scope?: string[];
|
||
}
|
||
```
|
||
|
||
### hasOne
|
||
|
||
一对一
|
||
|
||
```ts
|
||
interface HasManyOptions {
|
||
|
||
type: 'hasMany';
|
||
|
||
/**
|
||
* 关系字段名称
|
||
*/
|
||
name: string;
|
||
|
||
/**
|
||
* 目标数据表名称
|
||
*
|
||
* 默认值：<name>
|
||
*/
|
||
target?: string;
|
||
|
||
/**
|
||
* 目标数据表字段（外键字段）
|
||
*
|
||
* 默认值：<targetName>_<targetPrimaryKeyAttribute>
|
||
*/
|
||
foreignKey?: string;
|
||
|
||
/**
|
||
* 来源数据表字段（一般为主键字段）
|
||
*
|
||
* 默认值：<sourcePrimaryKeyAttribute>
|
||
*/
|
||
sourceKey?: string;
|
||
}
|
||
```
|
||
|
||
### hasMany
|
||
|
||
一对多
|
||
|
||
```ts
|
||
interface HasManyOptions {
|
||
|
||
type: 'hasMany';
|
||
|
||
/**
|
||
* 关系字段名称
|
||
*/
|
||
name: string;
|
||
|
||
/**
|
||
* 目标数据表名称
|
||
*
|
||
* 默认值：<name>
|
||
*/
|
||
target?: string;
|
||
|
||
/**
|
||
* 目标数据表字段（外键字段）
|
||
*
|
||
* 默认值：<targetName>_<targetPrimaryKeyAttribute>
|
||
*/
|
||
foreignKey?: string;
|
||
|
||
/**
|
||
* 来源数据表字段（一般为主键字段）
|
||
*
|
||
* 默认值：<sourcePrimaryKeyAttribute>
|
||
*/
|
||
sourceKey?: string;
|
||
}
|
||
```
|
||
|
||
### belongsTo
|
||
|
||
多对一
|
||
|
||
```ts
|
||
interface BelongsToOptions {
|
||
|
||
type: 'belongsTo';
|
||
|
||
/**
|
||
* 关系字段名称
|
||
*/
|
||
name: string;
|
||
|
||
/**
|
||
* 目标数据表名称
|
||
*
|
||
* 默认值：<name plural>
|
||
*/
|
||
target?: string;
|
||
|
||
/**
|
||
* 来源数据表字段（外键字段）
|
||
*
|
||
* 默认值：<sourceName>_<sourcePrimaryKeyAttribute>
|
||
*/
|
||
foreignKey?: string;
|
||
|
||
/**
|
||
* 目标数据表字段（一般为主键字段）
|
||
*
|
||
* 默认值：<targetPrimaryKeyAttribute>
|
||
*/
|
||
targetKey?: string;
|
||
}
|
||
```
|
||
|
||
### belongsToMany
|
||
|
||
多对多
|
||
|
||
```ts
|
||
interface BelongsToManyOptions {
|
||
|
||
type: 'belongsToMany';
|
||
|
||
/**
|
||
* 关系字段名称
|
||
*/
|
||
name: string;
|
||
|
||
|
||
/**
|
||
* 目标数据表名称
|
||
*
|
||
* 默认值：<name>
|
||
*/
|
||
target?: string;
|
||
|
||
/**
|
||
* 中间表名称
|
||
*
|
||
* 默认值：sourceName 和 targetName 按字母顺序排序之后连接
|
||
*/
|
||
through?: string;
|
||
|
||
/**
|
||
* 来源数据表字段（一般为主键字段）
|
||
*
|
||
* 默认值：<sourcePrimaryKeyAttribute>
|
||
*/
|
||
sourceKey?: string;
|
||
|
||
/**
|
||
* 来源数据表字段（外键字段）
|
||
*
|
||
* 默认值：<sourceName>_<sourcePrimaryKeyAttribute>
|
||
*/
|
||
foreignKey?: string;
|
||
|
||
/**
|
||
* 目标数据表字段（一般为主键字段）
|
||
*
|
||
* 默认值：<targetPrimaryKeyAttribute>
|
||
*/
|
||
targetKey?: string;
|
||
|
||
/**
|
||
* 目标数据表字段（外键字段）
|
||
*
|
||
* 默认值：<targetName>_<targetPrimaryKeyAttribute>
|
||
*/
|
||
otherKey?: string;
|
||
}
|
||
```
|
||
|
||
### 字段扩展
|
||
|
||
以密码字段为例：
|
||
|
||
```ts
|
||
import bcrypt from 'bcrypt';
|
||
import { StringOptions, FieldContext, registerFields, getField } from '@nocobase/database';
|
||
|
||
export class PASSWORD extends STRING {
|
||
|
||
getDataType() {
|
||
return DataTypes.STRING;
|
||
}
|
||
|
||
constructor(options: StringOptions, context: FieldContext) {
|
||
super(options, context);
|
||
const Model = context.sourceTable.getModel();
|
||
Model.addHook('beforeCreate', PASSWORD.hash.bind(this));
|
||
Model.addHook('beforeUpdate', PASSWORD.hash.bind(this));
|
||
}
|
||
|
||
static async hash(this: PASSWORD, model) {
|
||
const { name } = this.options;
|
||
if (!model.changed(name as any)) {
|
||
return;
|
||
}
|
||
const value = model.get(name) as string;
|
||
if (value) {
|
||
if (value.startsWith('$2b$10$') && value.length === 60) {
|
||
return;
|
||
}
|
||
const hash = await bcrypt.hash(value, 10);
|
||
model.set(name, hash);
|
||
} else {
|
||
model.set(name, null);
|
||
}
|
||
}
|
||
|
||
static async verify(value: string, hash: string) {
|
||
return await bcrypt.compare(value, hash);
|
||
}
|
||
}
|
||
|
||
registerFields({ PASSWORD });
|
||
|
||
const db = new Database({
|
||
// 省略配置信息
|
||
});
|
||
|
||
const table = db.table({
|
||
name: 'users',
|
||
fields: [
|
||
{ type: 'password', name: 'password' },
|
||
],
|
||
});
|
||
|
||
await table.sync();
|
||
|
||
const User = db.getModel('users');
|
||
|
||
const user = User.create({
|
||
password: '123456',
|
||
});
|
||
|
||
const Pwd = getField('password');
|
||
|
||
await Pwd.verify('123456', user.password); // true
|
||
```
|
||
|
||
## API
|
||
|
||
### registerField(type: string, field: Field)
|
||
|
||
- type：字段类型，不区分大小写
|
||
- field：字段类
|
||
|
||
注册字段
|
||
|
||
### registerFields
|
||
|
||
批量注册字段，用法同 registerField
|
||
|
||
### getField
|
||
|
||
获取已注册字段类
|
||
|
||
<Alert title="注意" type="warning">
|
||
虽然直接通过 import/require 可以引用已导出的字段类型，但是更推荐用 getField 来处理，尤其在插件化的场景下。
|
||
</Alert>
|
||
|
||
```ts
|
||
import CustomField from './CustomField';
|
||
|
||
registerFields({ CustomField });
|
||
|
||
// 以下三种写法最终效果一致，区别在于用 getField 只能获取已注册的字段类型
|
||
import CustomField from './CustomField';
|
||
const CustomField = require('./CustomField');
|
||
// CustomField 只是 key，真实的类由 registerFields 控制
|
||
const CustomField = getField('CustomField');
|
||
```
|
||
|
||
### registerModel
|
||
|
||
注册 Model
|
||
|
||
```ts
|
||
import { Model, registerModel } from '@nocobase/database';
|
||
|
||
class Test extends Model {
|
||
// 在这个类里可以为 Test Model 扩展其他 API
|
||
static hello() {
|
||
|
||
}
|
||
}
|
||
|
||
registerModel('test', Test);
|
||
|
||
db.table({
|
||
name: 'tests',
|
||
model: 'test',
|
||
});
|
||
|
||
const Test = db.getModel('tests');
|
||
// Test 可以调用 hello 方法了
|
||
Test.hello();
|
||
```
|
||
|
||
### registerModels
|
||
|
||
批量注册 Model，用法同 registerModel
|
||
|
||
### getRegisteredModel
|
||
|
||
获取已注册字段类型
|
||
|
||
### extend <Badge>实验性</Badge>
|
||
|
||
扩展配置的语法糖，需要与 database.import 配合使用，extend 的用法参考 [database.extend](#databaseextend)。 table 配置只有 extend 时，不处理。
|
||
|
||
如某配置文件 `./path1/foos-extends.ts`
|
||
|
||
```ts
|
||
import { extend } from '@nocobase/database';
|
||
|
||
export default extend({
|
||
name: 'foos',
|
||
fields: [],
|
||
});
|
||
```
|
||
|
||
导入配置
|
||
|
||
```ts
|
||
database.import({
|
||
directory: '/path1',
|
||
});
|
||
|
||
// foos 只有 extend 配置文件，不导入处理
|
||
database.isDefined('foos'); // false
|
||
```
|
||
|
||
### Operator.register <Badge>实验性</Badge> <Badge>待完善</Badge>
|
||
|
||
注册自定义 op
|
||
|
||
### database.constructor
|
||
|
||
初始化实例
|
||
|
||
```ts
|
||
const db = new Database({
|
||
username,
|
||
password,
|
||
database,
|
||
host,
|
||
port,
|
||
dialect,
|
||
dialectOptions,
|
||
pool,
|
||
logging,
|
||
define,
|
||
sync,
|
||
});
|
||
```
|
||
|
||
更多用法参考 [Sequelize.Options](https://github.com/sequelize/sequelize/blob/5b16b32259f0599a6af2d1eb625622da9054265e/types/lib/sequelize.d.ts#L180)
|
||
|
||
### database.import
|
||
|
||
- directory：文件夹路径
|
||
- extensions：扩展，默认 `['js', 'ts', 'json']`
|
||
|
||
批量导入配置
|
||
|
||
```ts
|
||
database.import({
|
||
directory: '/path1/tables',
|
||
extensions: ['js', 'ts', 'json'],
|
||
});
|
||
```
|
||
|
||
### database.table
|
||
|
||
- name：表名
|
||
- fields：字段
|
||
- model：绑定自定义的 Model
|
||
|
||
更多参数查看 [TableOptions](https://github.com/nocobase/nocobase/blob/bbcd31016913b1297f258786df97b237d9fbd977/packages/database/src/table.ts#L48)（继承 [Sequelize.ModelOptions](https://github.com/sequelize/sequelize/blob/5b16b32259f0599a6af2d1eb625622da9054265e/types/lib/model.d.ts#L1361)）
|
||
|
||
配置数据表
|
||
|
||
用例：
|
||
|
||
```ts
|
||
database.table({
|
||
name: 'demos',
|
||
fields: [],
|
||
});
|
||
```
|
||
|
||
### database.extend
|
||
|
||
配置扩展。更多用法参考 [table.extend](#tableextend)
|
||
|
||
```ts
|
||
db.table({
|
||
name: 'foos',
|
||
fields: [
|
||
{type: 'string', name: 'name'},
|
||
],
|
||
});
|
||
|
||
db.extend({
|
||
name: 'foos',
|
||
fields: [
|
||
{type: 'string', name: 'content'},
|
||
],
|
||
});
|
||
```
|
||
|
||
<Alert title="database.table 与 database.extend 区别？" type="warning">
|
||
database.table 用于初始化，database.extend 用于处理扩展，需要 table 已存在。
|
||
</Alert>
|
||
|
||
### database.isDefined
|
||
|
||
判断数据表是否已定义
|
||
|
||
### database.getModel
|
||
|
||
获取已定义的 Model
|
||
|
||
```ts
|
||
database.table({
|
||
name: 'posts',
|
||
fields: [
|
||
{type: 'string', name: 'title'},
|
||
{type: 'string', name: 'content'},
|
||
],
|
||
});
|
||
|
||
const Post = database.getModel('posts');
|
||
|
||
await Post.create({
|
||
title: 't1',
|
||
content: 'c1',
|
||
})
|
||
```
|
||
|
||
### database.getModels
|
||
|
||
批量获取已定义的 Models
|
||
|
||
```ts
|
||
const [User, Post] = database.getModels(['users', 'posts']);
|
||
```
|
||
|
||
### database.getTable
|
||
|
||
获取已定义的 Table
|
||
|
||
```ts
|
||
const table = database.getTable('posts');
|
||
```
|
||
|
||
### database.getTables
|
||
|
||
批量获取已定义的 Tables
|
||
|
||
```ts
|
||
const [user, post] = database.getTables(['users', 'posts']);
|
||
```
|
||
|
||
### database.sync
|
||
|
||
- tables：与数据库结构同步的表
|
||
|
||
数据表配置与数据库表结构同步
|
||
|
||
```ts
|
||
await db.sync({
|
||
tables: ['users', 'posts'],
|
||
});
|
||
```
|
||
|
||
更多参数参考 [Sequelize.sync](https://github.com/sequelize/sequelize/blob/5b16b32259f0599a6af2d1eb625622da9054265e/types/lib/sequelize.d.ts#L45)
|
||
|
||
<Alert title="database.sync、table.sync、sequelize.sync、Model.sync 区别？" type="warning">
|
||
|
||
- database.sync：所有已配置表同步，可以指定 tables 范围
|
||
- table.sync：当前表同步，如果有关系字段，关系表也会处理
|
||
- sequelize.sync：所有 sequelize.models 同步
|
||
- Model.sync 只处理某个 Model.attributes 同步，并不处理关系 Model 的情况
|
||
|
||
</Alert>
|
||
|
||
### database.close
|
||
|
||
关闭数据库连接
|
||
|
||
```ts
|
||
await database.close();
|
||
```
|
||
|
||
### database.addHook <Badge>待完善</Badge>
|
||
|
||
为数据表配置提供的钩子，目前 HookType 有：
|
||
|
||
- beforeTableInit
|
||
- afterTableInit
|
||
- beforeAddField
|
||
- afterAddField
|
||
|
||
<Alert title="注意" type="warning">
|
||
|
||
目前这部分的 api 主要用于弥补数据表配置的事件，长远来看还需要继续完善的有：
|
||
|
||
- 统一 hook 接口（Table 和 Model）
|
||
- 钩子需要支持优先级（顺序）
|
||
|
||
</Alert>
|
||
|
||
### database.runHooks <Badge>待完善</Badge>
|
||
|
||
运行当前钩子挂载的函数
|
||
|
||
### table.getOptions
|
||
|
||
获取数据表配置
|
||
|
||
```ts
|
||
const options = table.getOptions();
|
||
const fields = table.getOptions('fields');
|
||
```
|
||
|
||
### table.getModel
|
||
|
||
获取当前配置表对应的 Model
|
||
|
||
### table.hasField
|
||
|
||
判断字段是否存在
|
||
|
||
### table.getField
|
||
|
||
获取已配置字段
|
||
|
||
### table.addField
|
||
|
||
新增字段（附加操作），字段的配置参考 [Field Types](#field-types)
|
||
|
||
```ts
|
||
const table = db.table({
|
||
name: 'foos',
|
||
});
|
||
|
||
table.addField({type: 'string', name: 'name'});
|
||
table.addField({type: 'string', name: 'status'});
|
||
```
|
||
|
||
### table.setFields
|
||
|
||
批量新增字段（替换操作）
|
||
|
||
### table.getFields
|
||
|
||
获取当前表字段列表
|
||
|
||
### table.addIndex
|
||
|
||
建立索引
|
||
|
||
### table.addIndexes
|
||
|
||
批量建立索引，同 table.addIndex
|
||
|
||
### table.extend(tableOptions: TableOptions, mergeOptions?: MergeOptions)
|
||
|
||
- tableOptions：表配置
|
||
- mergeOptions：自定义合并规则，非必填，参数参考 [deepmerge](https://www.npmjs.com/package/deepmerge#options)
|
||
|
||
配置扩展
|
||
|
||
```ts
|
||
table.extend({
|
||
// 与 table.table 一致
|
||
}, {
|
||
// 自定义
|
||
arrayMerge,
|
||
customMerge,
|
||
})
|
||
```
|
||
|
||
<Alert title="table.extend、database.extend、extend 区别？" type="warning">
|
||
|
||
- table.extend：用于处理当前表扩展
|
||
- database.extend：需要指定 tableName，其他用法同 table.extend
|
||
- extend：Markup 函数，只用于标记哪些配置用于扩展，用于 database.import 的配置文件中，用法同 database.extend
|
||
|
||
</Alert>
|
||
|
||
### table.sync <Badge>待完善</Badge>
|
||
|
||
当前表配置与数据库表结构同步
|
||
|
||
更多参数参考 [Sequelize.sync](https://github.com/sequelize/sequelize/blob/5b16b32259f0599a6af2d1eb625622da9054265e/types/lib/sequelize.d.ts#L45)
|
||
|
||
```ts
|
||
await table.sync({})
|
||
```
|
||
|
||
<Alert title="注意">
|
||
|
||
因为没有更细度的 field.sync 所以配置有更新时，直接执行 table.sync，如果 table 里存在关系字段，关系表也会执行 sync 可能导致执行时间超时，数据库连接断开。后续需要提供更细度的 field.sync 以减少不必要的性能消耗。
|
||
|
||
</Alert>
|
||
|
||
### Model.database
|
||
|
||
获取当前 database 实例
|
||
|
||
### Model.parseApiJson <Badge>待完善</Badge>
|
||
|
||
将 filter、fields、sort 等参数转换为 where、attributes、include、order 等
|
||
|
||
#### filter
|
||
|
||
过滤条件，支持两种格式
|
||
|
||
```ts
|
||
{
|
||
filter: {
|
||
[field: string]: {
|
||
[operator: Op]: any,
|
||
}
|
||
},
|
||
}
|
||
```
|
||
|
||
逻辑运算符 - and/or：
|
||
|
||
```ts
|
||
{
|
||
['and'|'or']: [
|
||
{
|
||
[field: string]: {
|
||
[operator: Op]: any,
|
||
}
|
||
},
|
||
{
|
||
['and'|'or']: [
|
||
{
|
||
[field: string]: {
|
||
[operator: Op]: any,
|
||
}
|
||
},
|
||
],
|
||
},
|
||
],
|
||
}
|
||
```
|
||
|
||
#### fields
|
||
|
||
简单用法（同 only 用法）：
|
||
|
||
```ts
|
||
{
|
||
fields: ['col1', 'col2'],
|
||
}
|
||
```
|
||
|
||
复杂用法：
|
||
|
||
```ts
|
||
{
|
||
fields: {
|
||
// 附加，一般用于关系字段（默认不输出关系字段数据）
|
||
appends: ['col1', 'col2'],
|
||
// 白名单
|
||
only: ['col1', 'col2'],
|
||
// 黑名单
|
||
except: ['col1', 'col2'],
|
||
},
|
||
}
|
||
```
|
||
|
||
#### sort
|
||
|
||
排序
|
||
|
||
```ts
|
||
{
|
||
sort: [
|
||
'-created_at', // 优先创建时间倒序
|
||
'id' // 其次 id 正序
|
||
],
|
||
}
|
||
```
|
||
|
||
#### page
|
||
|
||
当前分页
|
||
|
||
#### perPage
|
||
|
||
每页多少条数据，当 `perPage=-1` 时，输出所有数据，最多不超过 500 条
|
||
|
||
#### context
|
||
|
||
注入上下文，目前主要用于处理 filter 的动态参数
|
||
|
||
### model.database
|
||
|
||
获取当前 database 实例
|
||
|
||
### model.updateAssociations <Badge>待完善</Badge>
|
||
|
||
更新关系数据
|
||
|
||
```ts
|
||
const user = User.create({});
|
||
const post = Post.create({});
|
||
await post.updateAssociations({
|
||
// 支持直接提供外键值，一般为 Model.primaryKeyAttribute
|
||
user: 1,
|
||
// 或者是 object 对象，如果数据不存在会直接创建
|
||
user: {
|
||
name: 'name1',
|
||
},
|
||
// 也可以是 model 对象
|
||
user,
|
||
// 如果是 hasMany 或 belongsToMany 关系，可以是上面三种写法，也可以是数组类型
|
||
categories: 1,
|
||
tags: [
|
||
1,
|
||
{name: 'tag2'}, // object
|
||
tag, // tag 对象
|
||
],
|
||
comments: [
|
||
{ content: '' },
|
||
comment, // comment model 对象
|
||
]
|
||
});
|
||
```
|
||
|
||
<Alert title="为什么需要 model.updateAssociations？">
|
||
|
||
关系数据的新增或更新非常复杂，尤其在表单场景里非常受用。
|
||
|
||
注意：还需要支持仅关联和可新增或更新关系数据两种情况。
|
||
|
||
- 仅关联：只建立关系，不更新关系数据内容
|
||
- 可新增或更新关系数据：建立关联的同时，更新关系数据内容
|
||
|
||
</Alert>
|
||
|
||
### model.getValuesByFieldNames <Badge>待完善</Badge>
|
||
|
||
获取当前 model 在 scope 范围内的值
|
||
|
||
如，某 model 的 dataValues 如下：
|
||
|
||
```ts
|
||
{
|
||
id: 1,
|
||
status: 'publish',
|
||
user: { // 关系数据，可能需要异步获取
|
||
id: 1,
|
||
email: 'admin@example.com'
|
||
},
|
||
}
|
||
```
|
||
|
||
```ts
|
||
await model.getValuesByFieldNames(['status', 'user.email']);
|
||
|
||
// 理想化输出的结果为：
|
||
{
|
||
status: 'publish',
|
||
'user.email': 'admin@example.com',
|
||
}
|
||
```
|
||
|
||
可能用于与 filter 进行比较
|
||
|
||
```ts
|
||
compareFilterWithScope(
|
||
{
|
||
and: [{ status: 'publish' }]
|
||
},
|
||
{
|
||
status: 'publish',
|
||
'user.email': 'admin@example.com',
|
||
}
|
||
); // => true
|
||
``` |