feat(docs): add model api doc
This commit is contained in:
		
							parent
							
								
									d9484e25a6
								
							
						
					
					
						commit
						35739f9f42
					
				
							
								
								
									
										327
									
								
								docs/reference/model.md
									
									
									
									
									
										Normal file
									
								
							
							
						
						
									
										327
									
								
								docs/reference/model.md
									
									
									
									
									
										Normal file
									
								
							@ -0,0 +1,327 @@
 | 
			
		||||
---
 | 
			
		||||
toc: menu
 | 
			
		||||
---
 | 
			
		||||
 | 
			
		||||
# Model
 | 
			
		||||
 | 
			
		||||
## `model.updateAssociations()`
 | 
			
		||||
 | 
			
		||||
用于更新 model 的关系,目前主要有四种基础关系
 | 
			
		||||
 | 
			
		||||
- hasOne
 | 
			
		||||
- hasMany
 | 
			
		||||
- belongsTo
 | 
			
		||||
- belongsToMany
 | 
			
		||||
 | 
			
		||||
##### Definition
 | 
			
		||||
 | 
			
		||||
```ts
 | 
			
		||||
interface updateAssociations {
 | 
			
		||||
  (values: UpdateAssociationValues, options?: UpdateAssociationOptions): Promise<void>;
 | 
			
		||||
}
 | 
			
		||||
 | 
			
		||||
interface UpdateAssociationOptions {
 | 
			
		||||
  transaction?: Transaction | null;
 | 
			
		||||
  updateAssociationValues?: string[];
 | 
			
		||||
}
 | 
			
		||||
 | 
			
		||||
interface UpdateAssociationValues {
 | 
			
		||||
  [key: string]: any;
 | 
			
		||||
}
 | 
			
		||||
```
 | 
			
		||||
 | 
			
		||||
##### Examples
 | 
			
		||||
 | 
			
		||||
### HasOne
 | 
			
		||||
 | 
			
		||||
以用户个人资料 user.profile 为例:
 | 
			
		||||
 | 
			
		||||
可以传 profile instance
 | 
			
		||||
 | 
			
		||||
```ts
 | 
			
		||||
const User = db.collection({
 | 
			
		||||
  name: 'users';
 | 
			
		||||
  fields: [
 | 
			
		||||
    { type: 'hasOne', name: 'profile' },
 | 
			
		||||
  ],
 | 
			
		||||
});
 | 
			
		||||
 | 
			
		||||
const Profile = db.collection({
 | 
			
		||||
  name: 'profiles';
 | 
			
		||||
  fields: [
 | 
			
		||||
    { type: 'string', name: 'gender' },
 | 
			
		||||
  ],
 | 
			
		||||
});
 | 
			
		||||
 | 
			
		||||
const user = await User.model.create();
 | 
			
		||||
const profile = await Profile.model.create();
 | 
			
		||||
 | 
			
		||||
await user.updateAssociations({
 | 
			
		||||
  profile,
 | 
			
		||||
});
 | 
			
		||||
```
 | 
			
		||||
 | 
			
		||||
也可以直接传 profile 的 id 值
 | 
			
		||||
 | 
			
		||||
```ts
 | 
			
		||||
const user = await User.model.create();
 | 
			
		||||
const profile = await Profile.model.create();
 | 
			
		||||
 | 
			
		||||
await user.updateAssociations({
 | 
			
		||||
  profile: profile.id,
 | 
			
		||||
});
 | 
			
		||||
```
 | 
			
		||||
 | 
			
		||||
也可以传 object,如果 object 不含 pk,直接创建并关联
 | 
			
		||||
 | 
			
		||||
```ts
 | 
			
		||||
const user = await User.model.create();
 | 
			
		||||
 | 
			
		||||
await user.updateAssociations({
 | 
			
		||||
  profile: {
 | 
			
		||||
    gender: 'male',
 | 
			
		||||
  },
 | 
			
		||||
});
 | 
			
		||||
```
 | 
			
		||||
 | 
			
		||||
如果 object 的 key 带 pk,只关联,不修改关联数据(默认)
 | 
			
		||||
 | 
			
		||||
```ts
 | 
			
		||||
const user = await User.model.create();
 | 
			
		||||
const profile = await Profile.model.create({
 | 
			
		||||
  gender: 'male',
 | 
			
		||||
});
 | 
			
		||||
await user.updateAssociations({
 | 
			
		||||
  profile: {
 | 
			
		||||
    id: profile.id,
 | 
			
		||||
    gender: 'female', // 这里虽然改了,但是不修改
 | 
			
		||||
  },
 | 
			
		||||
});
 | 
			
		||||
```
 | 
			
		||||
 | 
			
		||||
如果要修改关联数据,需要指定 `updateAssociationValues` 路径,如:
 | 
			
		||||
 | 
			
		||||
```ts
 | 
			
		||||
const user = await User.model.create();
 | 
			
		||||
const profile = await Profile.model.create({
 | 
			
		||||
  gender: 'male',
 | 
			
		||||
});
 | 
			
		||||
await user.updateAssociations({
 | 
			
		||||
  profile: {
 | 
			
		||||
    id: profile.id,
 | 
			
		||||
    gender: 'female', // updateAssociationValues 包含 profile,所以 gender 会被修改
 | 
			
		||||
  },
 | 
			
		||||
}, {
 | 
			
		||||
  // 对 profile 的 values 进行更新
 | 
			
		||||
  updateAssociationValues: ['profile'],
 | 
			
		||||
});
 | 
			
		||||
```
 | 
			
		||||
 | 
			
		||||
<Alert title="注意">
 | 
			
		||||
修改关联数据的使用频率较低,用不好破坏性很大,默认只关联并不更新关联数据。如果 JSON 不包含 pk,需要创建并关联处理。
 | 
			
		||||
</Alert>
 | 
			
		||||
 | 
			
		||||
如果已经存在关联,解除关联,但不删除关联数据,并与新的数据建立关联
 | 
			
		||||
 | 
			
		||||
```ts
 | 
			
		||||
const user = await User.model.create();
 | 
			
		||||
const profile1 = await Profile.model.create();
 | 
			
		||||
const profile2 = await Profile.model.create();
 | 
			
		||||
await user.updateAssociations({
 | 
			
		||||
  profile: profile1,
 | 
			
		||||
});
 | 
			
		||||
 | 
			
		||||
// 与 profile1 解除关联,并与 profile2 建立关联,profile1 数据还存在
 | 
			
		||||
await user.updateAssociations({
 | 
			
		||||
  profile: profile2,
 | 
			
		||||
});
 | 
			
		||||
```
 | 
			
		||||
 | 
			
		||||
## BelongsTo
 | 
			
		||||
 | 
			
		||||
与 HasOne 的处理机制类似,不过多了个 targetKey 的情况,当 targetKey 不为 id 时,会有些区别:
 | 
			
		||||
 | 
			
		||||
以文章作者 post.user 为例:
 | 
			
		||||
 | 
			
		||||
```ts
 | 
			
		||||
const Post = db.collection({
 | 
			
		||||
  name: 'posts';
 | 
			
		||||
  fields: [
 | 
			
		||||
    { type: 'belongsTo', name: 'user', targetKey: 'uid' },
 | 
			
		||||
  ],
 | 
			
		||||
});
 | 
			
		||||
 | 
			
		||||
const User = db.collection({
 | 
			
		||||
  name: 'users';
 | 
			
		||||
  fields: [
 | 
			
		||||
    { type: 'uid', name: 'uid', unique: true }
 | 
			
		||||
  ],
 | 
			
		||||
});
 | 
			
		||||
 | 
			
		||||
const post = Post.model.create();
 | 
			
		||||
const user = User.model.create({ uid: 'uid123' });
 | 
			
		||||
 | 
			
		||||
// 可以传 uid 值,而不一定是 id
 | 
			
		||||
await post.updateAssociations({
 | 
			
		||||
  user: 'uid123',
 | 
			
		||||
});
 | 
			
		||||
```
 | 
			
		||||
 | 
			
		||||
## HasMany
 | 
			
		||||
 | 
			
		||||
可以传 instance
 | 
			
		||||
 | 
			
		||||
```ts
 | 
			
		||||
const comment = await Comment.model.create();
 | 
			
		||||
await post.updateAssociations({
 | 
			
		||||
  // 自动转换为 [comment]
 | 
			
		||||
  comments: comment,
 | 
			
		||||
});
 | 
			
		||||
 | 
			
		||||
// 等同于
 | 
			
		||||
await post.updateAssociations({
 | 
			
		||||
  comments: [comment],
 | 
			
		||||
});
 | 
			
		||||
```
 | 
			
		||||
 | 
			
		||||
也可以传 pk 值
 | 
			
		||||
 | 
			
		||||
```ts
 | 
			
		||||
const comment = await Comment.model.create();
 | 
			
		||||
await post.updateAssociations({
 | 
			
		||||
  // 自动转换为 [comment.id]
 | 
			
		||||
  comments: comment.id,
 | 
			
		||||
});
 | 
			
		||||
 | 
			
		||||
// 等同于
 | 
			
		||||
await post.updateAssociations({
 | 
			
		||||
  comments: [comment.id]
 | 
			
		||||
});
 | 
			
		||||
```
 | 
			
		||||
 | 
			
		||||
可以是 object
 | 
			
		||||
 | 
			
		||||
```ts
 | 
			
		||||
await post.updateAssociations({
 | 
			
		||||
  comments: {
 | 
			
		||||
    content: 'comment 1'
 | 
			
		||||
  },
 | 
			
		||||
});
 | 
			
		||||
```
 | 
			
		||||
 | 
			
		||||
或者是 array
 | 
			
		||||
 | 
			
		||||
```ts
 | 
			
		||||
await post.updateAssociations({
 | 
			
		||||
  comments: [
 | 
			
		||||
    {
 | 
			
		||||
      content: 'comment 1'
 | 
			
		||||
    },
 | 
			
		||||
    {
 | 
			
		||||
      content: 'comment 2'
 | 
			
		||||
    },
 | 
			
		||||
  ],
 | 
			
		||||
});
 | 
			
		||||
```
 | 
			
		||||
 | 
			
		||||
或者是混合的元素
 | 
			
		||||
 | 
			
		||||
```ts
 | 
			
		||||
await post.updateAssociations({
 | 
			
		||||
  comments: [
 | 
			
		||||
    1,
 | 
			
		||||
    comment,
 | 
			
		||||
    {
 | 
			
		||||
      id: 3,
 | 
			
		||||
      content: 'comment 3'
 | 
			
		||||
    },
 | 
			
		||||
  ],
 | 
			
		||||
});
 | 
			
		||||
```
 | 
			
		||||
 | 
			
		||||
多层内嵌的情况,订单商品详情 order.details
 | 
			
		||||
 | 
			
		||||
```ts
 | 
			
		||||
db.collection({
 | 
			
		||||
  name: 'orders',
 | 
			
		||||
  fields: [
 | 
			
		||||
    { type: 'hasMany', name: 'details', target: 'order_details' }
 | 
			
		||||
  ],
 | 
			
		||||
});
 | 
			
		||||
 | 
			
		||||
db.collection({
 | 
			
		||||
  name: 'order_details',
 | 
			
		||||
  fields: [
 | 
			
		||||
    { type: 'belongsTo', name: 'product' },
 | 
			
		||||
    { type: 'integer', name: 'qty' },
 | 
			
		||||
    { type: 'integer', name: 'price' },
 | 
			
		||||
  ],
 | 
			
		||||
});
 | 
			
		||||
 | 
			
		||||
db.collection({
 | 
			
		||||
  name: 'products',
 | 
			
		||||
  fields: [
 | 
			
		||||
  ],
 | 
			
		||||
});
 | 
			
		||||
 | 
			
		||||
const order = Order.model.create();
 | 
			
		||||
 | 
			
		||||
await order.updateAssociations({
 | 
			
		||||
  details: [
 | 
			
		||||
    {
 | 
			
		||||
      product: 1,
 | 
			
		||||
      qty: 3,
 | 
			
		||||
      price: 200,
 | 
			
		||||
    },
 | 
			
		||||
    {
 | 
			
		||||
      product: 2,
 | 
			
		||||
      qty: 3,
 | 
			
		||||
      price: 200,
 | 
			
		||||
    },
 | 
			
		||||
  ],
 | 
			
		||||
});
 | 
			
		||||
```
 | 
			
		||||
 | 
			
		||||
## BelongsToMany
 | 
			
		||||
 | 
			
		||||
常规写法与 HasMany 类似,不过有两个特殊参数 targetKey 和 through。targetKey 与 BelongsTo 类似。through 为实体表时,需要可以更新 through 数据。
 | 
			
		||||
 | 
			
		||||
```ts
 | 
			
		||||
const Foo = db.collection({
 | 
			
		||||
  name: 'foos',
 | 
			
		||||
  fields: [
 | 
			
		||||
    { type: 'belongsToMany', name: 'bars' },
 | 
			
		||||
  ],
 | 
			
		||||
});
 | 
			
		||||
 | 
			
		||||
const Bar = db.collection({
 | 
			
		||||
  name: 'bars',
 | 
			
		||||
  fields: [
 | 
			
		||||
    { type: 'string', name: 'title' },
 | 
			
		||||
  ],
 | 
			
		||||
});
 | 
			
		||||
 | 
			
		||||
db.collection({
 | 
			
		||||
  name: 'bars_foos',
 | 
			
		||||
  fields: [
 | 
			
		||||
    { type: 'string', name: 'status' },
 | 
			
		||||
  ],
 | 
			
		||||
});
 | 
			
		||||
 | 
			
		||||
await foo.updateAssociations({
 | 
			
		||||
  bars: [
 | 
			
		||||
    {
 | 
			
		||||
      title: 'title1',
 | 
			
		||||
      bars_foos: {
 | 
			
		||||
        status: 'publish',
 | 
			
		||||
      },
 | 
			
		||||
    },
 | 
			
		||||
    {
 | 
			
		||||
      title: 'title2',
 | 
			
		||||
      bars_foos: {
 | 
			
		||||
        status: 'draft',
 | 
			
		||||
      },
 | 
			
		||||
    },
 | 
			
		||||
  ],
 | 
			
		||||
})
 | 
			
		||||
```
 | 
			
		||||
		Loading…
	
		Reference in New Issue
	
	Block a user