SDK 设计

自托管 SDK 版本管理

以 Markdown 格式查看
企业功能

此功能仅适用于企业计划。如需开始使用，请联系 support@buildwithfern.com。

自托管时，您的流水线为每次 SDK 发布选择版本号。与云端生成不同，自托管设置需要自行计算下一个版本。

CLI 提供两种工作流，可以接入同一生成流水线：

  • --version AUTO 是推荐方式。Fern 对照完整 SDK 输出对变更进行分类 — 因此 generators.yml 设置、生成器版本升级或 CLI 版本升级驱动的变更都会反映在选取的版本中 — 并为您生成变更日志条目、PR 描述和规范化提交消息。此路径也是持续改进的方向。
  • fern ir + fern diff 是确定性替代方案。它比较 API 规范的中间表示 (IR) 并仅返回计算的版本提升和下一版本号。由于差异比较仅针对规范本身，它不考虑来自 generators.yml 配置、生成器版本或 CLI 版本的 SDK 实现变更 — 如果其中任何一项发生变化，您需要自行提升版本。其余发布产物（变更日志、PR 描述、提交消息）也由您编写。当您需要对版本号的推导方式有明确控制，或无法依赖外部 LLM 提供商时，使用此工作流。

--version AUTO（推荐）

将 --version AUTO 传递给 fern generate，Fern 会分析上一次和当前 SDK 输出之间的差异，将变更分类为 MAJOR、MINOR 或 PATCH，并将下一个语义版本应用到生成的包中。同一分析还会生成：

  • 描述变更内容的变更日志条目
  • 总结发布内容的 PR 描述
  • 规范化提交消息

--version AUTO 需要：

  • 用于组织验证的 FERN_TOKEN（与所有自托管生成相同）。
  • 在 generators.yml 中配置的 GitHub 输出，因为流水线需要将版本提升和变更日志推送回 SDK 仓库。
1

配置 AI 提供商

在 generators.yml 中设置提供商和模型：

generators.yml
1ai:
2  provider: openai   # openai | anthropic | bedrock
3  model: gpt-4o      # 提供商接受的任何模型名称
2

设置提供商凭据

导出匹配的 API 密钥，以便 Fern CLI 调用提供商：

  • OPENAI_API_KEY 用于 OpenAI
  • ANTHROPIC_API_KEY 用于 Anthropic
  • 标准 AWS 凭据（AWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEY、AWS_REGION）用于 AWS Bedrock

差异通过您的凭据发送到提供商的 API — Fern 的基础设施不参与分析过程。

3

使用 --version AUTO 运行生成

$FERN_TOKEN=<token> fern generate --local --version AUTO

使用 fern ir + fern diff 进行确定性版本管理

如果您更倾向于自行推导版本号，可使用 fern ir 和 fern diff 命令从 API 定义计算版本提升。此工作流无 LLM 依赖：fern diff 遍历两个规范的中间表示 (IR) 并返回确定性结果。

工作流有三个步骤：

1

生成之前的 IR

检出上次 SDK 生成时的规范并将其 IR 写入磁盘：

$fern ir old-ir.json

如果您的项目定义了多个 API，请传递 --api <name>。

2

生成当前的 IR

检出 HEAD 处的规范并将其 IR 写入磁盘：

$fern ir new-ir.json
3

比较两个 IR

使用 --from-version 设置为 SDK 当前版本运行 fern diff。提供 --from-version 时，命令会打印包含计算的版本提升和下一版本的 JSON 对象：

$fern diff \
>  --from old-ir.json \
>  --to new-ir.json \
>  --from-version 1.4.2
1{
2  "bump": "minor",
3  "nextVersion": "1.5.0",
4  "errors": []
5}

bump 是 major、minor、patch 或 no_change 之一。将 nextVersion 传递给 fern generate 以发布该确切版本：

$fern generate --local --version 1.5.0

当计算的版本提升为 major 时，fern diff 以非零状态退出。这使得在 CI 中将破坏性变更设置为需要手动审查变得容易。

将 fern ir + fern diff 集成到 CI

不太直观的部分是为之前的规范重现 IR。每个生成的 SDK 会在 .fern/metadata.json 中记录生成时的配置仓库提交：

.fern/metadata.json
1{
2  "cliVersion": "0.74.0",
3  "generatorName": "fernapi/fern-python-sdk",
4  "generatorVersion": "4.0.0",
5  "originGitCommit": "a1b2c3d4e5f6...",
6  "requestedVersion": "1.4.2",
7  "sdkVersion": "1.4.2"
8}

originGitCommit 是配置仓库中产生当前版本 SDK 的 SHA。检出该提交，运行 fern ir，然后切换回 HEAD 再次运行 fern ir，以产生 fern diff 的两个输入。

以下代码片段在每次推送到 main 时在配置仓库中运行，并计算 Python SDK 的下一个版本，其 originGitCommit 和 sdkVersion 从 SDK 仓库读取：

.github/workflows/release-sdk.yml
1name: Release SDK
2
3on:
4  push:
5    branches: [main]
6
7jobs:
8  release:
9    runs-on: ubuntu-latest
10    env:
11      FERN_TOKEN: ${{ secrets.FERN_TOKEN }}
12      SDK_REPO: your-org/python-sdk
13    steps:
14      - name: Check out config repo
15        uses: actions/checkout@v4
16        with:
17          fetch-depth: 0
18
19      - name: Set up Fern CLI
20        uses: fern-api/setup-fern-cli@v1
21
22      - name: Read previous SDK metadata
23        id: meta
24        run: |
25          curl -fsSL \
26            -H "Authorization: token ${{ secrets.GITHUB_TOKEN }}" \
27            -H "Accept: application/vnd.github.raw" \
28            "https://api.github.com/repos/${SDK_REPO}/contents/.fern/metadata.json" \
29            > metadata.json
30          echo "old_sha=$(jq -r .originGitCommit metadata.json)" >> "$GITHUB_OUTPUT"
31          echo "from_version=$(jq -r .sdkVersion metadata.json)" >> "$GITHUB_OUTPUT"
32
33      - name: Generate previous IR
34        run: |
35          git checkout ${{ steps.meta.outputs.old_sha }}
36          fern ir old-ir.json --api <your-api-name>
37
38      - name: Generate current IR
39        run: |
40          git checkout ${{ github.sha }}
41          fern ir new-ir.json --api <your-api-name>
42
43      - name: Compute next version
44        id: diff
45        run: |
46          result=$(fern diff \
47            --from old-ir.json \
48            --to new-ir.json \
49            --from-version ${{ steps.meta.outputs.from_version }}) || true
50          bump=$(echo "$result" | jq -r .bump)
51          if [ "$bump" = "major" ]; then
52            echo "Computed a major version bump — manual review required before releasing."
53            exit 1
54          fi
55          echo "next_version=$(echo "$result" | jq -r .nextVersion)" >> "$GITHUB_OUTPUT"
56
57      - name: Generate SDK
58        run: fern generate --local --group python-sdk --version ${{ steps.diff.outputs.next_version }}

检出步骤的 fetch-depth: 0 是必需的，以便运行器拥有检出 originGitCommit 所需的历史记录。将元数据获取步骤替换为任何能让您的流水线访问 SDK 仓库 .fern/metadata.json 的机制（检出 SDK 仓库、发布产物、内部 API 等）。