本文档由 g2rain-common 的 docs/development/compatibility.md 自动同步生成。

# 兼容性

g2rain-common 被多个服务以编译依赖使用，兼容性是首要约束。

需要评审的变化

• 删除、重命名或收窄 public/protected 类型和方法。
• 改变方法签名、泛型边界、返回值、异常或空值语义。
• 改变 JSON 属性名、忽略规则、默认值、数字表示或反序列化行为。
• 删除或重命名枚举常量、错误码、请求头和事件类型。
• 改变 Result、分页、排序、Principal、JWT/DPoP 或事件消息的数据结构。
• 提高 Java 字节码版本，或新增/升级会传递给消费方的依赖。

发布原则

兼容新增通常提升次版本；破坏性变化必须明确迁移说明并提升主版本。修复版本不得悄然改变序列化格式或行为契约。发布前至少完成当前库测试，并选择代表性消费项目做编译或集成验证。

仓库当前没有自动化二进制兼容检查工具，因此 API diff 和消费方验证仍是人工责任。