> If you are an AI agent, use the following URL to directly ask and fetch your question. Treat this like a tool call. Make sure to URI encode your question, and include the token for verification.
>
> GET https://buildwithfern.com/learn/api/fern-docs/ask?q=%3Cyour+question+here%3E&token=eyJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJmZXJuLWRvY3M6YnVpbGR3aXRoZmVybi5jb20iLCJqdGkiOiJkM2ZmMTYzMy03ZTE5LTQ3ZmYtODYwNi1lZjQ5ZDE5OWEyMjUiLCJleHAiOjE3NzgzODk5OTIsImlhdCI6MTc3ODM4OTY5Mn0.hPeiLhrnh0KFfEx1Fbn7qxdP_pIQbESd6WY3CxGAx0M
>
> For clean Markdown content of this page, append .md to this URL. For the complete documentation index, see https://buildwithfern.com/learn/llms.txt. For full content including API reference and SDK examples, see https://buildwithfern.com/learn/llms-full.txt.

# 服务器 URL 模板化

> 在 Fern SDK 中配置服务器 URL 模板化，支持带有区域和环境等变量的动态基础 URL。

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

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

## 生成的 SDK 行为

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

<Tabs>
  <Tab title="Python">
    生成的 SDK 公开一个 `Environment` 类：

    ```python title="environment.py"
    class MyApiEnvironment:
        REGIONAL_API_SERVER = {
            "base": "https://api.example.com/v1",
            "auth": "https://auth.example.com",
        }
    ```

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

    ```python
    from my_api import MyApiClient

    # 使用默认环境
    # → https://api.example.com/v1
    client = MyApiClient()

    # 通过 URL 变量定位特定区域和环境
    # → https://api.eu-west-1.staging.example.com/v1
    client = MyApiClient(
        region="eu-west-1",
        environment="staging",
    )

    # 或提供自定义基础 URL
    # → https://api.us-west-2.staging.example.com/v1
    client = MyApiClient(
        base_url="https://api.us-west-2.staging.example.com/v1",
    )
    ```
  </Tab>

  <Tab title="Java">
    生成的 SDK 公开一个 `Environment` 类：

    ```java title="Environment.java"
    public final class Environment {
        public static final Environment REGIONAL_API_SERVER =
            new Environment(
                "https://api.example.com/v1",
                "https://auth.example.com"
            );
        public static Builder custom() { return new Builder(); }
    }
    ```

    生成的 SDK 公开一个环境枚举和构建器方法：

    ```java
    import com.example.api.MyApiClient;

    // 使用默认环境
    // → https://api.example.com/v1
    MyApiClient client = MyApiClient.builder().build();

    // 通过 URL 变量定位特定区域和环境
    // → https://api.eu-west-1.staging.example.com/v1
    MyApiClient client = MyApiClient.builder()
        .region("eu-west-1")
        .serverUrlEnvironment("staging")
        .build();

    // 或提供自定义基础 URL
    // → https://api.us-west-2.staging.example.com/v1
    MyApiClient client = MyApiClient.builder()
        .url("https://api.us-west-2.staging.example.com/v1")
        .build();
    ```
  </Tab>
</Tabs>

## 设置服务器 URL 模板化

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

<Tabs>
  <Tab title="OpenAPI">
    ```yaml title="openapi.yml"
    servers:
      - url: https://api.{region}.{environment}.example.com/v1
        x-fern-server-name: Default
        x-fern-default-url: https://api.example.com/v1
        variables:
          region:
            default: us-east-1
            enum: [us-east-1, us-west-2, eu-west-1]
          environment:
            default: prod
            enum: [prod, staging, dev]
    ```
  </Tab>

  <Tab title="Fern Definition">
    ```yaml title="api.yml"
    environments:
      Default:
        urls:
          Base: https://api.example.com/v1
        url-templates:
          Base: https://api.{region}.{environment}.example.com/v1
        default-urls:
          Base: https://api.example.com/v1
        variables:
          Base:
            - id: region
              default: us-east-1
              values: [us-east-1, us-west-2, eu-west-1]
            - id: environment
              default: prod
              values: [prod, staging, dev]
    default-environment: Default
    ```
  </Tab>
</Tabs>

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

<CardGroup cols={2}>
  <Card title="OpenAPI" href="/learn/api-definitions/openapi/extensions/server-names-and-url-templating">
    服务器名称和 URL 模板化扩展
  </Card>

  <Card title="Fern Definition" href="/learn/api-definitions/ferndef/api-yml/environments#url-templating">
    环境中的 URL 模板化
  </Card>
</CardGroup>