30 lines
2.6 KiB
Markdown
30 lines
2.6 KiB
Markdown
# SDK 与协议兼容矩阵
|
||
|
||
当前发布线是 HTTP `/v1`、Worker WebSocket `pulse.worker.v1`、结果事件 WebSocket `orbit.events.v1`、Worker/事件帧 `protocol_version=1`、流程定义 `schema_version=1`，数据库要求 MySQL 8.4+ 与 Orbit schema v28。协议门禁由 `make protocol-check` 执行，检查服务端常量、SDK 常量、路由和机器可读 schema 是否一致。
|
||
|
||
| SDK / 客户端 | 服务端 | 当前证据 | 结论 |
|
||
| --- | --- | --- | --- |
|
||
| 当前仓库 SDK | 当前仓库服务端 | `scripts/test-protocol-compatibility.sh`、SDK 单元/竞态测试、HTTP/WSS 集成测试 | 已验证 |
|
||
| 历史提交 `a50d5fa` SDK | 当前服务端 | `make mysql-compatibility`，真实 MySQL/HTTP 任务 API 双向演练 | 任务 API smoke 已验证；不是正式标签或全协议结论 |
|
||
| 当前 SDK | 历史提交 `a50d5fa` 服务端 | `make mysql-compatibility`，真实 MySQL/HTTP 任务 API 双向演练 | 任务 API smoke 已验证；不是正式标签或全协议结论 |
|
||
| 上一个正式 SDK 标签 | 当前服务端 | 仓库尚未发布正式 SDK 标签 | 未验证，不得宣称兼容 |
|
||
| 当前 SDK | 上一个正式服务端标签 | 仓库尚未发布正式服务端标签 | 未验证，不得宣称兼容 |
|
||
| 非 Go HTTP 客户端 | 当前服务端 | `/v1` 接口手册、严格输入和错误码回归 | 按接口手册逐项验证 |
|
||
|
||
## 兼容规则
|
||
|
||
同一协议线内只允许保持字段语义、状态值和错误码含义不变的兼容扩展。新增响应字段通常由 HTTP JSON 客户端忽略；新增请求必填字段、修改既有字段类型/单位、修改状态终结语义或改变 WebSocket 帧方向，都不属于兼容扩展。Worker 和事件 SDK 的帧解码会拒绝未知字段或错误版本，避免把协议漂移当作业务结果。
|
||
|
||
发生不兼容变化时必须新建 HTTP 路径版本、WebSocket 子协议或 schema `$id`，并保留旧线的服务端/SDK 实现与回归，直到发布说明明确移除日期。不能仅增加一个文档版本字符串来掩盖行为变化。流程业务版本（例如定义的 `version`）与传输协议版本分开，业务版本固定在实例上，不改变旧实例的执行语义。
|
||
|
||
## 发布前组合
|
||
|
||
候选版本至少执行：
|
||
|
||
```sh
|
||
make protocol-check
|
||
make sdk-check
|
||
```
|
||
|
||
然后在干净 checkout 中用候选 SDK module 标签运行健康、任务、Worker、事件订阅、流程定义/实例/恢复和文件转换示例。历史提交演练只证明稳定任务 API 的有限范围；旧/新跨版本的完整协议组合、TLS 终止、外部副作用和生产容量仍需在正式发布候选及接入方环境单独验证。
|