语义转换

语义版本（SemVer）是关于版本号如何反映更改性质的约定。格式： MAJOR。MINOR.PATCH[-PRERELEASE][+BUILD].

• MAJOR-不兼容的更改（断开）。
• MINOR-反向可移动的fici/扩展。
• PATCH-可逆的错误/安全修复。

目标：API、事件、数据模式、SDK和configs的可预测演变,没有突然的消费者故障。

1）编号公约

X.Y.Z[-alpha.1    -rc.1][+build.sha]

预发布（"-alpha"，"-beta"，"-rc"）是不稳定的组件；不保证兼容性。
Build metadata（"+sha"）-不影响比较顺序,有利于跟踪。
最多1。0.0任何更改都可以视为突破（但最好从一开始就遵守规则）。

2）如何计算突破/小调/补丁

PATCH (Z):

错误和安全假货没有合同变更。
不影响合同的医生。
优化而不更改响应/事件/模式。

MINOR (Y):

添加新的可选字段/方法/末端。
如果消费者容忍不熟悉的含义，则扩展含义。
新的DB索引，带有默认值的nullable列，新事件以及旧事件。

MAJOR (X):

删除/重命名字段、更改类型、强制性。
更改语义/状态/错误代码。
更改序列化格式、密钥模式、传输协议。
拓扑的压缩/合并，事件意义的转移，分期方案的更改。
需要"双相"切换而无需向后兼容的DB迁移。

3）通过人工制品进行转化

3.1 REST

选项："URI/v1/……"，标题（"接受：application/vnd"。acme.game+json;version=1'），参数。
建议：URI中用于公共API的版本；对于内部-通过标题c negotation。
MINOR：添加可选字段、新过滤器/资源；不要改变现有的答桉。
PATCH：虚构,说明完善,稳定排序。

3.2 gRPC

更改签名/类型→ MAJOR（新包/服务： 'acme。wallet.v2`).

新字段-带有选项标签；服务器必须忽略未知数。
我们不会删除字段："depricate+保留编号",仅在以下MAJOR中删除。

3.3 GraphQL

MINOR：新字段/类型/查询；删除-通过'@deprecated'+迁移窗口,完全删除-MAJOR。
更改nullable→non-nullable-MAJOR。

3.4事件和拓扑（Kafka/SQS）

Schema Registry中的方案：additive的演变（添加带有默认字段）。

新的不兼容版本→新的主题/主题版本（'bet。settled.v2`).

在MAJOR中，分期密钥不变。

3.5 DB计划

1.添加列（nullable/c默认）→

2.填满后退→

3.翻译阅读→

4.删除旧的（仅限于MAJOR）。

类型/RK/唯一性更改为 MAJOR，在ficheflag和双重记录下。

3.6 SDK/CLI

公共方法/签名是相同的规则。
对于自动生成（OpenAPI/Proto），是批处理名称和工件的版本。

4）剥夺政策和生命周期

在每个断裂更改之前都先进行剥离（通常外部为90-180天，内部为30-60天）。
通讯：changelog，电子邮件/webhooks合作伙伴，开发者门户网站上的横幅。
双运行模式：同时保持"v1"和"v2"，监视"v1"的流量份额。

Sunset headers (REST): `Sunset: 2026-03-31`, `Link: ;rel="deprecation"`.

5) Version negotiation

客户端发送所需的版本+最大支持版本（例如"接受版本：1.2"）。
如果能够升级,服务器将响应"Content-Version： 2"。
在双向协议（WebSocket，gRPC）中，是"支持_版本"的Hello框架交换。

6）与提供程序适配器（ACL）的集成)

外部提供商正在改变模式-在适配器内,我们保留v1/v2映射器,并在内部事件中发布MINOR,同时保留我们的域合同。
如果外部更改进入内部-这是我们域事件的MAJOR和新的主题。

7）Changelog和Commites标签

• `feat:...` → MINOR
• "fix：……"/"chore"，"docs"，"perf"（无合同）→ PATCH
• 'feat!：'/'fix!：' /'refactor!：'或'BREAKING CHANGE： 'in → MAJOR

[2.3.0] - 2025-10-31
Added
- GET /v1/games?capabilities=jackpot (optional)
Changed
- GraphQL: field Game.volatility @deprecated, use Game.riskProfile

8）自动发行版

CI：电路验证器（OpenAPI/Protobuf/Avro/JSON-Shema），破解诽谤的细节。
SemVer-bot： Conventional Commits分析→计算bump （major/minor/patch）,设置标签,生成changelog。
CD：分离的deploy和release（ficheflagi/configi激活新版本）。
控制：在成功的canary和一致的SLO之前,我们不会在PRO上发布"最新"。

9）配置和策略的语义

Configs（YAML/JSON）也有方案版本："schema_version： 3"。
MINOR-新的可选字段/规则；MAJOR-结构/义务变更。
在验证器中支持v2/v3；不兼容报告的configs迁移者。

10）兼容性测试

消费者驱动合同测试（Pact）：每次集成。
Schema-evolution测试：在新电路上运行旧的付费,反之亦然。
重播：在阴影中播放"v1"到"v2"的原始流量。
基于物业的：对陌生字段/enum的抵抗力。

11）按版本分列的可观察性

对度量/逻辑进行标记："api_version"、"schema_version"、"event_version"。
迁移码：按版本划分的流量份额,"v1/v2"的错误/潜伏期。
Alerta：如果"v1"没有按计划下降；"v2"发行后的4xx/5xx增长。

12）无停机迁移模式

Expand → Migrate → Contract (БД).

双写作+在切换阅读之前比较差异。
Shadow compare用于排名/规则。
按特南特/地区分列的金丝雀；用于快速回滚的特征标志。
Read-compat/Write-compat窗口：新版本读取旧数据,但以新格式写入。

13）反模式

"每个字段中的版本"代替资源/事件的转换。
在MINOR下隐藏断开更改（例如默认更改）。
删除没有窗口和消耗度量的缺失。
"Forever v1"：没有计划消除旧版本的→ techdolg和漏洞。
业务版本和容器映像版本的混合。

14）考试政策支票清单

• 记录了版本格式和真相来源（Registry/Portal）。
• 批准了人工制品突破标准清单（REST/gRPC/GraphQL/events/DB）。
• 剥夺过程：时机，通讯，日落/横幅，双跑。
• 自动分频电路检查器和公约委员会。
• 使用版本和Alerta的达什板。
• 迁移花花公子（expand/migrate/contract，dual-write，shadow）。
• Configi和SDK有自己的版本和寄存器。
• 为客户提供"如何选择版本"的文档,为团队提供"如何升级"的文档。

15）测试示例（iGaming桉例）

"BetSettled v1" → "v2"事件：添加了"void_reason"（选项）和"tax"。amount` (optional) — MINOR.重新命名为"payout'→'win_amount"-MAJOR，新的主题。
REST'/wallets/transfer'：添加过滤器'?tenant_id='-MINOR。更改错误代码"409'→'422"-MAJOR。
GraphQL：标记为"播放器"。年龄为'@deprecated'，有利于'Player。ageGroup'-在MINOR中发布，在X期之后在MAJOR中删除。
DB：添加了"bonus_wager_left" nullable-MINOR列。做了不空，删除了"bonus_left"-MAJOR（通过expand/contract）。

二.结论

语义转换不是关于数字，而是关于信任和可预测性。清晰的规则、自动检查、受控的剥夺和透明的遥测使得API、事件和电路能够无痛苦地进行集成,并经常、安全和有意义地发布更改。