> ## Documentation Index
> Fetch the complete documentation index at: https://openapidocs.flexforwardship.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 版本管理

> Flex Forward API 如何处理变更与向后兼容性

<Note>
  此页面由英文翻译而成。[英文版](/introduction)为官方权威来源。如翻译内容有任何不一致之处，请以英文版为准。
</Note>

# 版本管理

Flex Forward API 以长期稳定性为设计目标。变更会谨慎进行，以避免破坏现有集成。

## 当前版本

API 当前版本为 **1.0.0**。URL 中没有版本前缀 — 所有端点直接访问（例如 `POST /labels`，而非 `POST /v1/labels`）。

## 向后兼容性

Flex Forward 团队致力于维护向后兼容性。现有集成会在 API 演进的同时持续运作。

### 非破坏性变更

以下变更可能在未事先通知的情况下进行。您的集成应妥善处理：

* 在请求体中新增可选字段
* 在响应体中新增字段
* 新增 API 端点
* 在响应字段中新增枚举值
* 为边界情况新增 HTTP 状态码
* 改善错误消息的清晰度

<Note>
  对 API 响应中的未预期字段，请忽略而非视为错误。对未知的枚举值也请妥善处理 — 例如，将无法识别的追踪 `tag` 视为 `Unknown`。这能确保您的集成对非破坏性新增具有韧性。
</Note>

### 破坏性变更

以下变更被视为破坏性且将事先通知：

* 移除或重命名现有字段
* 变更现有字段的数据类型
* 移除 API 端点
* 变更身份验证机制
* 变更现有状态码的含义

破坏性变更将通过[变更记录](/zh-Hans/changelog)以及对受影响的 API 使用者的直接通知提前公布。非破坏性改善可能在维持现有集成向后兼容性的前提下，无需变更 URL 版本即可发布。

## 集成建议

* 宽容地解析响应体 — 忽略未知字段
* 不要使用会拒绝新字段的严格模式来验证响应
* 关注[变更记录](/zh-Hans/changelog)以获取 API 变更的更新
* 更新集成时在[开发环境](/zh-Hans/environments)中进行测试