# Data 模块

## 模块概述

Data 模块是自定义数据结构和类型转换模块，提供了 JSON 序列化/反序列化工具、缓冲区管理和 Gson 扩展功能。该模块封装了常用的数据处理操作，提供了安全可靠的数据转换机制。

## 主要功能

### 1. JSON 处理工具
- **GsonExt**: 扩展的 Gson 工具类
- 提供安全的 JSON 序列化/反序列化方法
- 支持异常捕获和日志记录
- 集成自定义 TypeAdapter 工厂

### 2. 缓冲区管理
- **AutoExtendByteBuffer**: 自动扩容的字节缓冲区
- 支持动态内存分配
- 提供多种数据类型写入方法
- 自动处理容量不足问题

### 3. 自定义注解
- **@GsonNullable**: Gson 空值处理注解
- **@Must**: 必须字段标记注解
- 支持字段级别的序列化控制

### 4. 扩展 TypeAdapter
- **ExtReflectiveTypeAdapterFactory**: 扩展反射适配器工厂
- **ExtMapTypeAdapterFactory**: 扩展 Map 类型适配器工厂
- **ExtCollectionTypeAdapterFactory**: 扩展集合类型适配器工厂

## 核心类和接口

### GsonExt
```kotlin
// 全局 Gson 实例，集成扩展适配器工厂
val gson: Gson

// 安全的序列化方法（异常时返回 null）
fun toJsonErrorNull(obj: Any?): String?

// 安全的反序列化方法
inline fun <reified T> froJsonErrorNull(json: String?): T?
fun <T> froJsonErrorNull(json: String?, clazz: Class<T>): T?
fun <T> froJsonErrorNull(json: String?, typeOfT: Type): T?
```

### AutoExtendByteBuffer
```kotlin
class AutoExtendByteBuffer(initSize: Int) {
    // 写入不同类型的数据
    fun putInt(value: Int)
    fun putFloat(value: Float)
    fun putString(value: String?)
    
    // 获取数据
    fun array(): ByteArray
    fun position(): Int
    
    // 内部自动扩容
    private fun ensureSize(allocate: Int)
}
```

### 自定义注解
```java
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.FIELD})
public @interface GsonNullable {
    // 标记字段可以为空
}

@Retention(RetentionPolicy.RUNTIME)  
@Target({ElementType.FIELD})
public @interface Must {
    // 标记必须字段
}
```

## 使用方式

### 1. JSON 序列化/反序列化
```kotlin
// 安全序列化
val jsonString = toJsonErrorNull(dataObject)
if (jsonString != null) {
    // 序列化成功
    saveJson(jsonString)
} else {
    // 序列化失败，已记录日志
}

// 安全反序列化
val dataObject = froJsonErrorNull<MyData>(jsonString)
if (dataObject != null) {
    // 反序列化成功
    processData(dataObject)
} else {
    // 反序列化失败，已记录日志
}

// 使用 Class 类型反序列化
val result = froJsonErrorNull(jsonString, MyData::class.java)

// 使用 Type 反序列化泛型
val listType = object : TypeToken<List<MyData>>() {}.type
val dataList = froJsonErrorNull<List<MyData>>(jsonString, listType)
```

### 2. 使用 AutoExtendByteBuffer
```kotlin
// 创建缓冲区（初始大小 1024 字节）
val buffer = AutoExtendByteBuffer(1024)

// 写入不同类型数据
buffer.putInt(42)
buffer.putFloat(3.14f)
buffer.putString("Hello World")

// 获取最终数据
val byteArray = buffer.array()
val currentPosition = buffer.position()

// 自动扩容示例
val smallBuffer = AutoExtendByteBuffer(16) // 初始 16 字节
repeat(100) {
    smallBuffer.putInt(it) // 自动扩容到足够大小
}
```

### 3. 使用自定义注解
```kotlin
data class UserData(
    @Must val id: String,           // 必须字段
    @GsonNullable val name: String?, // 可空字段
    val email: String               // 普通字段
) : IJsonConfig

// 序列化时会根据注解进行特殊处理
val json = toJsonErrorNull(userData)
```

### 4. 直接使用全局 Gson 实例
```kotlin
// 获取配置好的 Gson 实例
val customGson = gson

// 使用标准 Gson API
val json = customGson.toJson(dataObject)
val obj = customGson.fromJson(json, MyData::class.java)
```

## 扩展功能

### 1. 自动扩容算法
```kotlin
// AutoExtendByteBuffer 的扩容策略
private fun ensureSize(allocate: Int) {
    val newPosition = allocate + position
    var capacity = buffer.capacity()
    
    // 容量不足时，按 2 的幂次递增
    while (newPosition > capacity) {
        capacity = capacity shl 1  // 容量翻倍
    }
    
    // 创建新缓冲区并拷贝数据
    val newBuffer = ByteBuffer.allocate(capacity)
    buffer.flip()
    newBuffer.put(buffer)
    buffer = newBuffer
}
```

### 2. 异常处理机制
所有 JSON 处理方法都集成了统一的异常处理：
- 异常时返回 null 而非抛出异常
- 自动记录错误日志到 AppBase.log
- 使用 TAG_GSON 标签便于日志过滤

## 依赖关系

### 编译时依赖
- `gson` - Google JSON 库
- `kotlin-stdlib` - Kotlin 标准库
- `androidx.core.ktx` - Android Core 扩展
- `frame:base` - 基础模块（日志功能）
- `frame:zero` - 零依赖模块

### 被依赖关系
- `frame:network` - 网络模块使用 JSON 处理
- `frame:storage` - 存储模块使用数据序列化
- 其他需要数据转换的模块

## 构建配置

```gradle
implementation "com.wenext.android:frame-data:6.0.0"
```

## 注意事项

1. **异常安全**: 所有 JSON 方法都有异常处理，不会抛出未捕获异常
2. **日志记录**: 异常信息会自动记录到系统日志，便于调试
3. **内存管理**: AutoExtendByteBuffer 使用倍增策略，注意大数据量时的内存消耗
4. **线程安全**: Gson 实例是线程安全的，可在多线程环境下使用
5. **最小容量**: AutoExtendByteBuffer 最小初始容量为 16 字节
6. **性能考虑**: 扩展适配器工厂可能影响序列化性能，适用于需要特殊处理的场景
7. **空值处理**: 注意区分 null 返回值是因为输入为空还是处理异常