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