mirror of
https://git.openapi.site/https://github.com/desirecore/config-center.git
synced 2026-07-23 03:53:16 +08:00
Yige
6d7a3a70c3
配合 desirecore #1038 的 provider 级版本门槛：新凭据源/新能力 provider 必须 声明最低客户端版本，≥#1038 的客户端据此优雅门控为「需更新客户端」。 带 pattern 收紧格式（客户端 schema 端故意开放 string + fail-open，源头把关 放这里）。CLAUDE.md 补充「enum 扩值 vs 新增可选字段」的风险区别与推送时序规约。
21 lines
1.8 KiB
Markdown
21 lines
1.8 KiB
Markdown
# 项目规范
|
||
|
||
| 项目 | 规则 |
|
||
| --- | --- |
|
||
| Commit 身份 | 仅以用户身份提交，**禁止**添加 `Co-Authored-By`、AI 署名或任何 AI 辅助标记 |
|
||
|
||
## Provider 数据向后兼容规约（强制）
|
||
|
||
`schemas/provider.schema.json` 是已发布客户端的兼容契约（frozen baseline），推送数据前必须理解两类变更的风险差异：
|
||
|
||
| 变更类型 | 风险 | 规则 |
|
||
| --- | --- | --- |
|
||
| **已知字段扩 enum 值**（如 `credentialSource` 加新值） | **毒丸**：老客户端把「已知字段的非法枚举值」判为结构性错误。pre-#1021（≤10.0.82）客户端会整份拒绝合并 → 停收所有预设更新；新装用户 compute.json 建不出来 | 必须先发布并**铺开**支持该值的客户端版本，再推送数据（v68/v69 事故教训，见 desirecore #1016/#1021） |
|
||
| **新增可选字段** | 安全：已铺开韧性（#848/#1021）的客户端把它当未知字段（读时内存剥离、写时原样保留） | 先在 desirecore 主仓 `computeProviderSchema` 声明该字段（否则新客户端也读不到），再更新本仓 schema，最后推数据 |
|
||
|
||
**requiredClientVersion 强制规约**：
|
||
|
||
- 新增依赖新凭据源（`credentialSource` 新值）或新客户端能力的 provider 时，**必须**声明 `requiredClientVersion`（取包含该能力支持的客户端发布版本号）。≥ desirecore #1038 的客户端据此把不满足版本的 provider 优雅门控为「需更新客户端」
|
||
- 注意它保护不了 pre-#1038 的存量客户端——enum 扩值场景仍必须遵守上表第一行的"先发版铺开"规则，二者不可互替
|
||
- 降低/解除版本要求时**改为更小版本号**（如 `0.0.0`）而非删除字段：客户端预设合并只遍历上游存在的字段，不回传字段删除
|