SDK 设计

服务器 URL 模板化

以 Markdown 格式查看

服务器 URL 模板化允许您定义带有变量占位符（例如 {region}、{environment}）的基础 URL，SDK 用户可以在运行时自定义这些变量。这对于部署在多个区域、环境或自定义域中的 API 非常有用。

URL 模板化目前仅支持 Python 和 Java SDK 生成。

生成的 SDK 行为

Fern 生成一个环境模块，为每个命名服务器公开默认 URL。SDK 用户可以选择预定义的环境或传递自定义 URL 字符串。

生成的 SDK 公开一个 Environment 类：

environment.py
1class MyApiEnvironment:
2    REGIONAL_API_SERVER = {
3        "base": "https://api.example.com/v1",
4        "auth": "https://auth.example.com",
5    }

SDK 用户可以在构造客户端时覆盖基础 URL：

1from my_api import MyApiClient
2
3# 使用默认环境
4# → https://api.example.com/v1
5client = MyApiClient()
6
7# 通过 URL 变量定位特定区域和环境
8# → https://api.eu-west-1.staging.example.com/v1
9client = MyApiClient(
10    region="eu-west-1",
11    environment="staging",
12)
13
14# 或提供自定义基础 URL
15# → https://api.us-west-2.staging.example.com/v1
16client = MyApiClient(
17    base_url="https://api.us-west-2.staging.example.com/v1",
18)

设置服务器 URL 模板化

在您的 API 定义中定义 URL 模板变量，并为不自定义变量的 SDK 用户提供静态回退 URL：

openapi.yml
1servers:
2  - url: https://api.{region}.{environment}.example.com/v1
3    x-fern-server-name: Default
4    x-fern-default-url: https://api.example.com/v1
5    variables:
6      region:
7        default: us-east-1
8        enum: [us-east-1, us-west-2, eu-west-1]
9      environment:
10        default: prod
11        enum: [prod, staging, dev]

有关完整配置详细信息，请查看您的 API 定义格式文档：

OpenAPI

服务器名称和 URL 模板化扩展

Fern Definition

环境中的 URL 模板化