AsyncAPI 与 Event Schema：事件生产者消费者怎样独立演进
新事件能通过 Schema 校验，为什么仍可能让旧消费者记错账？ 这类事故通常不是序列化库突然失效，而是双方只共享了字段形状，没有共享字段身份、业务含义、状态前提和演进规则。事件契约同时包含结构、业务含义、时序、交付与所有权。AsyncAPI 描述应用如何在 channel 上发送或接收 message，但兼容性必须结合所有活跃消费者和历史重放证明。
契约不是一份文档，而是跨时间的承诺
契约至少包含五层：传输语义、结构 Schema、业务语义、运行策略和演进策略。传输语义回答方法、状态、deadline 与交付；结构 Schema 回答字段、类型、必填和引用；业务语义回答单位、状态、权限与不变量；运行策略回答幂等、重试、分页和限额；演进策略回答新增、废弃、迁移、支持窗口与回滚。只检查其中一层，会把另外四层的破坏带入生产。
AsyncAPI 3 把 server、channel、operation、message 与 protocol binding 分层；生产者写出 eventId、eventType、schemaVersion、aggregateId、aggregateVersion、occurredAt 和 payload，Broker 负责投递，消费者按自身水位幂等应用。
一次契约调用怎样从制品走到业务状态
发布新 schema 前构建消费者能力矩阵，对每个消费者运行新生产者样本和历史语料。事件采用事实过去式与不可变身份；语义变更不能只升 schemaVersion，应设计新 event type 或过渡双发并设置终止条件。
重命名字段但保留类型会通过部分结构检查却改变语义；把可选改为必填会破坏历史消息重放；消费者未知枚举处理不当会崩溃；只测最新消费者会遗漏仍在运行的旧版本。
身份比名字更重要
兼容性不是单向的布尔值
兼容矩阵的行是活跃消费者及版本，列是候选契约和生产者行为。矩阵单元格保存结构验证、生成编译、样本回放、错误分支与性能限制结果。只测试最新 SDK 会让旧移动端、离线任务、合作方和延迟消息成为盲区。
结构验证必须建立引用闭包
OpenAPI、JSON Schema 和 AsyncAPI 都允许复用或外部引用。解析阶段需要从入口遍历整个引用图，解析相对 URI、锚点和 dialect，检测不可达引用、循环和冲突标识。循环本身不一定非法，但工具必须有访问集合和深度/节点预算，否则恶意或错误引用可以耗尽资源。
JSON Schema 的 format 在不同实现中可能只作为 annotation，也可能启用 assertion；default 通常是注解，不等于验证器自动填值；unevaluatedProperties、dynamicRef 和 vocabulary 需要相应 dialect 支持。生成代码前应对目标工具运行能力探测，不能把规范允许与工具实现等同。
错误契约必须告诉调用方下一步
可运行模型一：让破坏性变更显形
运行 ConsumerCompatibilityDemo.java：
javac --release 17 -Xlint:all -Werror ConsumerCompatibilityDemo.java
java ConsumerCompatibilityDemo预期输出：
consumers=4 acceptsV2=3 rejectsV2=1 blockingConsumers=[billing-v1] publishable=false第一个模型把兼容判断压缩为稳定数量关系：新增 required、字段号复用、阻塞消费者、浮点误差或状态机非法转换。它不替代真实解析器，却能让评审者看到“哪些输入导致哪条门禁失败”，并能稳定用于回归。
修改模型输入做反向实验：把 optional 变 required、从 reserved 集合取字段号、新增旧消费者不能识别的事件、让金额经过 double 或移除问题类型。若模型仍报告 publishable，说明门禁只检查了表面结构。
可运行模型二：验证运行时仍然收敛
javac --release 17 -Xlint:all -Werror EventReplayDemo.java
java EventReplayDemo预期输出：
events=6 duplicates=1 outOfOrder=1 applied=4 staleRejected=1 replayed=1 finalVersion=5 converged=true第二个模型覆盖引用缺失、deadline 传播、事件重放、presence、消费者契约或回滚制品。结构兼容只是第一道门，运行时还必须在超时、重复、乱序、缺省值和版本并存时保持可判定结果。
验收不应只断言进程退出码。需要核对输出中的失败数、阻塞消费者、最终版本、剩余预算、错误泄漏和 rollbackArtifact。任何非零破坏都应关联 owner、例外期限与迁移计划，不能以“先上线观察”替代证据。
Deadline、幂等和重试也是契约
幂等性要定义作用域、身份和保存期。HTTP 方法的通用幂等语义不自动解决业务重复扣款；应使用业务操作 ID 或 Idempotency-Key，把请求摘要、状态和结果绑定。事件消费者按 eventId 去重、按 aggregateVersion 拒绝旧状态。重试只针对明确可重试错误，并受总截止时间与次数限制。
契约应声明最大请求/响应、流式背压、分页大小和批次上限。生成 SDK 若默认无限读取响应或自动重试非幂等调用，同样属于契约缺陷。性能限制必须进入规范扩展、客户端策略或配套机器可读策略，不能只藏在运维文档。
时间、金额、ID、枚举与 Null 要逐个定义
枚举新增必须假设旧消费者会收到未知值。客户端模型保留 UNKNOWN/UNRECOGNIZED 和原始值，不应在未知值上崩溃或默认映射为某个真实业务状态。服务端在收缩枚举前先观察未知值流量，确认所有生产者完成迁移。
事件契约还要承担历史
同步 API 可以通过部署窗口逐步迁移，事件则可能在日志、重试队列、对象存储和审计归档中保留多年。消费者升级后仍要能重放旧事件；新事件投入生产后，滞后消费者仍可能是旧代码。因此事件兼容矩阵必须覆盖历史语料和最大保留期。
AsyncAPI 的 channel 是可寻址组件，operation 表达应用执行的发送或接收动作，message 表达载荷与 headers，binding 只承载协议特定信息。不要把 Kafka partition、AMQP exchange 等绑定细节混进通用 payload，也不要认为 AsyncAPI 文件存在就自动定义了顺序、至少一次或事务语义。
事件 payload 应表达已经发生的事实，不发数据库行镜像。aggregateVersion 建立同一聚合内顺序，eventId 建立投递身份，schemaVersion 只标识结构而不取代 eventType。语义无法兼容时发布新 eventType，双发期间核对消费者水位，并为旧类型设置可验证的终止条件。
发布门禁要横跨生产者和消费者
安全边界必须写进 Schema 和生成器
Schema 只能证明形状，不能代替授权。资源级权限必须基于当前身份和对象关系判断，不能因为请求符合契约就允许访问。响应 Schema 要按权限设计最小字段，不用客户端忽略字段代替服务端裁剪。错误 detail、validation path 和反射描述也可能泄露隐藏字段。
个人数据字段标注分类、用途、日志策略和删除传播。SDK 的 toString、调试拦截器与自动日志默认脱敏；事件契约记录数据保留与擦除关联键。契约制品公开范围也要分级，内部管理接口不应因为生成文档而自动暴露。
观测要能回答哪个版本在破坏谁
同步接口按 operationId、contractDigest、consumerName/version、status/problemType、latency、request/response size 和 retry count 聚合；RPC 增加 method、grpc.status、deadline remaining、cancellation；事件增加 eventType/schemaVersion、producer、consumer、partition、lag、decode failure 和 unknown field/enum。
不要把完整 payload 作为默认诊断手段。保存结构化摘要、字段 presence 位图、类型错误路径和脱敏样本引用。发生兼容故障时，先定位哪个生产者制品生成了什么 wire 数据，再定位哪个消费者制品如何解释，最后比较两者共享的契约基线。
发布看板至少显示活跃消费者版本分布、最老受支持版本、候选变更破坏数、SDK 生成/编译结果、provider/consumer 通过率、unknown enum、解析失败和弃用接口流量。没有消费者版本可见性，就无法安全删除旧字段或旧路径。
回滚必须能复现旧制品与旧语义
每个已发布版本保存源 Schema、bundle、digest、生成器镜像或锁定版本、生成产物、测试语料和兼容报告。回滚演练从这些制品重新生成客户端并运行，而不是依赖开发机缓存。事件回滚还要定义新旧 eventType 的补偿或转换，不能删除已经进入日志的事实。
版本号是沟通工具，不是兼容机制。路径版本、媒体类型版本、RPC 新方法或事件新类型都只建立新身份；迁移、双写、流量观测、消费者支持与终止条件仍需单独设计。能兼容扩展时避免无意义大版本，确实改变语义时也不要用小版本掩盖。
架构决策必须留下可复审证据
事件契约同时包含结构、业务含义、时序、交付与所有权。AsyncAPI 描述应用如何在 channel 上发送或接收 message，但兼容性必须结合所有活跃消费者和历史重放证明。 这一主题最终要守住：任何新事件都能被声明支持的消费者正确解释，重复、乱序和历史重放最终收敛。若只能证明最新生产者与最新客户端的 happy path，就还没有建立可演进契约。
契约源、解析 bundle、digest、生成器版本与测试报告可追溯。明确区分传输、结构、业务、运行和演进五层语义。所有机器身份删除后保留并禁止复用，名称不承担隐式判断。
兼容矩阵覆盖所有活跃消费者、历史样本与双向部署顺序。引用闭包、dialect、循环、外部资源和解析预算经过门禁。错误类型、状态、可重试性和 detail 脱敏具有稳定规则。
deadline、取消、幂等键、分页游标和容量上限进入契约。时间、金额、ID、枚举、Null 与未知值有跨语言语义。SDK 实际生成并编译，Provider 与 Consumer 测试均执行。
expand/migrate/contract、弃用终止条件和回滚制品经过演练。两个 Java 17 模型以严格编译运行，输出与正文逐项一致。
以下一手资料用于核对协议与规范语义，实际采用版本仍需匹配解析器、生成器和语言运行时能力：