This is an automated email from the ASF dual-hosted git repository.
chaokunyang pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/fory-site.git
The following commit(s) were added to refs/heads/main by this push:
new 3e0a2d87 Refine all zh docs (#271)
3e0a2d87 is described below
commit 3e0a2d87193b1622e5c67f04a2f207434955f832
Author: Shawn Yang <[email protected]>
AuthorDate: Thu Jun 19 15:04:04 2025 +0800
Refine all zh docs (#271)
---
.../docusaurus-plugin-content-docs/current.json | 4 +-
.../current/docs/guide/_category_.json | 2 +-
.../current/docs/guide/graalvm_guide.md | 79 ++++++----
.../current/docs/guide/java_serialization_guide.md | 11 --
.../current/docs/guide/row_format_guide.md | 98 ++++++++++--
.../current/docs/guide/scala_guide.md | 108 +++++++++----
.../docs/guide/xlang_serialization_guide.md | 51 ++++--
.../current/docs/guide/xlang_type_mapping.md | 174 ++++++++++++---------
8 files changed, 337 insertions(+), 190 deletions(-)
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current.json
b/i18n/zh-CN/docusaurus-plugin-content-docs/current.json
index fcdc27d1..1fb5719b 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/current.json
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current.json
@@ -1,6 +1,6 @@
{
"version.label": {
- "message": "下一步",
+ "message": "版本",
"description": "The label for version current"
}
-}
+}
\ No newline at end of file
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/docs/guide/_category_.json
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/docs/guide/_category_.json
index 5c88c178..a4d4668e 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/docs/guide/_category_.json
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/docs/guide/_category_.json
@@ -1,4 +1,4 @@
{
"position": 3,
"label": "Guide"
-}
\ No newline at end of file
+}
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/docs/guide/graalvm_guide.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/docs/guide/graalvm_guide.md
index 46e04eb4..714efb86 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/docs/guide/graalvm_guide.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/docs/guide/graalvm_guide.md
@@ -2,30 +2,43 @@
title: GraalVM 指南
sidebar_position: 6
id: graalvm_guide
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
---
-## GraalVM Native Image 介绍
+## GraalVM Native Image
-GraalVM Native Image 能够将 Java 应用代码编译成为原生的本地应用程序代码，以构建更快、更小、更精简的应用程序。
-其不能使用 JIT 编译器将字节码编译为机器码，并且在没有配置相关反射文件的前提下不支持反射，在很多情况下使用较为复杂。
+GraalVM 的 `native image` 能将 Java 代码提前编译为本地代码，从而构建更快、更小、更精简的应用。
+Native image 不包含 JIT 编译器，无法在运行时将字节码编译为机器码，也不支持反射，除非配置反射元数据文件。
-Apache Fory 对 GraalVM Native Image 支持非常完善。Apache Fory 在 Graalvm 构建时能够为 `Fory
JIT framework` 和 `MethodHandle/LambdaMetafactory`
生成所有的序列化代码。然后在运行时使用这些生成的代码进行序列化，无需任何额外成本，性能非常出色。
+Fory 在 GraalVM native image 下运行良好。Fory 会在 graalvm 构建阶段为 `Fory JIT framework` 和
`MethodHandle/LambdaMetafactory` 生成所有序列化器代码，运行时直接使用这些生成的代码进行序列化，无需额外开销，性能优异。
-为了在 Graalvm Native Images 上使用 Fory，您必须将 Apache Fory 创建为**静态**的类字段，并且在
`enclosing class` 初始化时间期间完成所有的类**注册**。
然后在`resources/META-INF/native-image/$xxx/` 目录下添加 `native-image.properties`
配置文件。指导 GraalVM 在构建 Native Images 时初始化配置的类。
-
-例如，这里我们在配置文件中加入 `org.apache.fory.graalvm.Example` 类：
+在 graalvm native image 下使用 Fory 时，必须将 Fory 创建为类的**静态**字段，并在类初始化时**注册**所有类型。然后在
`resources/META-INF/native-image/$xxx/native-image.properties` 下配置
`native-image.properties`，告知 graalvm 在 native image 构建时初始化该类。例如，配置
`org.apache.fory.graalvm.Example` 类在构建时初始化：
```properties
Args = --initialize-at-build-time=org.apache.fory.graalvm.Example
```
-使用 Apache Fory 的另一个好处是，您不必配置[反射
JSON](https://www.graalvm.org/latest/reference-manual/native-image/metadata/#specifying-reflection-metadata-in-json)和[序列化
JSON](https://www.graalvm.org/latest/reference-manual/native-image/metadata/#serialization)，这非常乏味、繁琐且不方便。使用
Apache Fory 时，您只需为要序列化的每个类型调用 `org.apache.fory.Fory.register(Class<?>,
boolean)` 即可。
+使用 fory 的另一个好处是无需配置繁琐的 [reflection
json](https://www.graalvm.org/latest/reference-manual/native-image/metadata/#specifying-reflection-metadata-in-json)
和 [serialization
json](https://www.graalvm.org/latest/reference-manual/native-image/metadata/#serialization)。只需对每个需要序列化的类型调用
`org.apache.fory.Fory.register(Class<?>, boolean)` 即可。
-请注意，由于 GraalVM Native Image 在镜像运行时不支持 JIT，因此 Apache Fory 的
`asyncCompilationEnabled` 选项将在使用 GraalVM Native Image 构建应用时自动禁用。
+注意：Fory 的 `asyncCompilationEnabled` 选项在 graalvm native image 下会自动禁用，因为 native
image 运行时不支持 JIT。
-## 线程不安全
+## 非线程安全 Fory
-Example：
+示例：
```java
import org.apache.fory.Fory;
@@ -46,7 +59,7 @@ public class Example {
static {
fory = Fory.builder().build();
- // register and generate serializer code.
+ // 注册并生成序列化器代码。
fory.register(Record.class, true);
}
@@ -61,13 +74,13 @@ public class Example {
}
```
-之后在 `native-image.properties` 中加入 `org.apache.fory.graalvm.Example` 配置：
+然后在 `native-image.properties` 配置中添加 `org.apache.fory.graalvm.Example` 的构建时初始化：
```properties
Args = --initialize-at-build-time=org.apache.fory.graalvm.Example
```
-## 线程安全
+## 线程安全 Fory
```java
import org.apache.fory.Fory;
@@ -91,7 +104,7 @@ public class ThreadSafeExample {
static {
fory = new ThreadLocalFory(classLoader -> {
Fory f = Fory.builder().build();
- // register and generate serializer code.
+ // 注册并生成序列化器代码。
f.register(Foo.class, true);
return f;
});
@@ -110,7 +123,7 @@ public class ThreadSafeExample {
}
```
-之后在 `native-image.properties` 中加入 `org.apache.fory.graalvm.ThreadSafeExample`
配置：
+然后在 `native-image.properties` 配置中添加
`org.apache.fory.graalvm.ThreadSafeExample` 的构建时初始化：
```properties
Args = --initialize-at-build-time=org.apache.fory.graalvm.ThreadSafeExample
@@ -118,25 +131,25 @@ Args =
--initialize-at-build-time=org.apache.fory.graalvm.ThreadSafeExample
## 框架集成
-对于框架开发人员，如果您想集成 Apache Fory 进行序列化。您可以提供一个配置文件，让用户列出他们想要序列化的所有类，然后您可以加载这些类并调用
`org.apache.fory.Fory.register(Class<?>, boolean)` 在您的 Fory 集成类中注册这些类，并配置该类在
GraalVM Native Image 构建时进行初始化。
+对于框架开发者，如果希望集成 fory 作为序列化方案，可以提供一个配置文件，让用户列出所有需要序列化的类，然后加载这些类并在 Fory 集成类中调用
`org.apache.fory.Fory.register(Class<?>, boolean)` 进行注册，并配置该类在 graalvm native
image 构建时初始化。
-## 基准测试
+## Benchmark
-在这里，我们给出了 Apache Fory 和 Graalvm 序列化之间的两个类基准测试。
+这里给出 Fory 与 Graalvm Serialization 的两个类的基准测试。
-禁用 Apache Fory compression 时：
+Fory 未开启压缩时：
-- Struct：Fory 与 `46x speed, 43% size` JDK 进行比较。
-- Pojo：Fory 与 `12x speed, 56% size` JDK进行比较。
+- Struct：Fory 为 JDK 的 `46x 速度，43% 大小`
+- Pojo：Fory 为 JDK 的 `12x 速度，56% 大小`
-启用 Apache Fory compression 时：
+Fory 开启压缩时：
-- Struct：Fory 与 `24x speed, 31% size` JDK进行比较。
-- Pojo：Fory 与 `12x speed, 48% size` JDK进行比较。
+- Struct：Fory 为 JDK 的 `24x 速度，31% 大小`
+- Pojo：Fory 为 JDK 的 `12x 速度，48% 大小`
-有关基准测试代码，请参阅
[Benchmark.java](https://github.com/apache/fory/blob/main/integration_tests/graalvm_tests/src/main/java/org/apache/fory/graalvm/Benchmark.java)。
+基准测试代码见
[[Benchmark.java](https://github.com/apache/fory/blob/main/integration_tests/graalvm_tests/src/main/java/org/apache/fory/graalvm/Benchmark.java)]。
-### 结构体基准测试
+### Struct 基准测试
#### 类字段
@@ -157,9 +170,9 @@ public class Struct implements Serializable {
}
```
-#### 基准测试结果
+#### Benchmark 结果
-不开启压缩时测试结果：
+未压缩：
```
Benchmark repeat number: 400000
@@ -173,7 +186,7 @@ Compare speed: Fory is 45.70x speed of JDK
Compare size: Fory is 0.43x size of JDK
```
-开启压缩时测试结果：
+压缩：
```
Benchmark repeat number: 400000
@@ -200,9 +213,9 @@ public class Foo implements Serializable {
}
```
-#### 基准测试结果
+#### Benchmark 结果
-不开启压缩时测试结果：
+未压缩：
```
Benchmark repeat number: 400000
@@ -216,7 +229,7 @@ Compare speed: Fory is 12.19x speed of JDK
Compare size: Fory is 0.56x size of JDK
```
-开启压缩时测试结果：
+压缩：
```
Benchmark repeat number: 400000
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/docs/guide/java_serialization_guide.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/docs/guide/java_serialization_guide.md
index c05eee6b..f9f09421 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/docs/guide/java_serialization_guide.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/docs/guide/java_serialization_guide.md
@@ -825,14 +825,3 @@ public class DeserializeIntoType {
- 用 `Fory#serialize` 序列化的对象，需用 `Fory#deserialize` 反序列化，不能用
`Fory#deserializeJavaObject`。
- 用 `Fory#serializeJavaObject` 序列化的对象，需用 `Fory#deserializeJavaObject` 反序列化，不能用
`Fory#deserializeJavaObjectAndClass` 或 `Fory#deserialize`。
- 用 `Fory#serializeJavaObjectAndClass` 序列化的对象，需用
`Fory#deserializeJavaObjectAndClass` 反序列化，不能用其他 API。
-
-```java
-// 示例
-if (serializeBy == "serialize") {
- fory.deserialize(bytes);
-} else if (serializeBy == "serializeJavaObject") {
- fory.deserializeJavaObject(bytes, SomeClass.class);
-} else if (serializeBy == "serializeJavaObjectAndClass") {
- fory.deserializeJavaObjectAndClass(bytes);
-}
-```
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/docs/guide/row_format_guide.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/docs/guide/row_format_guide.md
index 5699b372..752bc5e9 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/docs/guide/row_format_guide.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/docs/guide/row_format_guide.md
@@ -1,12 +1,25 @@
---
-title: Row format 指南
+title: 行格式指南
sidebar_position: 1
id: row_format_guide
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
---
-## Row format protocol
-
-### Java
+## Java
```java
public class Bar {
@@ -34,26 +47,26 @@ for (int i = 0; i < 1000000; i++) {
bars.add(bar);
}
foo.f4 = bars;
-// Can be zero-copy read by python
+// 可被 python 零拷贝读取
BinaryRow binaryRow = encoder.toRow(foo);
-// can be data from python
+// 也可以是 python 生成的数据
Foo newFoo = encoder.fromRow(binaryRow);
-// zero-copy read List<Integer> f2
+// 零拷贝读取 List<Integer> f2
BinaryArray binaryArray2 = binaryRow.getArray(1);
-// zero-copy read List<Bar> f4
+// 零拷贝读取 List<Bar> f4
BinaryArray binaryArray4 = binaryRow.getArray(3);
-// zero-copy read 11th element of `readList<Bar> f4`
+// 零拷贝读取 `readList<Bar> f4` 的第 11 个元素
BinaryRow barStruct = binaryArray4.getStruct(10);
-// zero-copy read 6th of f2 of 11th element of `readList<Bar> f4`
+// 零拷贝读取 `readList<Bar> f4` 第 11 个元素的 f2 的第 6 个元素
barStruct.getArray(1).getInt64(5);
RowEncoder<Bar> barEncoder = Encoders.bean(Bar.class);
-// deserialize part of data.
+// 只反序列化部分数据
Bar newBar = barEncoder.fromRow(barStruct);
Bar newBar2 = barEncoder.fromRow(binaryArray4.getStruct(20));
```
-### Python
+## Python
```python
@dataclass
@@ -86,9 +99,9 @@ print(f"pickle end: {datetime.datetime.now()}")
### Apache Arrow 支持
-Apache Fory Format 还支持从 Arrow Table/RecordBatch 自动转换。
+Fory Format 也支持与 Arrow Table/RecordBatch 的自动转换。
-Java：
+Java 示例：
```java
Schema schema = TypeInference.inferSchema(BeanA.class);
@@ -101,7 +114,60 @@ for (int i = 0; i < 10; i++) {
return arrowWriter.finishAsRecordBatch();
```
-Python：
+## 支持接口与继承类型
+
+Fury 现已支持 Java `interface` 类型和子类（`extends`）类型的行格式映射，带来更动态和灵活的数据 schema。
+
+相关增强见
[#2243](https://github.com/apache/fury/pull/2243)、[#2250](https://github.com/apache/fury/pull/2250)、[#2256](https://github.com/apache/fury/pull/2256)。
+
+### 示例：接口类型的 RowEncoder 映射
+
+```java
+public interface Animal {
+ String speak();
+}
+
+public class Dog implements Animal {
+ public String name;
+
+ @Override
+ public String speak() {
+ return "Woof";
+ }
+}
+
+// 使用 RowEncoder 以接口类型编码和解码
+RowEncoder<Animal> encoder = Encoders.bean(Animal.class);
+Dog dog = new Dog();
+dog.name = "Bingo";
+BinaryRow row = encoder.toRow(dog);
+Animal decoded = encoder.fromRow(row);
+System.out.println(decoded.speak()); // Woof
+
+```
+
+### 示例：继承类型的 RowEncoder 映射
+
+```java
+public class Parent {
+ public String parentField;
+}
+
+public class Child extends Parent {
+ public String childField;
+}
+
+// 使用 RowEncoder 以父类类型编码和解码
+RowEncoder<Parent> encoder = Encoders.bean(Parent.class);
+Child child = new Child();
+child.parentField = "Hello";
+child.childField = "World";
+BinaryRow row = encoder.toRow(child);
+Parent decoded = encoder.fromRow(row);
+
+```
+
+Python 示例：
```python
import pyfory
@@ -110,7 +176,7 @@ encoder.to_arrow_record_batch([foo] * 10000)
encoder.to_arrow_table([foo] * 10000)
```
-C++:
+C++ 示例：
```c++
std::shared_ptr<ArrowWriter> arrow_writer;
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/docs/guide/scala_guide.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/docs/guide/scala_guide.md
index e012e016..682e9542 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/docs/guide/scala_guide.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/docs/guide/scala_guide.md
@@ -2,54 +2,98 @@
title: Scala 序列化指南
sidebar_position: 4
id: scala_guide
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
---
-Apache Fory 支持所有 Scala 对象序列化：
+Fory 支持所有 Scala 对象的序列化：
-- `case` 支持类序列化；
-- `pojo/bean` 支持类序列化；
-- `object` 支持单例序列化；
-- `collection` 支持序列化；
-- 其他类型（如 `tuple/either` AND BASIC 类型）也都受支持。
+- 支持 `case` class 序列化
+- 支持 `pojo/bean` class 序列化
+- 支持 `object` 单例对象序列化
+- 支持 `collection` 集合序列化
+- 其他类型如 `tuple/either` 以及基础类型也都支持
-Scala 2 和 3 均支持。
+同时支持 Scala 2 和 Scala 3。
## 安装
+如果你使用 sbt 并希望在 Scala 2 项目中引入 Fory Scala 依赖，请添加如下内容：
+
```sbt
-libraryDependencies += "org.apache.fory" % "fory-core" % "0.7.1"
+libraryDependencies += "org.apache.fory" % "fory-scala_2.13" % "0.11.0"
```
-## Fory 对象创建
+如果你使用 sbt 并希望在 Scala 3 项目中引入 Fory Scala 依赖，请添加如下内容：
+
+```sbt
+libraryDependencies += "org.apache.fory" % "fory-scala_3" % "0.11.0"
+```
-当使用 Apache Fory 进行 Scala 序列化时，您应该至少使用以下选项创建 Fory 对象：
+## 快速开始
```scala
-val fory = Fory.builder()
- .withScalaOptimizationEnabled(true)
- .requireClassRegistration(true)
- .withRefTracking(true)
- .build()
+case class Person(name: String, id: Long, github: String)
+case class Point(x : Int, y : Int, z : Int)
+
+object ScalaExample {
+ val fory: Fory = Fory.builder().withScalaOptimizationEnabled(true).build()
+ // 注册针对 Scala 优化的 fory 序列化器
+ ScalaSerializers.registerSerializers(fory)
+ fory.register(classOf[Person])
+ fory.register(classOf[Point])
+
+ def main(args: Array[String]): Unit = {
+ val p = Person("Shawn Yang", 1, "https://github.com/chaokunyang";)
+ println(fory.deserialize(fory.serialize(p)))
+ println(fory.deserialize(fory.serialize(Point(1, 2, 3))))
+ }
+}
```
-根据您序列化的对象类型，您可能需要注册一些 Scala 的内部类型：
+## Fory 实例创建
+
+在使用 fory 进行 Scala 序列化时，建议至少以如下方式创建 fory 实例：
```scala
-fory.register(Class.forName("scala.collection.generic.DefaultSerializationProxy"))
-fory.register(Class.forName("scala.Enumeration.Val"))
+import org.apache.fory.Fory
+import org.apache.fory.serializer.scala.ScalaSerializers
+
+val fory = Fory.builder().withScalaOptimizationEnabled(true).build()
+
+// 注册针对 Scala 优化的 fory 序列化器
+ScalaSerializers.registerSerializers(fory)
```
-如果要避免此类注册，可以通过禁用类 `ForyBuilder#requireClassRegistration(false)` 来完成。
+根据你需要序列化的对象类型，可能还需要注册一些 Scala 内部类型：
+
+```scala
+fory.register(Class.forName("scala.Enumeration.Val"))
+```
-> 请注意：此选项可以反序列化未知的对象类型，使用更灵活。但如果类包含任何的恶意代码，会有安全风险。
+如果你希望避免手动注册这些类型，可以通过 `ForyBuilder#requireClassRegistration(false)` 关闭类注册功能。
+注意：关闭类注册后，可以反序列化未知类型的对象，灵活性更高，但如果反序列化的类包含恶意代码，可能存在安全风险。
-循环引用在 Scala 中很常见，`Reference tracking` 应该由 `ForyBuilder#withRefTracking(true)`
配置选项开启。如果不启用 `Reference tracking`，则在序列化 Scala Enumeration 时，某些 Scala 版本可能会发生
[StackOverflowError 错误](https://github.com/apache/fory/issues/1032)。
+Scala 中循环引用较为常见，建议通过 `ForyBuilder#withRefTracking(true)` 启用引用跟踪（Reference
tracking）。如果未启用引用跟踪，在某些 Scala 版本下序列化 Scala Enumeration 时，可能会出现
[StackOverflowError](https://github.com/apache/fory/issues/1032)。
-> 注意：Fory 实例应该在多个序列化之间共享，创建 Fory 实例开销很大，应该尽量复用。
+注意：fory 实例应在多次序列化操作间复用，fory 实例的创建开销较大。
-如果您在多个线程中使用共享的 Fory 实例，您应该使用 `ThreadSafeFory` 代替
`ForyBuilder#buildThreadSafeFory()`。
+如果你需要在多线程环境下共享 fory 实例，应通过 `ForyBuilder#buildThreadSafeFory()` 创建
`ThreadSafeFory` 实例。
-## 序列化 case 对象
+## 序列化 case class
```scala
case class Person(github: String, age: Int, id: Long)
@@ -67,7 +111,7 @@ class Foo(f1: Int, f2: String) {
println(fory.deserialize(fory.serialize(Foo(1, "chaokunyang"))))
```
-## 序列化对象单例
+## 序列化 object 单例对象
```scala
object singleton {
@@ -77,7 +121,7 @@ val o2 = fory.deserialize(fory.serialize(singleton))
println(o1 == o2)
```
-## 序列化集合
+## 序列化集合（Collection）
```scala
val seq = Seq(1,2)
@@ -88,7 +132,7 @@ println(fory.deserialize(fory.serialize(list)))
println(fory.deserialize(fory.serialize(map)))
```
-## 序列化元组
+## 序列化 Tuple
```scala
val tuple = Tuple2(100, 10000L)
@@ -97,16 +141,16 @@ val tuple = Tuple4(100, 10000L, 10000L, "str")
println(fory.deserialize(fory.serialize(tuple)))
```
-## 序列化枚举
+## 序列化 Enum
-### Scala3 枚举
+### Scala3 Enum
```scala
enum Color { case Red, Green, Blue }
println(fory.deserialize(fory.serialize(Color.Green)))
```
-### Scala2 枚举
+### Scala2 Enum
```scala
object ColorEnum extends Enumeration {
@@ -116,7 +160,7 @@ object ColorEnum extends Enumeration {
println(fory.deserialize(fory.serialize(ColorEnum.Green)))
```
-## 序列化 Option 类型
+## 序列化 Option
```scala
val opt: Option[Long] = Some(100)
@@ -127,7 +171,7 @@ println(fory.deserialize(fory.serialize(opt1)))
## 性能
- `pojo/bean/case/object` Scala 对 Apache Fory JIT 的支持很好，性能与 Apache Fory Java
一样优异。
+`pojo/bean/case/object` Scala 对 Apache Fory JIT 的支持很好，性能与 Apache Fory Java
一样优异。
Scala 集合和泛型不遵循 Java 集合框架，并且未与当前发行版中的 Apache Fory JIT 完全集成。性能不会像 Java 的 Fory
collections 序列化那么好。
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/docs/guide/xlang_serialization_guide.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/docs/guide/xlang_serialization_guide.md
index 8576f322..7f35e2f7 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/docs/guide/xlang_serialization_guide.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/docs/guide/xlang_serialization_guide.md
@@ -2,6 +2,21 @@
title: 多语言序列化指南
sidebar_position: 2
id: xlang_object_graph_guide
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
---
## 跨语言对象图序列化
@@ -96,17 +111,17 @@ func main() {
**JavaScript**
```javascript
-import Fory from '@foryjs/fory';
+import Fory from "@foryjs/fory";
/**
* @foryjs/hps use v8's fast-calls-api that can be called directly by jit,
ensure that the version of Node is 20 or above.
* Experimental feature, installation success cannot be guaranteed at this
moment
* If you are unable to install the module, replace it with `const hps = null;`
**/
-import hps from '@foryjs/hps';
+import hps from "@foryjs/hps";
const fory = new Fory({ hps });
-const input = fory.serialize('hello fory');
+const input = fory.serialize("hello fory");
const result = fory.deserialize(input);
console.log(result);
```
@@ -315,22 +330,22 @@ func main() {
**JavaScript**
```javascript
-import Fory, { Type, InternalSerializerType } from '@foryjs/fory';
+import Fory, { Type, InternalSerializerType } from "@foryjs/fory";
/**
* @foryjs/hps use v8's fast-calls-api that can be called directly by jit,
ensure that the version of Node is 20 or above.
* Experimental feature, installation success cannot be guaranteed at this
moment
* If you are unable to install the module, replace it with `const hps = null;`
**/
-import hps from '@foryjs/hps';
+import hps from "@foryjs/hps";
// Now we describe data structures using JSON, but in the future, we will use
more ways.
-const description = Type.object('example.foo', {
+const description = Type.object("example.foo", {
foo: Type.string(),
});
const fory = new Fory({ hps });
const { serialize, deserialize } = fory.registerSerializer(description);
-const input = serialize({ foo: 'hello fory' });
+const input = serialize({ foo: "hello fory" });
const result = deserialize(input);
console.log(result);
```
@@ -396,7 +411,7 @@ fn complex_struct() {
### 序列化共享引用和循环引用
-共享引用和循环引用可自动序列化，不会出现重复数据或递归错误。
+共享引用和循环引用可以被自动序列化，不会产生重复数据或递归错误。
**Java**
@@ -444,7 +459,7 @@ class SomeClass:
f3: Dict[str, str]
fory = pyfory.Fory(ref_tracking=True)
-fory.register_class(SomeClass, type_tag="example.SomeClass")
+fory.register_type(SomeClass, typename="example.SomeClass")
obj = SomeClass()
obj.f2 = {"k1": "v1", "k2": "v2"}
obj.f1, obj.f3 = obj, obj.f2
@@ -476,6 +491,7 @@ func main() {
value.F1 = value
bytes, err := fory.Marshal(value)
if err != nil {
+ panic(err)
}
var newValue interface{}
// bytes can be data serialized by other languages.
@@ -489,23 +505,23 @@ func main() {
**JavaScript**
```javascript
-import Fory, { Type } from '@foryjs/fory';
+import Fory, { Type } from "@foryjs/fory";
/**
* @foryjs/hps use v8's fast-calls-api that can be called directly by jit,
ensure that the version of Node is 20 or above.
* Experimental feature, installation success cannot be guaranteed at this
moment
* If you are unable to install the module, replace it with `const hps = null;`
**/
-import hps from '@foryjs/hps';
+import hps from "@foryjs/hps";
-const description = Type.object('example.foo', {
+const description = Type.object("example.foo", {
foo: Type.string(),
- bar: Type.object('example.foo'),
+ bar: Type.object("example.foo"),
});
const fory = new Fory({ hps });
const { serialize, deserialize } = fory.registerSerializer(description);
-const data: any = {
- foo: 'hello fory',
+const data = {
+ foo: "hello fory",
};
data.bar = data;
const input = serialize(data);
@@ -513,8 +529,9 @@ const result = deserialize(input);
console.log(result.bar.foo === result.foo);
```
-**JavaScript**
-Reference cannot be implemented because of rust ownership restrictions
+**Rust**
+
+由于 Rust 所有权限制，暂不支持引用类型的序列化
### Zero-Copy Serialization
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/docs/guide/xlang_type_mapping.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/docs/guide/xlang_type_mapping.md
index 9c289376..1a047dad 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/docs/guide/xlang_type_mapping.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/docs/guide/xlang_type_mapping.md
@@ -1,95 +1,113 @@
---
-title: 多语言序列化的类型映射
+title: 跨语言序列化的类型映射
sidebar_position: 3
id: xlang_type_mapping
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
---
注意：
-- 有关类型定义，请参阅 [Spec
中的类型系统](https://fory.apache.org/docs/specification/fory_xlang_serialization_spec#type-systems)
-- `int16_t[n]/vector<T>` 表示 `int16_t[n]/vector<int16_t>`.
-- 跨语言序列化并不稳定，请勿在生产环境中使用。
-
-## Type Mapping
-
-| Fory 类型 | Fory 类型 ID | Java | Python |
Javascript | C++ | Golang | Rust
|
-|--------------------|--------------|-----------------|----------------------|-----------------|--------------------------------|------------------|------------------|
-| bool | 1 | bool/Boolean | bool |
Boolean | bool | bool | bool
|
-| int8 | 2 | byte/Byte | int/pyfory.Int8 |
Type.int8() | int8_t | int8 | i8
|
-| int16 | 3 | short/Short | int/pyfory.Int16 |
Type.int16() | int16_t | int16 | i6
|
-| int32 | 4 | int/Integer | int/pyfory.Int32 |
Type.int32() | int32_t | int32 | i32
|
-| var_int32 | 5 | int/Integer | int/pyfory.VarInt32 |
Type.varint32() | fory::varint32_t | fory.varint32 |
fory::varint32 |
-| int64 | 6 | long/Long | int/pyfory.Int64 |
Type.int64() | int64_t | int64 | i64
|
-| var_int64 | 7 | long/Long | int/pyfory.VarInt64 |
Type.varint64() | fory::varint64_t | fory.varint64 |
fory::varint64 |
-| sli_int64 | 8 | long/Long | int/pyfory.SliInt64 |
Type.sliint64() | fory::sliint64_t | fory.sliint64 |
fory::sliint64 |
-| float16 | 9 | float/Float | float/pyfory.Float16 |
Type.float16() | fory::float16_t | fory.float16 | fory::f16
|
-| float32 | 10 | float/Float | float/pyfory.Float32 |
Type.float32() | float | float32 | f32
|
-| float64 | 11 | double/Double | float/pyfory.Float64 |
Type.float64() | double | float64 | f64
|
-| string | 12 | String | str |
String | string | string |
String/str |
-| enum | 13 | Enum subclasses | enum subclasses |
/ | enum | / | enum
|
-| list | 14 | List/Collection | list/tuple |
array | vector | slice | Vec
|
-| set | 15 | Set | set |
/ | set | fory.Set | Set
|
-| map | 16 | Map | dict |
Map | unordered_map | map | HashMap
|
-| duration | 17 | Duration | timedelta |
Number | duration | Duration | Duration
|
-| timestamp | 18 | Instant | datetime |
Number | std::chrono::nanoseconds | Time | DateTime
|
-| decimal | 19 | BigDecimal | Decimal |
bigint | / | / | /
|
-| binary | 20 | byte[] | bytes |
/ | `uint8_t[n]/vector<T>` | `[n]uint8/[]T` |
`Vec<uint8_t>` |
-| array | 21 | array | np.ndarray |
/ | / | array/slice | Vec
|
-| bool_array | 22 | bool[] | ndarray(np.bool_) |
/ | `bool[n]` | `[n]bool/[]T` |
`Vec<bool>` |
-| int8_array | 23 | byte[] | ndarray(int8) |
/ | `int8_t[n]/vector<T>` | `[n]int8/[]T` |
`Vec<i18>` |
-| int16_array | 24 | short[] | ndarray(int16) |
/ | `int16_t[n]/vector<T>` | `[n]int16/[]T` |
`Vec<i16>` |
-| int32_array | 25 | int[] | ndarray(int32) |
/ | `int32_t[n]/vector<T>` | `[n]int32/[]T` |
`Vec<i32>` |
-| int64_array | 26 | long[] | ndarray(int64) |
/ | `int64_t[n]/vector<T>` | `[n]int64/[]T` |
`Vec<i64>` |
-| float16_array | 27 | float[] | ndarray(float16) |
/ | `fory::float16_t[n]/vector<T>` | `[n]float16/[]T` |
`Vec<fory::f16>` |
-| float32_array | 28 | float[] | ndarray(float32) |
/ | `float[n]/vector<T>` | `[n]float32/[]T` |
`Vec<f32>` |
-| float64_array | 29 | double[] | ndarray(float64) |
/ | `double[n]/vector<T>` | `[n]float64/[]T` |
`Vec<f64>` |
-| tensor | 30 | / | / |
/ | / | / | /
|
-| sparse tensor | 31 | / | / |
/ | / | / | /
|
-| arrow record batch | 32 | / | / |
/ | / | / | /
|
-| arrow table | 33 | / | / |
/ | / | / | /
|
-
-### 类型信息（目前尚未实现）
-
-由于语言类型系统之间的差异，这些类型无法在语言之间一对一地映射。
-
-如果用户看到一种语言中的一种类型对应 Apache Fory 类型系统中的多种类型。
-
-例如：java 中的 `long` 类型对应 `int64/varint64/sliint64` 类型。类型为
`int64/varint64/sliint64` 这意味着该语言缺少某些类型，用户在使用 Fory 时必须提供额外的类型信息。
-
-### 类型注解
-
-如果类型是另一个类的字段，用户可以为类型的字段或整个类型提供 meta hints。
-这些信息也可以用其他语言提供：
-
-- java：使用注解；
-- cpp：使用宏和模板；
-- golang：使用 struct tag；
-- python: 使用 typehint；
-- rust：使用宏。
-
-下面是一个例子：
+- 类型定义请参见 [规范中的类型系统](/specification/xlang_serialization_spec.md#type-systems)
+- `int16_t[n]/vector<T>` 表示 `int16_t[n]/vector<int16_t>`
+- 跨语言序列化功能尚不稳定，请勿在生产环境中使用。
+
+## 类型映射
+
+| Fory Type | Fory Type ID | Java | Python
| Javascript | C++ | Golang
| Rust |
+| ----------------------- | ------------ | --------------- |
--------------------------------- | --------------- |
------------------------------ | ---------------- | ---------------- |
+| bool | 1 | bool/Boolean | bool
| Boolean | bool | bool
| bool |
+| int8 | 2 | byte/Byte | int/pyfory.Int8
| Type.int8() | int8_t | int8
| i8 |
+| int16 | 3 | short/Short | int/pyfory.Int16
| Type.int16() | int16_t | int16
| i6 |
+| int32 | 4 | int/Integer | int/pyfory.Int32
| Type.int32() | int32_t | int32
| i32 |
+| var_int32 | 5 | int/Integer |
int/pyfory.VarInt32 | Type.varint32() | fory::varint32_t
| fory.varint32 | fory::varint32 |
+| int64 | 6 | long/Long | int/pyfory.Int64
| Type.int64() | int64_t | int64
| i64 |
+| var_int64 | 7 | long/Long |
int/pyfory.VarInt64 | Type.varint64() | fory::varint64_t
| fory.varint64 | fory::varint64 |
+| sli_int64 | 8 | long/Long |
int/pyfory.SliInt64 | Type.sliint64() | fory::sliint64_t
| fory.sliint64 | fory::sliint64 |
+| float16 | 9 | float/Float |
float/pyfory.Float16 | Type.float16() | fory::float16_t
| fory.float16 | fory::f16 |
+| float32 | 10 | float/Float |
float/pyfory.Float32 | Type.float32() | float
| float32 | f32 |
+| float64 | 11 | double/Double |
float/pyfory.Float64 | Type.float64() | double
| float64 | f64 |
+| string | 12 | String | str
| String | string | string
| String/str |
+| enum | 13 | Enum subclasses | enum subclasses
| / | enum | /
| enum |
+| named_enum | 14 | Enum subclasses | enum subclasses
| / | enum | /
| enum |
+| struct | 15 | pojo/record | data class / type
with type hints | object | struct/class | struct
| struct |
+| compatible_struct | 16 | pojo/record | data class / type
with type hints | object | struct/class | struct
| struct |
+| named_struct | 17 | pojo/record | data class / type
with type hints | object | struct/class | struct
| struct |
+| named_compatible_struct | 18 | pojo/record | data class / type
with type hints | object | struct/class | struct
| struct |
+| ext | 19 | pojo/record | data class / type
with type hints | object | struct/class | struct
| struct |
+| named_ext | 20 | pojo/record | data class / type
with type hints | object | struct/class | struct
| struct |
+| list | 21 | List/Collection | list/tuple
| array | vector | slice
| Vec |
+| set | 22 | Set | set
| / | set | fory.Set
| Set |
+| map | 23 | Map | dict
| Map | unordered_map | map
| HashMap |
+| duration | 24 | Duration | timedelta
| Number | duration | Duration
| Duration |
+| timestamp | 25 | Instant | datetime
| Number | std::chrono::nanoseconds | Time
| DateTime |
+| local_date | 26 | Date | datetime
| Number | std::chrono::nanoseconds | Time
| DateTime |
+| decimal | 27 | BigDecimal | Decimal
| bigint | / | /
| / |
+| binary | 28 | byte[] | bytes
| / | `uint8_t[n]/vector<T>` |
`[n]uint8/[]T` | `Vec<uint8_t>` |
+| array | 29 | array | np.ndarray
| / | / |
array/slice | Vec |
+| bool_array | 30 | bool[] |
ndarray(np.bool\_) | / | `bool[n]`
| `[n]bool/[]T` | `Vec<bool>` |
+| int8_array | 31 | byte[] | ndarray(int8)
| / | `int8_t[n]/vector<T>` |
`[n]int8/[]T` | `Vec<i18>` |
+| int16_array | 32 | short[] | ndarray(int16)
| / | `int16_t[n]/vector<T>` |
`[n]int16/[]T` | `Vec<i16>` |
+| int32_array | 33 | int[] | ndarray(int32)
| / | `int32_t[n]/vector<T>` |
`[n]int32/[]T` | `Vec<i32>` |
+| int64_array | 34 | long[] | ndarray(int64)
| / | `int64_t[n]/vector<T>` |
`[n]int64/[]T` | `Vec<i64>` |
+| float16_array | 35 | float[] | ndarray(float16)
| / | `fory::float16_t[n]/vector<T>` |
`[n]float16/[]T` | `Vec<fory::f16>` |
+| float32_array | 36 | float[] | ndarray(float32)
| / | `float[n]/vector<T>` |
`[n]float32/[]T` | `Vec<f32>` |
+| float64_array | 37 | double[] | ndarray(float64)
| / | `double[n]/vector<T>` |
`[n]float64/[]T` | `Vec<f64>` |
+| arrow record batch | 38 | / | /
| / | / | /
| / |
+| arrow table | 39 | / | /
| / | / | /
| / |
+
+## 类型信息（当前未实现）
+
+由于各语言的类型系统存在差异，某些类型无法做到一一映射。
+
+如果用户发现某一语言的类型在 Fory 类型系统中对应多个类型，例如 Java 中的 `long` 对应
`int64/varint64/sliint64`，这意味着该语言缺少某些类型，用户在使用 Fory 时需要额外提供类型信息。
+
+## 类型注解
+
+如果类型是另一个类的字段，用户可以为类型的字段或整个类型提供元信息提示。
+这些信息在其他语言中也可以提供：
+
+- Java：使用 annotation。
+- C++：使用宏和模板。
+- Golang：使用 struct tag。
+- Python：使用 typehint。
+- Rust：使用宏。
+
+示例：
- Java:
- ```java
- class Foo {
- @Int32Type(varint = true)
- int f1;
- List<@Int32Type(varint = true) Integer> f2;
- }
- ```
+ ```java
+ class Foo {
+ @Int32Type(varint = true)
+ int f1;
+ List<@Int32Type(varint = true) Integer> f2;
+ }
+ ```
- Python:
- ```python
- class Foo:
- f1: Int32Type(varint=True)
- f2: List[Int32Type(varint=True)]
- ```
+ ```python
+ class Foo:
+ f1: Int32Type(varint=True)
+ f2: List[Int32Type(varint=True)]
+ ```
## 类型包装器
-如果类型不是类的字段，用户必须用 Fory 类型来包装该类型，以传递额外的类型信息。
+如果类型不是类的字段，用户必须用 Fory 类型包装该类型以传递额外的类型信息。
-例如：假设 Apache Fory Java 提供了 `VarInt64` 类型，当用户调用 `fory.serialize(long_value)`
时，需要像下面这样调用
-调用 `fory.serialize(new VarInt64(long_value))`。
+例如，假设 Fory Java 提供了 `VarInt64` 类型，当用户调用 `fory.serialize(long_value)`
时，需要这样调用：`fory.serialize(new VarInt64(long_value))`。
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
