应使用 composer require php-avro/php-avro:^3.0 替代已弃用的 dasprid/php-avro；AvroSchema 解析需严格 JSON 格式；序列化须正确配对 AvroIODatumWriter 与 AvroIOBinaryEncoder；反序列化必须显式传入 writer 和 reader schema。
直接用 composer require 装不上，因为官方库已弃用
PHP-Avro 的原始作者维护的 php-avro（dasprid/php-avro）早在 2018 年就标记为 abandoned，Packagist 上明确提示应迁移到 php-avro/php-avro —— 这是社区 fork 后持续维护的版本。直接运行 composer require dasprid/php-avro 会失败或装入过时代码，且不兼容 PHP 8+。
正确做法是：
- 运行
composer require php-avro/php-avro:^3.0（当前稳定版支持 PHP 7.4–8.3） - 确认
composer.json中没有残留旧包引用，尤其是"dasprid/php-avro": "*"类条目 - 如果项目用了
autoload-dev或自定义 PSR-4 映射，检查是否与PhpAvro\命名空间冲突
AvroSchema 解析失败常见于 JSON 格式不严格
Apache Avro 规范要求 schema 是合法 JSON，但实际中常混入注释、尾随逗号、单引号或未转义字段名（如 'my-field'）。PHP-Avro 使用原生 json_decode()，遇到这些会静默返回 null，后续调用 AvroSchema::parse() 抛出 TypeError: Cannot call getProperties() on null。
调试建议：
立即学习“PHP免费学习笔记（深入）”；
- 先用
json_last_error()检查原始字符串：json_decode($schemaJson, true) === null && json_last_error() !== JSON_ERROR_NONE - 用
jq -n 'input' < schema.avsc验证格式（Linux/macOS），或粘贴到 https://jsonlint.com/ 在线校验 - 避免手动拼接 schema 字符串；优先从文件读取：
$schema = file_get_contents('schema.avsc');
序列化时注意 AvroIOBinaryEncoder 和 AvroIODatumWriter 的配合顺序
PHP-Avro 不像 Java 那样自动绑定 schema 与 writer；必须显式将 AvroSchema 实例传给 AvroIODatumWriter，再将其注入 encoder。顺序错乱或复用 writer 实例会导致数据损坏或 UnexpectedValueException。
典型安全写法：
$schema = AvroSchema::parse(file_get_contents('user.avsc'));
$writer = new AvroIODatumWriter($schema);
$encoder = new AvroIOBinaryEncoder();
// 注意：必须在 encode 前 setWriter
$encoder->setWriter($writer);
$data = ['name' => 'Alice', 'age' => 30];
$binary = $encoder->encode($data);
关键点：
- 每个新 schema 对应独立的
AvroIODatumWriter实例，不可跨 schema 复用 -
AvroIOBinaryEncoder是无状态的，但setWriter()必须在首次encode()前调用 - 若需批量编码，重复调用
encode()即可，无需重建 encoder 或 writer
反序列化时 AvroIODatumReader 必须传入 writer schema 和 reader schema
Avro 支持 schema 演化（如字段默认值、重命名），所以解码时需同时提供写入时的 schema（writer）和当前期望结构（reader）。只传一个会触发 AvroSchemaResolutionException 或静默跳过字段。
最简可用模式（writer == reader）：
$schema = AvroSchema::parse(file_get_contents('user.avsc'));
$reader = new AvroIODatumReader($schema, $schema); // 两个参数都传同一实例
$decoder = new AvroIOBinaryDecoder($binary);
$data = $reader->read($decoder);
进阶场景（如升级 schema 后读旧数据）：
- 第一个参数是旧 schema（writer），第二个是新 schema（reader）
- 新 schema 中新增字段必须带
"default"，否则解析失败 - 字段类型变更（如
int→long）受 Avro 类型兼容规则约束，PHP-Avro 不做额外转换，失败即抛异常
真正容易被忽略的是：即使你没做 schema 演化，也必须显式传两次 schema —— 缺少第二个参数会导致 read() 返回空数组或报 Cannot resolve schema。
