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
commit 29c8070ce0b18cf75e8bd63781beffc0faf7dad8 Author: chaokunyang <[email protected]> AuthorDate: Mon Jul 27 03:02:44 2026 +0000 🔄 synced local 'docs/guide/' with remote 'docs/guide/' --- docs/guide/dart/code-generation.md | 12 +- docs/guide/dart/custom-serializers.md | 18 +- docs/guide/dart/external-types.md | 310 ++++++++++++++++++++++++++++++++ docs/guide/dart/grpc-support.md | 2 +- docs/guide/dart/index.md | 32 ++-- docs/guide/dart/schema-evolution.md | 7 +- docs/guide/dart/schema-metadata.md | 6 +- docs/guide/dart/supported-types.md | 6 +- docs/guide/dart/troubleshooting.md | 22 ++- docs/guide/dart/type-registration.md | 25 ++- docs/guide/dart/web-platform-support.md | 7 +- docs/guide/dart/xlang-serialization.md | 29 ++- 12 files changed, 437 insertions(+), 39 deletions(-) diff --git a/docs/guide/dart/code-generation.md b/docs/guide/dart/code-generation.md index 09d8ee7df9..01624e3007 100644 --- a/docs/guide/dart/code-generation.md +++ b/docs/guide/dart/code-generation.md @@ -52,6 +52,10 @@ class User { Enums defined in the same file are automatically included in the generated registration. +For a class owned by another library, define an +[external structural serializer](external-types.md) with +`@ForyStruct(target: ExternalType)`. + ## Step 2 — Run the Generator From the directory that contains your `pubspec.yaml`: @@ -103,12 +107,16 @@ class Event { When using evolving structs, also assign stable field IDs with `@ForyField(id: ...)` before you ship your first payload — those IDs are how Fory matches fields after a schema change. -## When Not to Use Code Generation +## Choosing Generated or Manual Serialization -If you cannot annotate a type (e.g., it comes from a package you do not own), write a [Custom Serializer](custom-serializers.md) instead. +Use an [external structural serializer](external-types.md) when another +package's class exposes matching public getters and a safe public construction +path. Use a [manual serializer](custom-serializers.md) when the wire body, +field names, values, or construction need custom logic. ## Related Topics - [Type Registration](type-registration.md) +- [External-Type Serialization](external-types.md) - [Schema Metadata](schema-metadata.md) - [Schema Evolution](schema-evolution.md) diff --git a/docs/guide/dart/custom-serializers.md b/docs/guide/dart/custom-serializers.md index 4e76736411..14c677fde5 100644 --- a/docs/guide/dart/custom-serializers.md +++ b/docs/guide/dart/custom-serializers.md @@ -1,6 +1,6 @@ --- -title: Custom Serializers -sidebar_position: 9 +title: Manual Serializers +sidebar_position: 10 id: custom_serializers license: | Licensed to the Apache Software Foundation (ASF) under one or more @@ -19,13 +19,18 @@ license: | limitations under the License. --- -A custom serializer lets you control exactly how a type is encoded and decoded. You only need one when: +A manual serializer lets you control exactly how a type is encoded and decoded. +Use one when: -- the type comes from a package you cannot modify and cannot be annotated with `@ForyStruct()` - you need a completely custom binary layout +- the target requires field-name translation or value conversion +- the target exposes only factory or private construction +- the target's complete state is not available through matching public members - you are implementing a union/discriminated type -For your own models, `@ForyStruct()` with code generation is almost always the better choice. +Use `@ForyStruct()` for your own models. For a structurally matching class in +another package, use an +[external structural serializer](external-types.md). ## Implement `Serializer<T>` @@ -113,7 +118,7 @@ final class ShapeSerializer extends UnionSerializer<Shape> { } ``` -## Circular References in Custom Serializers +## Circular References in Manual Serializers If your serializer can encounter circular object graphs, bind the object to the reference tracker **before** reading its nested fields: @@ -134,5 +139,6 @@ Skipping this step causes back-references to that object to resolve to `null`. ## Related Topics - [Type Registration](type-registration.md) +- [External-Type Serialization](external-types.md) - [Xlang Serialization](xlang-serialization.md) - [Troubleshooting](troubleshooting.md) diff --git a/docs/guide/dart/external-types.md b/docs/guide/dart/external-types.md new file mode 100644 index 0000000000..0d9e96c6c5 --- /dev/null +++ b/docs/guide/dart/external-types.md @@ -0,0 +1,310 @@ +--- +title: External-Type Serialization +sidebar_position: 4 +id: external_types +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. +--- + +External-type serialization generates a Fory struct serializer for a class +owned by another Dart library or package. Define a local serializer declaration +with the same fields and name the external class with `ForyStruct.target`. + +## Define an External Structural Serializer + +Suppose a dependency owns this class: + +```dart +final class User { + const User({ + required this.name, + required this.age, + }); + + final String name; + final int age; +} +``` + +Add the serializer declaration in your package: + +```dart +import 'package:fory/fory.dart'; +import 'package:third_party/models.dart' as third_party; + +part 'external_serializers.fory.dart'; + +@ForyStruct(target: third_party.User) +abstract final class UserSerializer { + @ForyField(id: 1) + late final String name; + + @ForyField(id: 2, type: Int32Type()) + late final int age; +} +``` + +The declaration must be `abstract final`, cannot have type parameters, and +must declare each schema field as `late final` without an initializer. Each +field name and Dart type, including nullability and generic arguments, must +exactly match an accessible getter on the target. + +Run the generator as usual: + +```bash +dart run build_runner build --delete-conflicting-outputs +``` + +## Register and Use the Target + +Register the external target through the generated module: + +```dart +final fory = Fory(); +ExternalSerializersForyModule.register( + fory, + third_party.User, + name: 'example.User', +); + +final bytes = fory.serialize( + const third_party.User(name: 'Ada', age: 36), +); +final user = fory.deserialize<third_party.User>(bytes); +``` + +Numeric IDs work the same way: + +```dart +ExternalSerializersForyModule.register( + fory, + third_party.User, + id: 100, +); +``` + +Register the target `third_party.User`, not `UserSerializer`. + +## Constructors and Mutable Targets + +Without a `constructor` option, generation uses the target's public unnamed +generative constructor. Constructor parameters map to schema fields by name +and must use exactly the same Dart types. + +For example, suppose the dependency exposes this immutable class: + +```dart +final class Money { + const Money.fromParts({ + required this.currency, + required this.units, + }); + + final String currency; + final int units; +} +``` + +Select its public named generative constructor in the serializer declaration: + +```dart +@ForyStruct( + target: third_party.Money, + constructor: 'fromParts', +) +abstract final class MoneySerializer { + late final String currency; + + @ForyField(type: Int64Type()) + late final int units; +} +``` + +After decoding the fields, the generated serializer calls +`third_party.Money.fromParts(currency: ..., units: ...)`. + +For a mutable target, a public generative constructor with no required +arguments plus matching setters allows Fory to construct the target first and +then assign its fields. This also supports cycles when reference tracking is +enabled. For example, suppose the dependency exposes: + +```dart +final class Node { + Node.empty(); + + late String label; + Node? next; +} +``` + +Select `Node.empty` in the serializer declaration: + +```dart +@ForyStruct( + target: third_party.Node, + constructor: 'empty', +) +abstract final class NodeSerializer { + late final String label; + + @ForyField(ref: true) + late final third_party.Node? next; +} +``` + +The generated serializer can call `third_party.Node.empty()`, publish the new +node for reference tracking, and then assign `label` and `next`. + +A constructor-based target cannot decode a statically known reference-tracked +path back to itself because the target does not exist until its constructor +arguments have been read. This includes the target nested as a `List` or `Set` +element or as a `Map` key or value. Generation rejects these schemas. Use a +mutable two-phase target or a manual serializer when cycles are required. +Indirect cycles that cannot be determined from the declaration are also +unsupported for constructor-based targets. + +Factory constructors, private constructors, abstract targets, external enums, +external unions, records, extension types, and built-in collection types are +not external struct targets. + +## Fields and Collections + +After registration, the target works anywhere an ordinary registered struct +works. A containing generated class does not select the serializer declaration: + +```dart +@ForyStruct() +final class Group { + Group(); + + third_party.User? owner; + + @ListField(element: DeclaredType()) + List<third_party.User> users = <third_party.User>[]; + + @MapField(value: DeclaredType()) + Map<String, third_party.User> usersByName = + <String, third_party.User>{}; +} +``` + +Nested lists, sets, and maps resolve the registered target recursively. +Dynamic fields and heterogeneous collections also resolve each concrete target +by its registered type: + +```dart +@ForyField(dynamic: true) +Object? value; +``` + +Register every concrete external type that can appear dynamically. + +Non-empty root lists, sets, and maps decode their elements, keys, and values as +the registered external targets. Dart root collections retain their existing +runtime shapes, so read a root collection as `Object?` and cast its outer +carrier: + +```dart +final decoded = + fory.deserialize<Object?>( + fory.serialize(<third_party.User>[user]), + ) + as List<Object?>; +final first = decoded.first as third_party.User; +``` + +An empty root collection contains no element type identity. + +## Closed Generic Targets + +Suppose the dependency exposes this generic class: + +```dart +final class Box<T> { + const Box(this.value); + + final T value; +} +``` + +`Box<T>` is open because `T` is unresolved. Supplying a concrete type argument, +such as `Box<String>`, produces a closed generic instantiation that code +generation can analyze: + +```dart +@ForyStruct(target: third_party.Box<String>) +abstract final class StringBoxSerializer { + late final String value; +} +``` + +The generated serializer reconstructs values with +`third_party.Box<String>(...)` and applies only to `Box<String>`. Register and +use that exact target type directly: + +```dart +final fory = Fory(); +ExternalSerializersForyModule.register( + fory, + third_party.Box<String>, + id: 102, +); + +final input = const third_party.Box<String>('hello'); +final bytes = fory.serialize(input); +final output = fory.deserialize<third_party.Box<String>>(bytes); + +print(output.value); // hello +``` + +Register `third_party.Box<String>`, not `StringBoxSerializer`. A different +instantiation such as `Box<int>` needs its own serializer declaration and +registration; one declaration does not cover every `Box<T>`. + +## Schema Evolution + +`evolving` and field IDs work exactly as they do for an ordinary generated +struct: + +```dart +@ForyStruct( + target: third_party.User, + evolving: true, +) +abstract final class UserSerializer { + @ForyField(id: 1) + late final String name; +} +``` + +Keep field IDs and the registered type identity stable across peers. A field +name must still match the corresponding property on the local target class. + +## When to Use a Manual Serializer + +Use a [manual serializer](custom-serializers.md) when the target needs a custom +wire body, field-name translation, value conversion, factory-only +construction, private state, or any reconstruction rule that cannot be +expressed through matching public getters, constructor parameters, and +setters. + +## Related Topics + +- [Code Generation](code-generation.md) +- [Type Registration](type-registration.md) +- [Schema Metadata](schema-metadata.md) +- [Schema Evolution](schema-evolution.md) +- [Manual Serializers](custom-serializers.md) diff --git a/docs/guide/dart/grpc-support.md b/docs/guide/dart/grpc-support.md index ee6bd8634c..43f2a3a17e 100644 --- a/docs/guide/dart/grpc-support.md +++ b/docs/guide/dart/grpc-support.md @@ -1,6 +1,6 @@ --- title: gRPC Support -sidebar_position: 12 +sidebar_position: 13 id: grpc_support license: | Licensed to the Apache Software Foundation (ASF) under one or more diff --git a/docs/guide/dart/index.md b/docs/guide/dart/index.md index bf62639e01..8c201f6ab3 100644 --- a/docs/guide/dart/index.md +++ b/docs/guide/dart/index.md @@ -37,7 +37,7 @@ languages. ### Requirements -- Dart SDK 3.6 or later +- Dart SDK 3.7 or later - `build_runner` (generates the serializer code) ### Install @@ -117,6 +117,7 @@ dart run build_runner build --delete-conflicting-outputs - `fory.serialize(value)` — returns `Uint8List` bytes - `fory.deserialize<T>(bytes)` — returns a `T` - `@ForyStruct()` — marks a class for code generation +- `@ForyStruct(target: Type)` — generates an external structural serializer - `@ForyField(...)` — per-field options and canonical `type:` overrides - `@ListField(...)`, `@SetField(...)`, `@MapField(...)` — container sugar for nested `type:` trees - Exact-value wrappers: `Int64`, `Uint64`, `Float32` @@ -126,20 +127,21 @@ dart run build_runner build --delete-conflicting-outputs ## Documentation -| Topic | Description | -| ----------------------------------------------- | --------------------------------------------------------------- | -| [Configuration](configuration.md) | Fory options, compatible mode, and safety limits | -| [Basic Serialization](basic-serialization.md) | `serialize`, `deserialize`, generated registration, root graphs | -| [Code Generation](code-generation.md) | `@ForyStruct`, build runner, and generated modules | -| [Xlang Serialization](xlang-serialization.md) | Interoperability rules and field alignment | -| [Schema Metadata](schema-metadata.md) | `@ForyField`, field IDs, nullability, references, polymorphism | -| [Type Registration](type-registration.md) | ID-based vs name-based registration and registration rules | -| [Custom Serializers](custom-serializers.md) | Manual `Serializer<T>` implementations and unions | -| [Supported Types](supported-types.md) | Built-in xlang values, wrappers, collections, and structs | -| [Schema Evolution](schema-evolution.md) | Compatible structs and evolving schemas | -| [Web Platform Support](web-platform-support.md) | Dart VM/AOT, Flutter, and web support, limits, and validation | -| [gRPC Support](grpc-support.md) | Generated Fory-backed gRPC service companions | -| [Troubleshooting](troubleshooting.md) | Common errors, diagnostics, and validation steps | +| Topic | Description | +| ------------------------------------------------ | --------------------------------------------------------------- | +| [Configuration](configuration.md) | Fory options, compatible mode, and safety limits | +| [Basic Serialization](basic-serialization.md) | `serialize`, `deserialize`, generated registration, root graphs | +| [Code Generation](code-generation.md) | `@ForyStruct`, build runner, and generated modules | +| [External-Type Serialization](external-types.md) | Generated serializers for classes owned by another package | +| [Xlang Serialization](xlang-serialization.md) | Interoperability rules and field alignment | +| [Schema Metadata](schema-metadata.md) | `@ForyField`, field IDs, nullability, references, polymorphism | +| [Type Registration](type-registration.md) | ID-based vs name-based registration and registration rules | +| [Manual Serializers](custom-serializers.md) | Manual `Serializer<T>` implementations and unions | +| [Supported Types](supported-types.md) | Built-in xlang values, wrappers, collections, and structs | +| [Schema Evolution](schema-evolution.md) | Compatible structs and evolving schemas | +| [Web Platform Support](web-platform-support.md) | Dart VM/AOT, Flutter, and web support, limits, and validation | +| [gRPC Support](grpc-support.md) | Generated Fory-backed gRPC service companions | +| [Troubleshooting](troubleshooting.md) | Common errors, diagnostics, and validation steps | ## Related Resources diff --git a/docs/guide/dart/schema-evolution.md b/docs/guide/dart/schema-evolution.md index 46410de5a2..6239dc45c3 100644 --- a/docs/guide/dart/schema-evolution.md +++ b/docs/guide/dart/schema-evolution.md @@ -1,6 +1,6 @@ --- title: Schema Evolution -sidebar_position: 8 +sidebar_position: 9 id: schema_evolution license: | Licensed to the Apache Software Foundation (ASF) under one or more @@ -62,6 +62,10 @@ class UserProfile { If you add field IDs after payloads are already in production, existing stored messages won't have them and evolution won't work correctly. +For an [external structural serializer](external-types.md), the local +serializer declaration supplies the evolving schema and each declaration field +must match the corresponding target property. + ## What You Can Safely Change **Safe changes** (compatible on both sides): @@ -101,5 +105,6 @@ final fory = Fory(compatible: false); ## Related Topics - [Configuration](configuration.md) +- [External-Type Serialization](external-types.md) - [Schema Metadata](schema-metadata.md) - [Xlang Serialization](xlang-serialization.md) diff --git a/docs/guide/dart/schema-metadata.md b/docs/guide/dart/schema-metadata.md index b24597ddbb..63d4da5952 100644 --- a/docs/guide/dart/schema-metadata.md +++ b/docs/guide/dart/schema-metadata.md @@ -1,6 +1,6 @@ --- title: Schema Metadata -sidebar_position: 5 +sidebar_position: 6 id: schema_metadata license: | Licensed to the Apache Software Foundation (ASF) under one or more @@ -21,6 +21,9 @@ license: | Add `@ForyField(...)` to a field inside a `@ForyStruct()` class to change how that field is serialized. +The same annotations apply to fields in an +[external structural serializer declaration](external-types.md). + ## Quick Reference ```dart @@ -141,5 +144,6 @@ When the same model is defined in multiple languages: ## Related Topics - [Code Generation](code-generation.md) +- [External-Type Serialization](external-types.md) - [Schema Evolution](schema-evolution.md) - [Xlang Serialization](xlang-serialization.md) diff --git a/docs/guide/dart/supported-types.md b/docs/guide/dart/supported-types.md index 220ed988cd..55f3858b86 100644 --- a/docs/guide/dart/supported-types.md +++ b/docs/guide/dart/supported-types.md @@ -1,6 +1,6 @@ --- title: Supported Types -sidebar_position: 7 +sidebar_position: 8 id: supported_types license: | Licensed to the Apache Software Foundation (ASF) under one or more @@ -132,6 +132,10 @@ class User { See [Code Generation](code-generation.md). +Classes owned by another library can use an +[external structural serializer](external-types.md) when their public fields +and construction match a local Fory schema declaration. + ## Collections Fory supports `List<T>`, `Set<T>`, and `Map<K, V>`. Element and key types must diff --git a/docs/guide/dart/troubleshooting.md b/docs/guide/dart/troubleshooting.md index 5f066920a2..fba1ef59bf 100644 --- a/docs/guide/dart/troubleshooting.md +++ b/docs/guide/dart/troubleshooting.md @@ -1,6 +1,6 @@ --- title: Troubleshooting -sidebar_position: 11 +sidebar_position: 12 id: troubleshooting license: | Licensed to the Apache Software Foundation (ASF) under one or more @@ -48,6 +48,22 @@ dart run build_runner build --delete-conflicting-outputs If you moved files or renamed types, rebuild before re-running analysis or tests. +## External target generation fails + +An external structural serializer requires: + +- an `abstract final` serializer declaration with `late final` schema fields; +- a concrete imported target class; +- an accessible target getter with the same name and exact Dart type for every + field; +- a public generative constructor whose parameters map to fields, or a + zero-required-argument constructor plus matching setters. + +Select a public named constructor with +`@ForyStruct(target: Type, constructor: 'name')`. Use a +[manual serializer](custom-serializers.md) when the target requires a factory, +private state, field conversion, or name translation. + ## `Deserialized value has type ..., expected ...` The payload describes a different type than `T` in `deserialize<T>`. Common causes: @@ -64,7 +80,7 @@ To preserve identity: - For fields inside a `@ForyStruct`, add `@ForyField(ref: true)` to those fields. - For a top-level collection, pass `trackRef: true` to `fory.serialize(...)`. -- In a custom serializer, use `context.writeRef` / `context.readRef` and call `context.reference(obj)` before reading nested fields. +- In a manual serializer, use `context.writeRef` / `context.readRef` and call `context.reference(obj)` before reading nested fields. ## Cross-language field mismatch (missing data or wrong values) @@ -158,6 +174,6 @@ separate protobuf service endpoint for generic protobuf clients. - [Xlang Serialization](xlang-serialization.md) - [Code Generation](code-generation.md) -- [Custom Serializers](custom-serializers.md) +- [Manual Serializers](custom-serializers.md) - [Web Platform Support](web-platform-support.md) - [gRPC Support](grpc-support.md) diff --git a/docs/guide/dart/type-registration.md b/docs/guide/dart/type-registration.md index 61e3c20ce8..7948e7afae 100644 --- a/docs/guide/dart/type-registration.md +++ b/docs/guide/dart/type-registration.md @@ -1,6 +1,6 @@ --- title: Type Registration -sidebar_position: 6 +sidebar_position: 7 id: type_registration license: | Licensed to the Apache Software Foundation (ASF) under one or more @@ -65,9 +65,23 @@ Call the generated `register` function from the `.fory.dart` file. It installs a UserModelsForyModule.register(fory, User, id: 100); ``` -## Registering a Custom Serializer +External structural serializers use the same generated registration API. Pass +the external target type: -For types that you cannot annotate with `@ForyStruct()`, pass a serializer instance directly: +```dart +ExternalSerializersForyModule.register( + fory, + third_party.User, + id: 100, +); +``` + +See [External-Type Serialization](external-types.md) for the declaration. + +## Registering a Manual Serializer + +Pass a serializer instance directly when a type needs custom wire or +construction logic: ```dart fory.registerSerializer( @@ -77,7 +91,7 @@ fory.registerSerializer( ); ``` -See [Custom Serializers](custom-serializers.md) for how to implement a serializer. +See [Manual Serializers](custom-serializers.md) for how to implement a serializer. ## Rules to Follow @@ -93,5 +107,6 @@ The same numeric ID or name must be used in every peer that reads or writes the ## Related Topics - [Code Generation](code-generation.md) +- [External-Type Serialization](external-types.md) - [Xlang Serialization](xlang-serialization.md) -- [Custom Serializers](custom-serializers.md) +- [Manual Serializers](custom-serializers.md) diff --git a/docs/guide/dart/web-platform-support.md b/docs/guide/dart/web-platform-support.md index 2000450992..f329be4d58 100644 --- a/docs/guide/dart/web-platform-support.md +++ b/docs/guide/dart/web-platform-support.md @@ -1,6 +1,6 @@ --- title: Web Platform Support -sidebar_position: 10 +sidebar_position: 11 id: web_platform_support license: | Licensed to the Apache Software Foundation (ASF) under one or more @@ -36,6 +36,7 @@ Fory Dart supports: - Flutter web applications. - Generated `@ForyStruct` serializers and manually registered serializers on all supported targets. +- External structural serializers generated with `@ForyStruct(target: ...)`. ## Code Generation Is Required @@ -135,9 +136,9 @@ class StorageExtent { } ``` -## Custom Serializers +## Manual Serializers -Custom serializers can use the same `Buffer`, `WriteContext`, and `ReadContext` +Manual serializers can use the same `Buffer`, `WriteContext`, and `ReadContext` APIs on VM/AOT, Flutter, and web. For 64-bit values: - Use `buffer.writeInt64(Int64(...))` and `buffer.readInt64()` for full-range diff --git a/docs/guide/dart/xlang-serialization.md b/docs/guide/dart/xlang-serialization.md index 8b1a5874d3..639878b5d1 100644 --- a/docs/guide/dart/xlang-serialization.md +++ b/docs/guide/dart/xlang-serialization.md @@ -1,6 +1,6 @@ --- title: Xlang Serialization -sidebar_position: 4 +sidebar_position: 5 id: xlang_serialization license: | Licensed to the Apache Software Foundation (ASF) under one or more @@ -59,6 +59,32 @@ ModelsForyModule.register( Do not mix the two strategies for the same type across implementations. +## External Types + +For a struct class owned by another Dart package, define an +[external structural serializer](external-types.md) and register the target +with the same ID or name used by every peer: + +```dart +@ForyStruct(target: third_party.User) +abstract final class UserSerializer { + @ForyField(id: 1) + late final String name; + + @ForyField(id: 2, type: Int32Type()) + late final int age; +} + +ExternalSerializersForyModule.register( + fory, + third_party.User, + id: 100, +); +``` + +The declaration's field IDs, names, nullability, and wire-width annotations +define the Dart-side xlang schema. + ## Dart to Java Example ### Dart @@ -215,5 +241,6 @@ dart test ## Related Topics - [Type Registration](type-registration.md) +- [External-Type Serialization](external-types.md) - [Schema Evolution](schema-evolution.md) - [Xlang guide](../xlang/index.md) --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
