---
title: 版本与变更策略
description: 说明 API 版本线、变更通知、兼容策略和历史版本维护边界。
sidebar_position: 2
---


# 版本与变更策略

本页说明开放平台 API 和文档的版本治理原则，帮助合作方理解当前应该接入哪个版本，以及后续如何处理升级和兼容问题。

## 当前版本状态

截至目前：

- 当前对外稳定开放版本：`2.0`
- 当前已公开文档默认对应：`2.0`
- 后续新增实现与能力演进：进入 `3.0`

这意味着如果文档页面没有特别声明版本，现阶段应默认按 `2.0` 理解和接入。

## 版本命名规则

平台采用显式的大版本命名方式管理接口版本。

### API 路径

- `2.0`：`/v2/...`
- `3.0`：`/v3/...`

例如：

```text
/v2/nc.ms.drug.package.detail
/v3/...
```

### 文档路径

当前公开文档路径仍以现有 `/doc/*` 代表 `2.0`。

后续 `3.0` 文档将采用显式版本命名空间进行区分，避免和 `2.0` 混用。

## 2.0 的维护原则

`2.0` 是当前稳定版本，主要服务于已接入或正在接入的合作方。

`2.0` 的维护目标是稳定，而不是持续引入新语义。

因此，`2.0` 默认只做以下类型的更新：

1. 文档勘误和表达修正
2. 参数说明补充
3. 示例优化
4. 不改变既有语义的缺陷修复

原则上，以下内容不应继续直接写入 `2.0`：

- 新能力
- 新版本的核心实现
- 会改变字段语义的调整
- 会影响旧客户端理解的行为变化

## 3.0 的定位

`3.0` 是后续能力演进的主版本线。

凡是属于下面这些情况，默认都应进入 `3.0`：

1. 新增能力或新产品化接口
2. 需要重新组织字段结构的升级
3. 返回语义或业务口径发生明显变化
4. 需要引入新的接入方式、批量机制或结果模型

换句话说，`3.0` 不是对 `2.0` 的零散补丁，而是承接后续实现的主版本。

## 兼容原则

版本兼容遵循以下基本原则：

### 1. 已公开的 2.0 链接保持稳定

现有 `2.0` 文档链接和公开路径应继续可访问，避免影响已接入客户和外部引用。

### 2. 新版本不覆盖旧版本语义

`3.0` 的新增能力和字段演进，不应反向覆盖 `2.0` 文档页的原有含义。

### 3. 版本差异要显式表达

如果同一业务能力在 `2.0` 和 `3.0` 中都存在，文档中应明确写出差异点，例如：

- 请求参数是否变化
- 返回字段是否变化
- 字段含义是否变化
- 调用方式和分页机制是否变化

## 变更分类建议

为了避免版本线混乱，建议把变更分成三类：

### 文档型变更

只修正文案、错别字、示例或解释，不改变接口含义。

这类变更可以继续进入当前版本文档。

### 非破坏性补充

例如补充说明、增加背景信息、完善场景解释。

如果不影响旧客户端理解，也可以继续在当前版本文档中维护。

### 版本级演进

例如字段结构调整、返回语义变化、能力边界重定义、新主流程设计。

这类变更应进入 `3.0`，并在必要时提供迁移说明。

## 对合作方的实际建议

如处于准备接入阶段：

- 没有特殊说明时，按 `2.0` 文档接入
- 不要把尚未公开的 `3.0` 规划能力当作当前稳定能力
- 如果场景明确依赖后续新实现，应在立项阶段就确认是否走 `3.0`

如已在使用 `2.0`：

- 可以继续按 `2.0` 稳定文档运行
- 后续如需升级到 `3.0`，应优先关注版本差异和迁移说明

## 文档治理口径

从文档维护角度，当前推荐使用以下口径：

- `content/docs` 当前视为 `2.0` 内容源
- 现有 `/doc/*` 路径继续代表 `2.0`
- 后续 `3.0` 文档独立建设，避免直接覆盖当前文档

这套规则的目标只有一个：让存量客户继续稳定接入 `2.0`，同时给后续 `3.0` 演进留出清晰边界。