Skip to content

Commit

Permalink
Merge conflicts
Browse files Browse the repository at this point in the history
  • Loading branch information
babyfish-ct committed Dec 13, 2024
2 parents 967919a + 80e7f80 commit c5f6d82
Show file tree
Hide file tree
Showing 22 changed files with 47 additions and 110 deletions.
3 changes: 3 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -18,3 +18,6 @@
npm-debug.log*
yarn-debug.log*
yarn-error.log*

# IntelliJ
.idea
8 changes: 0 additions & 8 deletions .idea/.gitignore

This file was deleted.

12 changes: 0 additions & 12 deletions .idea/jimmer-doc.iml

This file was deleted.

8 changes: 0 additions & 8 deletions .idea/modules.xml

This file was deleted.

6 changes: 0 additions & 6 deletions .idea/vcs.xml

This file was deleted.

2 changes: 1 addition & 1 deletion docs/configuration/id-only-target-checking-level.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,6 @@ sidebar_position: 12
title: Associated Id Checking
---

This configuration is explained in [Mutation Section/Save Command/Enum Mapping/Associated Id Checking](../mutation/save-command/id-checking).
This configuration is explained in [Mutation Section/Save Command/Constraint Violation Error Handling/fake-foreign-keys](../mutation/save-command/investigation#fake-foreign-keys).

Therefore, this article will not repeat the explanation, it just serves as a link reference.
2 changes: 1 addition & 1 deletion docs/configuration/save-command-pessimistic-lock.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,6 @@ sidebar_position: 11
title: Pessimistic Lock
---

This configuration is explained in [Mutation Section/Save Command/Pessimistic Lock](../mutation/save-command/lock#pessimistic-lock).
This configuration is explained in [Mutation Section/Save Command/Pessimistic Locking](../mutation/save-command/pessimistic-locking).

Therefore, this article will not repeat the explanation, it just serves as a link reference.
42 changes: 10 additions & 32 deletions docs/mutation/save-command/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,43 +3,21 @@ sidebar_position: 3
title: Save Command
---

:::caution
In recent months, the save instruction has undergone a major restructuring, so there hasn't been time to update all the documentation in this directory.

Apart from new features, the new version of the save instruction has made minimal changes to existing functionality, and it remains largely consistent with the description in this directory. However, the new version of the save instruction **generates SQL with much higher performance than described here**.

The good news is that this historically significant restructuring of Jimmer has finally been completed and stabilized, so all the content in this directory will be updated soon.
:::

:::tip
One statement to save complex data of arbitrary shape, find DIFF to change database, like React/Vue
:::

Save commands are a very powerful capability of Jimmer that can greatly simplify the development difficulty of persisting complex data structures.

If [object fetchers](../../query/object-fetcher) enable output data to be in any shape, then save commands allow input data to also be in any shape.
## Features

For readers familiar with web frontend technologies, this can be analogized to `Virtual DOM diff` in [React](https://react.dev/) or [Vue](https://vuejs.org/).
Save commands are Jimmer's most powerful feature, used for saving arbitrary graph structures.

:::tip
Save command require developers to **completely change their thinking pattern**
- Merge data using the database's native upsert capabilities
- Multiple objects at each level are handled using batch DML operations
- Automatically translates constraint violation exceptions
- Saved objects at any level can be incomplete
- Can save either entities directly or input DTOs

- Fundamental difference in thinking

- The traditional thinking pattern:

Manually compare the data structure to be saved with existing data in the database, and execute `INSERT`, `UPDATE` or `DELETE` on the changed parts

- The thinking pattern for save command:

Accept the data structure passed from client as a whole and just save it. Jimmer will handle everything *(automatically compare the data structure to be saved with existing data in the database, and execute `INSERT`, `UPDATE` or `DELETE` on the changed parts)*

- Old habits should be replaced by better methods

In the traditional development mode, developers like to do one thing: query an object first, then modify some of its properties, and finally save the modified object.
:::caution
The usage of save commands is different from most other ORMs. It is recommended to first read the documentation or examples provided in this article, rather than making assumptions based on your understanding of other ORMs.
:::

Calling a save command only takes one line of code, but hides countless details internally that documentation cannot exhaustively enumerate. Therefore, save commands have a dedicated sample project:
## Examples

- Java: [jimmer-examples/java/save-command](https://github.com/babyfish-ct/jimmer-examples/tree/main/java/save-command)

Expand Down
1 change: 0 additions & 1 deletion docs/overview/key-features.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -119,7 +119,6 @@ Based on the aforementioned core concept, Jimmer provides the following features
- Automatically translates constraint violation exceptions
- Saved objects at any level can be incomplete
- Can save either entities directly or input DTOs
> This section has undergone a major upgrade, and the documentation is actively being restructured. Please refer to the save-command examples in the accompanying examples.
- Powerful caching
- Multi-layer caching, technology for each cache layer can be freely chosen
- Not just object caching *(associations, computed values, multiple views)*
Expand Down
1 change: 1 addition & 0 deletions docs/resource/ecosystem.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@ Enthusiastic people have contributed related tools, welcome everyone to actively
|IDE|Project URL|
|---|---|
|Intellij Plugin|https://github.com/ClearPlume/jimmer-dto|
|Supports any IDE that supports LSP|https://github.com/Enaium/jimmer-dto-lsp|

## Simplify Project Configurations

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,6 @@ sidebar_position: 12
title: 短关联id检查
---

该配置在[修改篇/保存指令/Enum映射/短关联id检查](../mutation/save-command/id-checking)中被阐述。
该配置在[修改篇/保存指令/违反约束异常处理#假外键](../mutation/save-command/investigation#假外键)中被阐述。

因此,本文不做重复阐述,只做链接收录。
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,6 @@ sidebar_position: 11
title: 保存指令悲观锁
---

该配置在[修改篇/保存指令/悲观锁](../mutation/save-command/lock#悲观锁)中被阐述。
该配置在[修改篇/保存指令/悲观锁](../mutation/save-command/pessimistic-locking)中被阐述。

因此,本文不做重复阐述,只做链接收录。
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ import TabItem from '@theme/TabItem';

- 拦截器可以根据业务上下文相关信息提供默认值,比如,当前用户在权限系统中的身份信息。

用户可以根据这类业务上下问信息提供和业务紧密结合的默认值,这是数据库级别默认值无法实现的。
用户可以根据这类业务上下文信息提供和业务紧密结合的默认值,这是数据库级别默认值无法实现的。
:::

## 定义被拦截数据格式
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -3,39 +3,21 @@ sidebar_position: 3
title: 保存指令
---

:::caution
最近几个月, 保存指令在做超大重构,所以没有时间更新这个目录下的所有文档。

除了全新的功能外,新版保存指令对已有功能的改动很小,和这个目录的描述基本一致;然而,新版保存指令**生成SQL的性能远高于这里所描述的。**

好消息是,这个Jimmer历史上最绝大的重构终于完成并稳定,所以,很快会更新这个目录的所有内容。
:::

:::note
一句话保存任意复杂的数据结构,自动找出DIFF并修改数据库,类似于React/Vue
:::

保存指令是Jimmer一个非常强大的能力,可以大幅简化复杂数据结构保存业务的开发难度。
## 功能

如果说[对象抓取器](../../query/object-fetcher)让作为输出信息的数据结构可以是任何形状,那么,保存指令就是让作为输入信息的数据结构也可以是任何形状。
保存指令是Jimmer最为强大的功能,用于保存任意图结构

如果读者对Web前端技术有一定的了解,可以用[React](https://react.dev/)[Vue](https://vuejs.org/)中的`Virtual DOM diff`来类比。
- 利用数据库本身的upsert能力merge数据
- 每一层的多个对象都用批量DML操作
- 自动翻译违背约束的异常
- 任何层次的被保存对象都可以不完整
- 既可以直接保存实体,也可保存Input DTO

:::tip
保存指令需要开发人员**彻底改变过去的思维模式**

- 思维模式的本质区别

- 以前的传统思维模式

自己去对比要保存的数据结构和数据库现有数据的差异,对有变化的局部执行`INSERT``UPDATE``DELETE`

- 保存指令的思维模式

接受客户端传递的数据结构,作为一个整体保存即可。Jimmer会处理好一切 *(自动对比要保存的数据结构和数据库现有数据的差异,对有变化的局部执行`INSERT``UPDATE``DELETE`)*
:::caution
保存指令的用法和绝大部分ORM都不相同,建议先阅读文档或本文给出的示例,不要按照自己对其他ORM的理解去做猜测性使用。
:::

调用保存指令只需要让一行代码,但其内部隐藏了千遍万化的细节,文档难以穷举大量案例。因此,保存指令有独立的示例项目:
## 配套例子

- Java: [jimmer-examples/java/save-command](https://github.com/babyfish-ct/jimmer-examples/tree/main/java/save-command)

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ title: 对象篇

- 不可变性

为避免环形引用,让实体对象可以直接通过JSON序列化进行HTTP交互并未其他任何编程语言所理解,Jimmer实体是不可变的。
为避免环形引用,让实体对象可以直接通过JSON序列化进行HTTP交互并为其他任何编程语言所理解,Jimmer实体是不可变的。

:::tip
Jimmer对象的动态性和不可变性是整个Jimmer世界的底层基础。
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ jimmer-core定义了一个jackson模块:`org.babyfish.jimmer.jackson.Immutable

- 使用Spring Boot Starter

在这种情况下,Jimmer已经注为Spring这册了ImmutableModule,如下
在这种情况下,Jimmer已经为Spring注册了ImmutableModule,如下

```java
// Jimmer内部代码,非用户代码
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ title: 可见性
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

之前文档已经详细讨论了Jimmer属性的[动态性](./dynamic)和不可变性(./immutable),这里介绍一个新的特性:可见性。
之前文档已经详细讨论了Jimmer属性的[动态性](./dynamic)[不可变性](./immutable),这里介绍一个新的特性:可见性。

## 纠缠属性

Expand Down Expand Up @@ -262,7 +262,7 @@ import TabItem from '@theme/TabItem';
</TabItem>
</Tabs>

对象抓取器中的`authors()`没有任何参数,表示是抓取只有id属性的author对象的集合,结果如下 *(为提高本稳定可读性,人为进行了格式化)*
对象抓取器中的`authors()`没有任何参数,表示是抓取只有id属性的author对象的集合,结果如下 *(为提高本文可读性,人为进行了格式化)*

```json
{
Expand Down Expand Up @@ -313,7 +313,7 @@ import TabItem from '@theme/TabItem';
</TabItem>
</Tabs>

这次结果为 *(为提高本稳定可读性,人为进行了格式化)*
这次结果为 *(为提高本文可读性,人为进行了格式化)*

```json
{
Expand All @@ -328,7 +328,7 @@ import TabItem from '@theme/TabItem';
}
```

虽然两次查询饭回的数据是等价的,但格式完全不同。
虽然两次查询返回的数据是等价的,但格式完全不同。

前面说过,[对象抓取器](../query/object-fetcher)抓取视图属性,其内部逻辑会将之换转化为对原始属性的抓取。

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -110,7 +110,6 @@ Jimmer自动生成的DTO支持任意复杂的层级关系,**Jimmer是目前唯
- 自动翻译违背约束的异常
- 任何层次的被保存对象都可以不完整
- 既可以直接保存实体,也可保存Input DTO
> 这部分经过了大升级,文档在积极重构中,可以先看配套例子中关于save-command的例子
- 强大的缓存
- 多级缓存,每一级缓存都可以做自由技术选型
- 不仅仅是对象缓存 *(关联、计算值、多视图)*
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@ Jimmer只专注于ORM本身,未提供辅助工具,比如,根据数据库
|IDE|项目地址|
|---|---|
|Intellij插件|https://github.com/ClearPlume/jimmer-dto|
|支持任何支持LSP的IDE|https://github.com/Enaium/jimmer-dto-lsp|

## 简化项目配置

Expand Down
2 changes: 1 addition & 1 deletion package.json
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
"scripts": {
"docusaurus": "docusaurus",
"start": "docusaurus start",
"start zh": "docusaurus start --locale zh",
"start:zh": "docusaurus start --locale zh",
"build": "docusaurus build",
"swizzle": "docusaurus swizzle",
"deploy": "docusaurus deploy",
Expand Down
2 changes: 1 addition & 1 deletion src/components/HomepageFeatures/SaveCommand.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,7 @@ const ZH: ReactNode =
<>
<p>保存指令允许开发人员保存任意形状的数据结构,而非保存简单的对象。</p>

<p>在默认情况下,即在<i>AssociatedSaveMode</i><b>REPLACE</b>情况下,Jimmer会用被保存结构去权量替换数据库中已有的数据结构,如图所示:</p>
<p>在默认情况下,即在<i>AssociatedSaveMode</i><b>REPLACE</b>情况下,Jimmer会用被保存结构去全量替换数据库中已有的数据结构,如图所示:</p>

<Save/>

Expand Down
10 changes: 9 additions & 1 deletion yarn.lock
Original file line number Diff line number Diff line change
Expand Up @@ -2184,7 +2184,11 @@

"@easyops-cn/docusaurus-search-local@^0.46.1":
version "0.46.1"
<<<<<<< HEAD
resolved "https://registry.yarnpkg.com/@easyops-cn/docusaurus-search-local/-/docusaurus-search-local-0.46.1.tgz#7fac1a14417de680b5af7088814192a153d7334d"
=======
resolved "https://registry.npmmirror.com/@easyops-cn/docusaurus-search-local/-/docusaurus-search-local-0.46.1.tgz#7fac1a14417de680b5af7088814192a153d7334d"
>>>>>>> 80e7f8002ed39a2695b6cd492e48a984a2715ef9
integrity sha512-kgenn5+pctVlJg8s1FOAm9KuZLRZvkBTMMGJvTTcvNTmnFIHVVYzYfA2Eg+yVefzsC8/cSZGKKJ0kLf8I+mQyw==
dependencies:
"@docusaurus/plugin-content-docs" "^2 || ^3"
Expand Down Expand Up @@ -4014,7 +4018,7 @@ [email protected]:

cheerio@^1.0.0:
version "1.0.0"
resolved "https://registry.yarnpkg.com/cheerio/-/cheerio-1.0.0.tgz#1ede4895a82f26e8af71009f961a9b8cb60d6a81"
resolved "https://registry.npmmirror.com/cheerio/-/cheerio-1.0.0.tgz#1ede4895a82f26e8af71009f961a9b8cb60d6a81"
integrity sha512-quS9HgjQpdaXOvsZz82Oz7uxtXiy6UIsIQcpBj7HRw2M63Skasm9qlDocAM7jNuaxdhpPU7c4kJN+gA5MCu4ww==
dependencies:
cheerio-select "^2.1.0"
Expand Down Expand Up @@ -4142,7 +4146,11 @@ combine-promises@^1.1.0:

comlink@^4.4.2:
version "4.4.2"
<<<<<<< HEAD
resolved "https://registry.yarnpkg.com/comlink/-/comlink-4.4.2.tgz#cbbcd82742fbebc06489c28a183eedc5c60a2bca"
=======
resolved "https://registry.npmmirror.com/comlink/-/comlink-4.4.2.tgz#cbbcd82742fbebc06489c28a183eedc5c60a2bca"
>>>>>>> 80e7f8002ed39a2695b6cd492e48a984a2715ef9
integrity sha512-OxGdvBmJuNKSCMO4NTl1L47VRp6xn2wG4F/2hYzB6tiCb709otOxtEYCSvK80PtjODfXXZu8ds+Nw5kVCjqd2g==

comma-separated-tokens@^2.0.0:
Expand Down

0 comments on commit c5f6d82

Please sign in to comment.