Junco 兼容性承诺

[TOC]

一、版本策略

Junco Framework 从正式发布版本开始遵循 SemVer 语义化版本。

• PATCH 版本只修复缺陷，不主动改变公开 API、配置项、协议字段、指标名和默认运行行为。
• MINOR 版本允许新增能力、配置项、注解、指标和可选行为，但默认保持向后兼容。
• MAJOR 版本允许破坏性变更，发布说明中必须给出影响范围和迁移方式。

当前框架仍处于公测前阶段，允许为了生产可用性做必要整理；进入正式公测版本后，下面列出的稳定契约按 SemVer 管理。

二、稳定契约范围

以下内容属于稳定契约，修改时必须评估兼容性并补充或更新契约测试。

• 公开注解：@JuncoBootApplication、@JuncoManaged、@JuncoConfig、@JuncoBean、@ConditionalOnProperty、@ConditionalOnMissingBean、@JuncoScan、@EnableWeb、@EnableJuncoJdbc、@EnableOpenApi、@EnableWebValidator、@RpcService、@RpcReference 等。
• 配置项：http.*、metrics.*、jdbc.*、jooq.*、rpc.*、cache.*、redis.*、nats.*、gateway.*。
• 内置运维端点：/-/live、/-/ready、/-/metrics。
• Prometheus 指标名和低基数标签，详见 metrics.md。
• RPC HTTP JSON 协议：RpcRequest、RpcResponse、RpcError 的字段结构。
• Web 默认错误响应：默认 404、400、500 文本响应，以及显式全局异常处理器返回结构。

三、不承诺兼容范围

以下内容属于内部实现细节，除非另有文档明确声明，否则不作为兼容契约。

• io.github.jarvett.third.* 包下的第三方适配层和内部传输对象。
• 扫描、注册、生命周期中的内部辅助类。
• 测试包、测试应用和测试夹具。
• 未在文档中列出的实验性配置项、实验性模块和临时诊断输出。
• 日志文本的完整措辞。日志级别和关键上下文会尽量保持稳定，但不作为强协议。

四、配置兼容规则

配置项按“新增优先、删除谨慎”的规则演进。

• 新增配置必须有默认值，未配置时保持旧行为。
• 修改默认值必须视为兼容性风险，至少在发布说明中说明原因。
• 删除配置必须进入 MAJOR 版本；在删除前应至少保留一个 MINOR 版本的废弃期。
• 配置重命名应保留旧 key 到新 key 的兼容绑定，废弃期内旧 key 仍可用。

五、指标兼容规则

指标用于 Prometheus 和 Grafana 看板，指标名、单位和低基数标签属于稳定契约。

• 不直接重命名已公开指标。
• 不移除已公开的低基数标签。
• 不新增高基数标签，例如用户 ID、订单号、请求参数、异常堆栈。
• 新增指标必须写入 metrics.md，并补契约测试。
• 指标迁移时可以先并行暴露新旧指标，旧指标只在 MAJOR 版本删除。

六、RPC 协议兼容规则

RPC HTTP 协议的稳定字段如下。

RpcRequest：

{
  "arguments": [],
  "method": "getById",
  "parameterTypes": ["java.lang.Long"],
  "service": "user-service"
}

RpcResponse 成功响应：

{
  "data": {},
  "success": true
}

RpcResponse 失败响应：

{
  "error": {
    "code": "RPC_REMOTE_ERROR",
    "details": "detail",
    "message": "remote failed"
  },
  "success": false
}

协议演进规则：

• 可以新增可选字段。
• 不修改已有字段含义。
• 不改变 success、data、error、code、message、details 的语义。
• 二进制字段继续使用 Base64 字符串表达，避免和历史 JSON 表达不兼容。

七、发布门禁

正式发布前必须完成以下检查。

• 运行对应模块测试，至少覆盖变更模块。
• 涉及公开契约时，新增或更新契约测试。
• 涉及配置、指标、端点、协议时，同步更新文档。
• 涉及破坏性变更时，发布说明必须包含迁移说明。