Electrolux_blog
Search K

Appearance

目录

版本管理与兼容性 ​

概述 ​

UCP 使用日期格式版本控制（YYYY-MM-DD），并实现了独立的组件版本控制机制。协议版本和能力版本独立管理，使得不同组件可以独立演进，同时保持向后兼容性。

版本格式 ​

日期格式 ​

UCP 使用日期格式版本控制：YYYY-MM-DD

优势：

  • 清晰的 chronological ordering（时间顺序）
  • 明确的版本比较
  • 易于理解版本关系
  • 避免语义版本号的歧义

示例：

  • 2026-01-11：2026年1月11日版本
  • 2026-01-23：2026年1月23日版本
  • 2026-02-01：2026年2月1日版本

版本比较 ​

版本比较基于日期：

python
def compare_versions(v1, v2):
    """比较两个版本"""
    from datetime import datetime
    
    d1 = datetime.strptime(v1, "%Y-%m-%d")
    d2 = datetime.strptime(v2, "%Y-%m-%d")
    
    if d1 < d2:
        return -1
    elif d1 > d2:
        return 1
    else:
        return 0

# 示例
compare_versions("2026-01-11", "2026-01-23")  # -1 (v1 < v2)
compare_versions("2026-01-23", "2026-01-11")  # 1 (v1 > v2)
compare_versions("2026-01-23", "2026-01-23")  # 0 (v1 == v2)

版本发现与协商 ​

协议版本 ​

协议版本（ucp.version）管理核心协议机制：

  • 发现流程
  • 协商流程
  • 传输绑定
  • 签名要求

能力版本 ​

能力版本独立于协议版本管理：

  • 每个能力独立版本化
  • 能力版本独立演进
  • 支持能力级别的向后兼容

版本声明 ​

商家和平台在 Profile 中声明单个版本：

商家 Profile：

json
{
  "ucp": {
    "version": "2026-01-23",
    "services": { ... },
    "capabilities": { ... }
  }
}

平台 Profile：

json
{
  "ucp": {
    "version": "2026-01-23",
    "services": { ... },
    "capabilities": { ... }
  }
}

版本协商 ​

版本兼容性在两个级别运行：协议版本和能力版本。

协议版本协商 ​

  1. 平台获取商家 Profile：从 /.well-known/ucp 获取当前版本 Profile

  2. 版本匹配：

    • 如果平台的协议版本匹配 version：直接使用此 Profile
    • 如果平台的协议版本是 supported_versions 中的键：获取该版本特定的 Profile
    • 否则：商家不支持平台的协议版本

  3. 请求时验证：商家必须在每个请求上验证平台的协议版本

能力版本协商 ​

能力版本在能力交集算法中协商：

  1. 计算交集：找到双方都支持的能力
  2. 版本选择：对于交集中的每个能力，选择双方都支持的最高版本
  3. 排除不兼容：如果没有共同版本，排除该能力

向后兼容性 ​

向后兼容的更改 ​

以下更改可以在不引入新版本的情况下引入：

  • 在响应中添加新的非必需字段
  • 在请求中添加新的非必需参数
  • 向传输添加新的端点、方法或操作
  • 使用现有错误结构添加新的错误代码
  • 向枚举添加新值（除非明确记录为 exhaustive）
  • 更改响应中字段的顺序
  • 更改不透明字符串的长度或格式（ID、令牌）

破坏性更改 ​

以下更改不得在不引入新版本的情况下引入：

  • 删除或重命名现有字段
  • 更改字段类型或语义
  • 使非必需字段成为必需
  • 删除操作、方法或端点
  • 更改认证或授权要求
  • 修改现有协议流程或状态机
  • 更改现有错误代码的含义

独立组件版本控制 ​

原则 ​

  • UCP 协议独立于能力版本化
  • 每个能力独立于其他能力版本化
  • 能力必须遵循与协议相同的向后兼容性规则
  • 商家必须使用与上述相同的逻辑验证能力版本兼容性
  • 传输可以定义自己的版本处理机制

UCP 能力（dev.ucp.*） ​

UCP 编写的能力默认随协议发布版本化。当需要协议发布周期之外的破坏性更改时，个别能力可以独立版本化。

供应商能力（com.{vendor}.*） ​

dev.ucp.* 命名空间之外的能力完全独立版本化。供应商控制自己的发布计划和版本控制策略。

版本特定 Profile ​

supported_versions 字段 ​

支持旧协议版本的商家应该声明 supported_versions 对象，将每个旧版本映射到 Profile URI：

json
{
  "ucp": {
    "version": "2026-01-23",
    "supported_versions": {
      "2026-01-11": "https://business.example.com/.well-known/ucp/2026-01-11"
    },
    "services": { ... },
    "capabilities": { ... }
  }
}

版本特定 Profile 要求 ​

版本特定的 Profile 是叶文档——它们描述恰好一个协议版本，不得包含 supported_versions 字段。

版本生命周期 ​

版本生命周期，包括何时弃用或从 supported_versions 中移除旧版本，是业务策略决策。协议不规定弃用计划。

版本发现流程 ​

初始服务和能力发现 ​

平台通过以下流程发现商家的能力：

  1. 获取当前版本 Profile：平台获取 /.well-known/ucp——这是当前版本 Profile
  2. 版本匹配：
    • 如果平台的协议版本匹配 version：使用此 Profile 直接进行能力协商
    • 如果平台的协议版本是 supported_versions 中的键：获取该版本映射的 URI 处的 Profile。此 Profile 描述该协议版本可用的能力。进行能力协商
    • 否则：商家不支持平台的协议版本。平台不应发送不兼容版本的请求；商家必须响应 version_unsupported 错误

请求时验证 ​

商家必须在每个请求上验证平台的协议版本：

  1. 平台声明版本：平台通过请求中引用的 Profile 中的 version 字段声明它使用的协议版本
  2. 商家验证：
    • 如果平台的 version 匹配商家的 version 或是 supported_versions 中的键：请求可以使用匹配版本的商家 Profile 进行能力协商
    • 否则：商家必须返回 version_unsupported 错误
  3. 能力协商：如果能力协商对请求操作所需的能力没有产生相互支持的版本，商家必须返回 capabilities_incompatible 错误
  4. 响应要求：商家必须在每个响应中包含协商的协议版本

响应中的版本确认 ​

json
{
  "ucp": {
    "version": "2026-01-23",
    "capabilities": { ... },
    "payment_handlers": { ... }
  },
  "id": "checkout_123",
  "status": "incomplete"
}

版本不支持错误 ​

json
{
  "ucp": { "version": "2026-01-11", "status": "error" },
  "messages": [{
    "type": "error",
    "code": "version_unsupported",
    "content": "Version 2026-01-12 is not supported. This business implements version 2026-01-11.",
    "severity": "unrecoverable"
  }],
  "continue_url": "https://merchant.com/"
}

能力版本 ​

能力版本数组 ​

Profile 中的每个能力是一个数组。同一能力的多个条目，每个具有不同的 version，广告支持该能力的多个版本。

版本选择算法 ​

能力交集算法只考虑双方都支持的能力版本：

python
def select_capability_version(business_versions, platform_versions):
    """选择能力版本"""
    
    # 计算共同版本
    business_version_set = {v['version'] for v in business_versions}
    platform_version_set = {v['version'] for v in platform_versions}
    
    common_versions = business_version_set & platform_version_set
    
    if not common_versions:
        return None  # 无共同版本
    
    # 选择最高版本
    return max(common_versions)

兼容性要求 ​

商家必须在响应中仅包含与协商的协议版本兼容的能力。依赖在新协议版本中引入的功能的能力不得在处理旧协议版本时包含。

扩展版本依赖 ​

requires 字段 ​

扩展 Schema 可以声明 requires 对象来指示所需的协议和能力版本：

json
{
  "name": "com.acme.shopping.loyalty",
  "requires": {
    "protocol": { "min": "2026-01-23" },
    "capabilities": {
      "dev.ucp.shopping.checkout": { "min": "2026-06-01" }
    }
  }
}

约束格式 ​

每个约束是一个对象，包含必需的 min（包含）和可选的 max（包含）版本：

json
"requires": {
  "protocol": { "min": "2026-01-23", "max": "2026-09-01" },
  "capabilities": {
    "dev.ucp.shopping.checkout": { "min": "2026-06-01" }
  }
}

当 max 缺失时，没有上限。

验证逻辑 ​

在 Schema 解析期间，平台和商家必须验证协商的协议版本和能力版本满足声明的约束。不兼容的扩展从激活能力集中排除。

迁移策略 ​

对于商家 ​

  1. 渐进式迁移：逐步迁移到新版本
  2. 并行支持：同时支持多个版本
  3. 版本特定 Profile：为旧版本提供版本特定 Profile
  4. 弃用通知：提前通知版本弃用

对于平台 ​

  1. 版本检测：检测商家支持的版本
  2. 自动适配：自动选择兼容版本
  3. 降级处理：如果新版本不可用，使用旧版本
  4. 迁移计划：制定版本迁移计划

最佳实践 ​

版本管理 ​

  1. 语义清晰：使用日期格式确保版本语义清晰
  2. 向后兼容：尽可能保持向后兼容
  3. 文档化：清晰文档化破坏性更改
  4. 测试：测试版本兼容性

能力版本化 ​

  1. 独立演进：能力独立版本化
  2. 版本依赖：使用 requires 字段声明版本依赖
  3. 兼容性测试：测试能力版本兼容性

扩展版本化 ​

  1. 版本约束：使用 requires 字段声明版本约束
  2. 兼容性验证：验证扩展版本兼容性
  3. 文档化：文档化版本要求

总结 ​

UCP 的版本管理实现了：

  1. 日期格式版本控制：清晰的版本语义和比较
  2. 独立组件版本控制：协议和能力独立版本化
  3. 向后兼容性：明确的兼容性规则
  4. 灵活迁移：支持渐进式迁移和多版本共存
  5. 版本发现：自动版本发现和协商

这种设计使得 UCP 能够：

  • 支持渐进式演进
  • 保持向后兼容性
  • 实现灵活的版本管理
  • 支持独立的能力演进

MIT License.

Copyright © 2023～present Electrolux