Why?

The previous Go serialization implementation had several limitations that affected both performance and developer experience:

1. Performance bottlenecks: Mixed read/write state in a single context, lack of fast paths for common types, and redundant indirections
2. API usability: Interface{}-based API caused unnecessary allocations and lacked compile-time type safety
3. Concurrency gaps: No built-in thread-safe support, forcing users to manage instances manually
4. Code maintainability: Mixed responsibilities and unclear separation of concerns made the codebase hard to navigate

This refactoring addresses these fundamental issues to make Fory Go more performant, safer, and easier to use.

What does this PR do?

This PR comprehensively refactors the Fory Go serialization implementation:

1. New Generic API Design (Closes #2992 )

• Introduces type-safe generic APIs: Serialize[T] and Deserialize[T]
• Pointer-based parameters eliminate unnecessary heap allocations and struct copies
• Separate SerializeAny/DeserializeAny for polymorphic use cases
• Cleaner distinction between typed and untyped serialization

2. Performance Optimizations (Closes #3016 )

• Separate ReadContext and WriteContext eliminate mixed state overhead
• Fast paths for primitives: bool, int8/16/32/64, float32/64, string
• Optimized serializers for common collections: []int, []string, []bool, etc.
• Direct memory access for struct field serialization
• Inlined hot path methods for compiler optimization

3. Thread-Safe Package (Closes #3017 )

• New fory/threadsafe package using sync.Pool for zero-contention concurrency
• Safe concurrent use without manual instance management
• Same API surface as main package (generic and non-generic)
• Global convenience functions for quick usage

4. Code Organization (Closes #3018 )

• Separate files: reader.go, writer.go for clear read/write separation
• Type-specific serializers: array.go, primitive.go, pointer.go, time.go, etc.
• Renamed files for clarity: resolver.go → meta_string_resolver.go, type.go → type_resolver.go
• Better documentation and code structure

Additional Improvements

• Updated codegen to align with new API
• Improved test coverage with new typed tests
• Updated documentation and examples

Related issues

Closes #2992 - API redesign with generics
Closes #3016 - Performance optimizations
Closes #3017 - Thread-safe package
Closes #3018 - Code refactoring
Closes #3010
Closes #3011

Closes #2611
Closes #2661
Closes #2639

#2982
#1017

Does this PR introduce any user-facing change?

Yes, this PR introduces breaking API changes:

Breaking Changes:

1. Main API changes:

   • Old: fory.Serialize(value) → New: fory.Serialize(foryInstance, &value) or fory.Marshal(&value)
   • Old: fory.Deserialize(data, &target) → New: fory.Deserialize(foryInstance, data, &target) or fory.Unmarshal(data, &target)
   • Constructor: fory.NewFory(refTracking) → fory.New(fory.WithTrackRef(enabled))

2. Type-safe generic API (recommended):

   // Serialization
   data, err := fory.Marshal(&myStruct)
   
   // Deserialization
   var result MyStruct
   err := fory.Unmarshal(data, &result)

3. Thread-safe usage:

   import fory "github.com/apache/fory/go/fory/threadsafe"
   
   // Global instance (recommended for concurrent use)
   data, err := fory.Marshal(&myStruct)
   var result MyStruct
   err := fory.Unmarshal(data, &result)
   
   // Or custom instance
   f := fory.New(fory.WithTrackRef(true))
   data, err := fory.Serialize(f, &myStruct)

Migration Guide:

Users need to update their code to:

• Use pointer parameters instead of values
• Switch to generic APIs for better performance
• Use the threadsafe package for concurrent applications
• Update to functional options pattern for configuration

Does this PR introduce any public API change?

Yes, extensive public API changes as detailed above. The new API is more performant and type-safe, but requires migration from the old interface{}-based API.

Does this PR introduce any binary protocol compatibility change?

No, the binary protocol remains fully compatible. This is purely an implementation and API refactoring. Data serialized with the old implementation can be deserialized with the new one and vice versa.