Go Hamba Avro 的 logicalType 与底层物理类型有什么区别

Hamba Avro 中，底层物理类型决定值按哪种 Avro 类型编码，logicalType 则赋予它日期、时间戳或十进制等含义，并影响 Go 端的类型映射。例如 timestamp-millis 的底层仍是 long，但值代表 Unix 纪元以来的毫秒，Hamba 通常以 time.Time 表示；普通 long 则可映射为 int64。相同物理编码不等于相同业务含义。

官方地址：https://github.com/hamba/avro

本文针对 github.com/hamba/avro/v2。项目当前仓库已声明不再维护；已有系统排障应先记录实际依赖版本，不能把规范里出现的新逻辑类型直接视为该版本库已经支持。此文比较现有映射，不把它作为新项目选型推荐。

先按症状区分编码与语义

消费端读到一个正常整数，但显示的时间落在错误年代；或者把字段从 int64 改成 time.Time 后出现类型错误，这两种情况都值得先看完整字段模式。只看 type 为 long，不足以判断值是毫秒、微秒，还是没有时间语义的计数器。

先保存写入端的原始模式、消费端使用的模式、字段完整路径、Go 字段类型和依赖版本。还要确认数据是否采用原始 datum、对象容器或其他封装：原始二进制 datum 本身不会把完整模式及 logicalType 随每个值写入，读取方需要正确的外部模式。

Avro 规范规定逻辑类型沿用底层类型的编码，语言实现可以提供适合的本地类型。数据里没有额外的“这是毫秒”标记替应用纠正错误的模式，详见Avro 逻辑类型规范。

对照物理类型和 Go 映射

表中列出项目文档支持的常用映射，并非所有可转换类型的穷举。普通整数优先用明确宽度的 int64，避免平台相关 int 宽度造成新的疑问。decimal 不是简单给任意字节加个标签：它的缩放、精度和未缩放整数必须一致。其 Go 类型也不同于普通 bytes 的 []byte。

项目映射说明见Hamba 类型转换文档。同一 Go 类型也不保证语义一样：date 和 timestamp-millis 都可能使用 time.Time，但前者是日期，后者是全球时间线上的瞬间。

用同一时间值比较两种模式

下面分别把一个时间点按 timestamp-millis 编码、把它的 UnixMilli 值按普通 long 编码。比较的是相同的底层整数；如果将另一条路径换成 UnixMicro，便失去了这个比较前提。

package main

import (
    "bytes"
    "fmt"
    "time"

    "github.com/hamba/avro/v2"
)

func compare() error {
    // logicalType 规定 long 的单位是毫秒，Go 端使用 time.Time。
    logical, err := avro.Parse(`{"type":"long","logicalType":"timestamp-millis"}`)
    if err != nil {
        return fmt.Errorf("解析逻辑模式: %w", err)
    }
    physical, err := avro.Parse(`"long"`)
    if err != nil {
        return fmt.Errorf("解析物理模式: %w", err)
    }
    t := time.Date(2024, 3, 12, 8, 30, 0, 123000000, time.UTC)
    a, err := avro.Marshal(logical, t)
    if err != nil {
        return fmt.Errorf("编码时间: %w", err)
    }
    // 以同一个毫秒整数编码，比较物理表示而非两种不同单位。
    b, err := avro.Marshal(physical, t.UnixMilli())
    if err != nil {
        return fmt.Errorf("编码整数: %w", err)
    }
    var decoded time.Time
    if err := avro.Unmarshal(logical, a, &decoded); err != nil {
        return fmt.Errorf("解码时间: %w", err)
    }
    // 示例用于读者自行对照，不把打印值当作本文实测结果。
    fmt.Println(bytes.Equal(a, b), decoded.UTC().Format(time.RFC3339Nano))
    return nil
}

func main() {
    if err := compare(); err != nil {
        panic(err) // 演示入口保留错误，不继续使用失败后的数据。
    }
}

示例在模式规则成立时应体现两条路径的物理字节一致，以及时间按毫秒精度还原；本文未执行此程序，不给出虚构终端输出。特意选用毫秒对齐的时间值，避免把被舍去的亚毫秒信息误判为编解码故障。

这只是单个原始 datum 的对照。外部容器头、模式文本和注册信息可能不同，不能由这里的比较推出两个完整文件必然逐字节一致，也不能据此断言任意模式演进均兼容。

处理单位误配与回退

如果历史数据实际写入的是纪元秒，单独把模式标成 timestamp-millis 不会自动乘以一千。处理时应确定原始约定，保留旧数据与旧模式，定义一次明确的单位转换，再安排消费者迁移。不要用“解码没有错误”代替时间含义正确。

准备回退时，需要同时保留旧消费者版本、旧字段约定与原始数据。若已把微秒值不可逆地截成毫秒，回退模式也不能恢复丢失精度；若只是消费端误用了模式，恢复正确模式与字段类型才是对应处理。对日期、时间戳和当地时间戳，也应分别确认业务语义，不以格式相似代替语义相同。

规范要求读取未知逻辑类型时按底层类型处理，对无效逻辑类型也给出了忽略逻辑标注的规则。这是互操作规则，不代表业务可以放任错误配置；实际项目仍须确认所用 Hamba 版本的解析行为及错误返回。未知标签不会让库自动获得自定义时间或金额转换能力。

整理排障记录与常见问题

问题记录至少包含字段路径、写入模式中的 type 与 logicalType、单位、Go 字段类型、示例值来源和采用的修复方案。时间字段要写清纪元与单位；十进制字段要写清精度与缩放。重新解释历史字节之前，先保留原始数据，避免修复过程覆盖了判断依据。

只改 logicalType 会改变二进制编码格式吗？底层编码规则保持不变，但逻辑值到整数或字节的转换及 Go 映射会改变，最终字节仍取决于实际转换后的物理值。

timestamp-millis 会保留原来的时区名称吗？不会。它表示瞬间，显示成何种本地时间由应用决定；需要保存地区或时区标识时，应在业务模式中单独表达。

decimal 可以当 float64 使用吗？不要直接套用普通浮点映射。Hamba 文档给出的常用表示是 *big.Rat，且需要按模式的 precision、scale 处理可表达范围。

Avro 规范定义的类型都能直接在这个库里用吗？不能据规范目录作此推断。先以实际库版本及类型转换文档为准，尤其现有项目已声明不再维护。