android-frame/frame/data/CLAUDE.md

Data 模块

模块概述

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

主要功能

1. JSON 处理工具

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

2. 缓冲区管理

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

3. 自定义注解

• @GsonNullable: Gson 空值处理注解
• @Must: 必须字段标记注解
• 支持字段级别的序列化控制

4. 扩展 TypeAdapter

• ExtReflectiveTypeAdapterFactory: 扩展反射适配器工厂
• ExtMapTypeAdapterFactory: 扩展 Map 类型适配器工厂
• ExtCollectionTypeAdapterFactory: 扩展集合类型适配器工厂

核心类和接口

GsonExt

// 全局 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

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)
}

自定义注解

@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.FIELD})
public @interface GsonNullable {
    // 标记字段可以为空
}

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

使用方式

1. JSON 序列化/反序列化

// 安全序列化
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

// 创建缓冲区（初始大小 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. 使用自定义注解

data class UserData(
    @Must val id: String,           // 必须字段
    @GsonNullable val name: String?, // 可空字段
    val email: String               // 普通字段
) : IJsonConfig

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

4. 直接使用全局 Gson 实例

// 获取配置好的 Gson 实例
val customGson = gson

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

扩展功能

1. 自动扩容算法

// 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 - 存储模块使用数据序列化
• 其他需要数据转换的模块

构建配置

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

注意事项

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