2. 平台门户基线概念

平台门户基线是 Service Catalog 与门户集成时的核心契约，它定义了门户在某一时刻所依赖的接口集合、数据模型、认证方式及行为约束。理解基线概念是进行接口调用与校验的前提。

2.1 基线定义

基线（Baseline）是指在特定版本下，平台门户对外暴露的一组稳定、可复用的 API 接口及其相关配置的集合。它包含以下核心要素：

2.2 基线校验的目的

基线校验的核心目标是确保门户在升级、变更或集成新组件时，不会破坏已有的接口契约。具体目的包括：

• 兼容性保障：验证新版本接口是否向后兼容旧版本基线，避免下游消费者出现调用失败。
• 一致性验证：检查实际部署的接口行为是否与基线文档描述一致，防止“文档与实现脱节”。
• 回归检测：在门户迭代过程中，快速发现因代码变更导致的接口异常。
• 多环境对齐：确保开发、测试、生产环境使用同一套基线标准，减少环境差异带来的问题。
• 合规审计：为平台治理提供可追溯的接口版本记录，满足企业级合规要求。

2.3 基线在门户中的体现

基线在平台门户中通过以下具体形式体现：

1. API 网关路由：网关根据基线版本号将请求路由到对应版本的后端服务实例。
2. 接口文档门户：Swagger/OpenAPI 文档中明确标注每个接口所属的基线版本。
3. SDK 与客户端库：不同基线版本对应不同的 SDK 版本，开发者通过引入特定版本 SDK 来保证兼容性。
4. 配置中心：基线相关的限流阈值、超时时间、重试策略等配置项统一管理。
5. 监控告警：针对不同基线版本的接口设置独立的监控指标和告警规则。

2.4 基线版本管理

基线版本管理遵循语义化版本规范（SemVer），采用 主版本.次版本.修订号 的格式，并配合生命周期状态进行管理。

基线版本的生命周期管理包含以下阶段：

• 开发阶段（Draft）：基线处于设计或开发中，仅供内部测试使用。
• 预览阶段（Preview）：基线发布预览版，邀请部分消费者进行集成验证。
• 稳定阶段（Stable）：基线正式发布，所有消费者可依赖此版本进行生产调用。
• 废弃阶段（Deprecated）：基线标记为废弃，仍可调用但不再更新，建议消费者迁移。
• 退役阶段（Retired）：基线完全下线，接口返回 410 Gone 或重定向到新版本。