Merge pull request #68 from SWQXDBA/main

enum document update
babyfish-ct · Nov 25, 2024 · 6ae5760 · 6ae5760
2 parents eb0894d + c2f3833
commit 6ae5760
Show file tree

Hide file tree

Showing 4 changed files with 177 additions and 5 deletions.
diff --git a/docs/mapping/advanced/enum.mdx b/docs/mapping/advanced/enum.mdx
@@ -204,4 +204,92 @@ Next, we show how to override the global configuration:
     ```
 
     </TabItem>
-    </Tabs>
+    </Tabs>
+
+## Work with TypeScript Client and Jackson
+
+The serialization of a type to JSON and its storage in the database are two independent matters. The content described above focuses on how Jimmer handles enum mapping in the database, which is unrelated to JSON.
+
+By default, Jackson converts enums to its name, so when generating the TypeScript Client, Jimmer maps the enum according to its name.
+
+
+    <Tabs groupId="language">
+    <TabItem value="java" label="Java">
+
+    ```java
+    enum Gender {
+        MAN,
+        WOMAN
+    }
+    ```
+
+    </TabItem>
+    <TabItem value="kotlin" label="Kotlin">
+
+    ```kotlin
+    enum class Gender {
+        MAN,
+        WOMAN
+    }
+    ```
+
+    </TabItem>
+    </Tabs>
+
+The generated TypeScript code is as follows:
+
+    ```TypeScript
+    export const GenderEnum_CONSTANTS = [
+        'MAN',
+        'WOMAN'
+    ] as const;
+    export type GenderEnum = typeof GenderEnum_CONSTANTS[number];
+
+    //usage
+    export type PersonDto = {
+        gender: GenderEnum;
+    }
+    ```
+
+If you want to customize the JSON serialization, you need to use the @JsonValue annotation from Jackson.
+
+    <Tabs groupId="language">
+    <TabItem value="java" label="Java">
+
+    ```java
+    enum Gender {
+        MAN,
+        WOMAN;
+
+        @JsonValue
+        public String getValue() {
+            return name().toLowerCase();
+        }
+    }
+    ```
+
+    </TabItem>
+    <TabItem value="kotlin" label="Kotlin">
+
+    ```kotlin
+    enum class Gender {
+        MAN,
+        WOMAN;
+
+        @JsonValue
+        fun getValue(): String {
+            return name().toLowerCase();
+        }
+    }
+    ```
+
+    </TabItem>
+    </Tabs>
+
+When detects the presence of annotations like @JsonValue, Jimmer not knowing how the enum will be converted during JSON serialization, so jimmer will translates the enum type to a string. The generated TypeScript code in this case is as follows:
+
+    ```TypeScript
+    export type PersonDto = {
+        gender: string;
+    }
+    ```
diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/mapping/advanced/enum.mdx b/i18n/zh/docusaurus-plugin-content-docs/current/mapping/advanced/enum.mdx
@@ -204,4 +204,88 @@ enum class Gender {
     ```
 
     </TabItem>
-    </Tabs>
+    </Tabs>
+
+## 与 Typescript Client and Jackson一起使用
+
+一个类型的Json序列化与数据库中的存储是独立的两件事。上述所描述的内容只是Jimmer在数据库中如何处理枚举映射，与Json无关。
+
+在默认情况下，Jackson将枚举转换为枚举名字符串，所以Jimmer会在生成TypeScript Client的时候按照枚举的Name映射
+
+    <Tabs groupId="language">
+    <TabItem value="java" label="Java">
+
+    ```java
+    enum Gender {
+        MAN,
+        WOMAN
+    }
+    ```
+
+    </TabItem>
+    <TabItem value="kotlin" label="Kotlin">
+
+    ```kotlin
+    enum class Gender {
+        MAN,
+        WOMAN
+    }
+    ```
+
+    </TabItem>
+    </Tabs>
+
+ 生成的TypeScript代码如下：
+    ```TypeScript
+    export const GenderEnum_CONSTANTS = [
+        'MAN',
+        'WOMAN'
+    ] as const;
+    export type GenderEnum = typeof GenderEnum_CONSTANTS[number];
+
+    //使用
+    export type PersonDto = {
+        gender: GenderEnum;
+    }
+    ```
+如果想要自定义Json序列化，需要使用Jackson的@JsonValue注解
+    <Tabs groupId="language">
+    <TabItem value="java" label="Java">
+
+    ```java
+    enum Gender {
+        MAN,
+        WOMAN;
+
+        @JsonValue
+        public String getValue() {
+            return name().toLowerCase();
+        }
+    }
+    ```
+
+    </TabItem>
+    <TabItem value="kotlin" label="Kotlin">
+
+    ```kotlin
+    enum class Gender {
+        MAN,
+        WOMAN;
+
+        @JsonValue
+        fun getValue(): String {
+            return name().toLowerCase();
+        }
+    }
+    ```
+
+    </TabItem>
+    </Tabs>
+
+在检测到存在@JsonValue等注解后，因为jimmer不知道在Json序列化时，枚举会被转换为什么，所以Jimmer会把枚举类型翻译成string，生成的TypeScript代码如下：
+
+    ```TypeScript
+    export type PersonDto = {
+        gender: string;
+    }
+    ```
diff --git a/...usaurus-plugin-content-docs/current/mutation/save-command/association/owner.mdx b/...usaurus-plugin-content-docs/current/mutation/save-command/association/owner.mdx
@@ -8,7 +8,7 @@ import TabItem from '@theme/TabItem';
 
 ## 基本概念
 
-所畏拥有方，只具备`mappedBy`的`@OneToMany`或`@OneToOne`对象。以`@OneToMany`为例
+所谓拥有方，指具备`mappedBy`的`@OneToMany`或`@OneToOne`对象。以`@OneToMany`为例
 
 <Tabs groupId="language">
 <TabItem value="java" label="Java">

diff --git a/...aurus-plugin-content-docs/current/mutation/save-command/data-classification.mdx b/...aurus-plugin-content-docs/current/mutation/save-command/data-classification.mdx
@@ -142,7 +142,7 @@ Jimmer支持`UPSERT`操作，即，用户并不明确指定`insert`或`update`
 ### 3. Key-specified对象
 
 对于一个对象而言，如果`@Id`属性 *(本文的`Book.id`)* 没有被指定，但是其`@Key`属性 *(本文的`Book.name`和`Book.edition`)* 被指定了，
-那么该对爱对象为key-specified对象，例如
+那么该对象为key-specified对象，例如
 
 <Tabs groupId="language">
 <TabItem value="java" label="Java">
@@ -208,7 +208,7 @@ val book = Book {
 
 ### 5. Key-only对象
 
-对于id-specified对象而言，如果除了id外没有任何属性被指定，称为id-only对象，例如
+对于key-specified对象而言，如果除了id外没有任何属性被指定，称为id-only对象，例如
 
 <Tabs groupId="language">
 <TabItem value="java" label="Java">