技术和基础设施→转化API

API转化

1）为什么需要它

验证是一种管理的方式，可以在不发生故障的情况下更改服务和客户之间的合同。在具有大量集成的产品（付款，KYC/AML，游戏，计费，报告）中，"旧"和"新"客户同时生活。正确的版本策略：

降低了发布事件的风险，
允许有计划地引入改进和安全性，
为企业提供了可预测的合作伙伴迁移时间表。

2）更改分类

PATCH（不中断）：不更改合同的修复程序（添加可选字段、验证小册子）。
MINOR（扩展）：反向兼容扩展（新端点,带默认字段）。
MAJOR（断开）：更改结构、语义或删除字段/末尾。

建议使用SemVer'MAJOR。MINOR.PATCH'用于工件（SDK/模式），可以简化"外部"API编号（v1，v2）。

3） REST转化模型

1.在URI中：

`GET /v1/payments/{id}`

优点：透明、可缓存、易于路由。缺点：重复文档，更难巧妙地演变。

2.在标题中（content negotation）：

`Accept: application/vnd.company.payments.v2+json`

优点：灵活性，URL中没有"垃圾"，介质的方便演变。缺点：更难在浏览器中借记，需要纪律严明的客户端。

3.在自定义标题中：

`X-API-Version: 2` (или `Api-Version: 2025-09-01`)

优点：就在网关上。缺点：没有标准，小心缓存。

4.日期版本（基于日期）：

有利于金融科技/报告：可预测的变化"切口"（例如季度）。

5.资源/模型转换：

相同的端点可以返回不同的视图：'fields=……'或'profile=lite	full`.这是一个补充，不是忠诚的替代。

建议：外部集成-'URI vN'+Deprecation/Sunset标题；对于内部-如果网关和平台支持,则可以"接受"或版本标题。

4) GraphQL

偏好-没有全局版本。通过添加字段/类型和剥离（'@deprecated（reason："……"）'）进行演变。
破裂的变化仅在带有迁移盖德的"大"窗口（经过验证的计划名称）中。
注意"n+1"并确保您不会更改现有字段的测量。

5) gRPC / Protobuf

字段编号不变。远程字段标记为"保留"。
将字段添加为带有安全默认值的选项。
使用buf breaking/lint自动验证兼容性。

转化包/模块： 'package payments。v1;` → `payments.v2`.

6）事件API （EDA）

事件图是相同的合同。将其存储在Schema Registry（Avro/JSON-Schema/Protobuf）中。

拓扑和版本： 'payments。v1.authorized`, `payments.v2.authorized`.

断开更改是新事件类型或新拓扑。
进化保证：在LTS时期为领事提供反向匹配。

7）剥夺和EOL政策

实施透明规则：

Deprecation： changelog和BOM （OpenAPI/GraphQL SDL）中的标签,标题
"Deprecation： true"和可能的"Sunset： Tue, 31 Mar 2026 pm GMT"
通讯：电子邮件/合作伙伴门户,webhooks通知,发布通知。
截止日期：MINOR-3-6个月的支持，MAJOR-9-18个月（取决于临界值）。
时间窗口：锁定在"API验证策略"中。

8）路由和发布

网关API （Cong/Apigee/Nginx/Envoy）：前缀"/v1/"、标题或介质规则。

路由示例：


if ($http_accept ~ "vnd.company.payments.v2") { proxy_pass http://payments-v2; }

Canary/Blue-Green/Shadow：将新版本滚动到1-5%的流量，比较合同错误指标和日志。
Feature Flags：在不改变合同的情况下隐藏行为。
零时段迁移：MAJOR提供双写入/读（双写入/读取）数据模式。

9）合同测试和兼容性控制

buf breaking для protobuf.

OpenAPI Diff（或swagger-diff）-检查MINOR/PATCH是否不中断电路。
Spectral Linting是一种必备元数据的样式（版本，Deprecation）。
Consumer-Driven Contracts （Pact）-确保提供商不会破坏客户。
CI必须在不提高MAJOR的情况下下降。

10）文档和SDK

Version spacks： '/docs/api/v1/openapi。json`, `/docs/api/v2/…`.

使用SemVer和changelog按版本（npm/maven/pypi）生成SDK。
在SDK中用注释/注释标记旧方法。

11）按版本划分的观察力

分开收集指标：

每个版本的RPS/潜在性/错误（"api_version"标签）。
Endpoint使用图：v1上还有谁？
Alerts：">10% 4xx due to contract mismatch","老客户>T日后的 X%"。

12）缓存和版本

路径上的版本提高了CDN的缓存能力。

对于标题/介质版本-仔细使用Vary：

`Vary: Accept, X-API-Version`.
不要改变MINOR中响应的语义来打破kesh键。

13）安全性

不要在JWT中加密或缝制版本-版本定义查询而不是令牌。
不要透露装配的内部编号。在外部消息中,使用"v1/v2"。
在MAJOR中，修改验证，限制，PII掩盖。

14）迁移和汽车助理

发布"迁移指南v1 → v2"：字段对应表，查询/响应示例，边缘案例。
为突出显示旧字段的客户提供Linter （CLI）。
对于大型合作伙伴-具有两个版本的sandbox和测试日期。

15）反模式

"永恒的v1"：没有截止日期和使用指标。
MINOR/PATCH中隐藏的断开更改。
"查询字符串中的版本"（'?v=2'）-打破缓存和可读性。
"一个终点-一百个标志值"：难以测试/记录。

16）实施支票

1.为外部和内部客户选择了一个模型（URI/Accept/Header）。
2.SemVer for BOM和SDK, CI中的自动断路检查。
3.Deprecation/Sunset策略和通信模板。
4.网关路由+金丝雀，按版本行驶。
5.CDC/合同测试关键集成（付款，KYC，报告）。
6.文档/SDK/迁移指南与发布同时发布。
7.具有日期和责任的EOL计划。

17）示例

17.1 REST （URI+头条）

查询：


GET /v2/withdrawals/12345
Accept: application/json
Idempotency-Key: 4a1c-…-9f

答案是：

json
{
"id": "12345",
"status": "PENDING_REVIEW",
"amount": {"value": "100.00", "currency": "EUR"},
"limits": {"daily": "500.00"},
"created_at": "2025-10-02T10:00:00Z",
"links": [{"rel": "cancel", "href": "/v2/withdrawals/12345/cancel", "method": "POST"}]
}

剥夺标题（在v1上）：


Deprecation: true
Sunset: Tue, 31 Mar 2026 00:00:00 GMT
Link: </v2/docs>; rel="successor-version"

17.2 Content Negotation（介质）


GET /payments/987
Accept: application/vnd.company.payments.v2+json
Vary: Accept

17.3 GraphQL（场剥夺）

graphql type Payment {
id: ID!
amount: Money!
status: PaymentStatus!
method: PaymentMethod!
legacyCode: String @deprecated(reason: "Use field `method`")
}

17.4 gRPC (protobuf)

proto package payments.v2;

message Withdrawal {
string id = 1;
Money amount = 2;
string status = 3; // previously enum, now string with documented values reserved 4; // legacy field removed in v1 -> v2
}

17.5事件模型

Topics：

`wallet.v1.balance.updated`
`wallet.v2.balance.changed"（具有扩展模式的新事件）

方案存储在Registry中，制作人不会发布具有违反兼容性方案的事件。

18） iGaming/fintech的背景（实践）

付款：新的PSP输入v2，其中"status"/"decline_reason"得到了扩展；在网关上，mapping v1 → v2进行报告。
KYC： MINOR添加了"pep_screening"字段,v1客户机忽略,v2-要求。
负责任的游戏/限制：MAJOR改变了限制模式（每日/每周）。双重导出到EOL v1之前的报告。
向监管机构报告：固定日期版本："reporting-2025-01"。

19）迷你政策（示例wiki）

模型：用于外部API-"URI/vN/"；对于内部-"Accept：…… vN+json"或"X-API-Version： N"。
SemVer：规范和SDK发布为'N。minor.patch`.MAJOR需要RFC/ADR。
兼容性：MINOR/PATCH-无中断更改。仅通过MAJOR打破→。
Deprecation/EOL：≥90天公告；标题中的日落日期；面向关键客户的LTS分支。
控制：OpenAPI diff/buf breaking在CI, CDC中用于关键集成。
观察力：带有"api_version"标签的度量/逻辑。
发行版本：canary 5% ≥ 24小时，然后在绿色指标下分阶段高达100%。

结果

转化不是关于"/v2 in URL"，而是关于过程：明确的进化规则，自动兼容性检查，托管发行版和对集成的尊重。输入清晰的策略,自动控制和可观察性-更改将不再是对产品的威胁。

技术和基础设施→转化API

buf breaking для protobuf.

结果

联系我们

快速联系

视频即将更新

我们目前正忙于各项项目