添加自定义代码 (Java) | Fern Documentation

本页面介绍如何向您的 Java SDK 添加自定义逻辑、方法和依赖项。

Before getting started, read about how Fern SDKs use custom code and learn about the .fernignore file.

添加自定义逻辑

开始添加自定义代码：

创建新文件并添加您的自定义逻辑

src/main/java/<package>/Helper.java

1 package com.example.helper;
2 
3 public class Helper {
4 
5 public static void myHelper() {
6     System.out.println("Hello World!");
7 }
8 
9 }

将您的文件添加到 `.fernignore`

.fernignore

1 # 指定不应被 Fern 修改的文件
2 
3 src/main/java/<package>/Helper.java

使用助手方法

Now your users can consume the helper function by importing it from the SDK.

1 import com.example.helper.Helper;
2 
3 public class Main {
4 
5 public static void main(String[] args) {
6     Helper.myHelper();
7 }
8 
9 }

添加自定义 SDK 方法

Fern also allows you to add custom methods to the SDK itself (e.g. client.my_method() ) by inheriting the Fern generated client and then extending it.

更新 `generators.yml` 配置

将您的 Fern 生成的客户端命名为类似 BaseClient 的名称，以反映此客户端将被扩展。

generators.yml

1 - name: fernapi/fern-java-sdk
2     version: "..."
3     config:
4       client-class-name: BaseClient

导入并扩展生成的客户端

首先，导入 Fern 生成的基础客户端并扩展它。然后，添加您想要的任何方法。

src/main/java/com/example/MyClient.java

1 package com.example;
2 
3 import com.example.client.BaseClient;
4 
5 public class MyClient extends BaseClient { // 扩展 Fern 生成的客户端
6 
7   public void myHelper() {
8     System.out.println("Hello World!");
9   }
10 
11 }

更新 `.fernignore`

将 MyClient.java 添加到 .fernignore。

.fernignore

1 + src/main/java/com/example/MyClient.java

使用方法

Now your users can consume the helper function by importing it from the SDK.

1 client.myHelper();

添加自定义客户端配置

Java SDK 生成器通过可选的自类型模式支持构建器扩展性。当通过 enable-extensible-builders 标志启用时，生成的构建器可以被扩展，同时在方法链接过程中保持类型安全。

常见用例包括：

动态 URL 构造：使用运行时值替换占位符（例如，https://api.${TENANT}.example.com）
自定义身份验证：实现超出基本令牌认证的复杂认证流程
请求转换：全局添加自定义标头或修改请求
多租户支持：添加特定租户的配置和标头

启用可扩展构建器

将标志添加到您的 generators.yml：

generators.yml

1 groups:
2   local:
3     generators:
4       - name: fernapi/fern-java-sdk
5         version: 2.39.6
6         config:
7           enable-extensible-builders: true

工作原理

生成的构建器使用自类型模式进行类型安全的方法链接：

1 public abstract class BaseClientBuilder<T extends BaseClientBuilder<T>> {
2     protected abstract T self();
3     
4     public T token(String token) {
5         return self();  // 返回您的自定义类型，而不是 BaseClientBuilder
6     }
7 }

创建自定义构建器

扩展生成的构建器：

src/main/java/com/example/CustomApiBuilder.java

1 public class CustomApiBuilder extends BaseClientBuilder<CustomApiBuilder> {
2     @Override
3     protected CustomApiBuilder self() {
4         return this;
5     }
6 
7     @Override
8     protected void setEnvironment(ClientOptions.Builder builder) {
9         // 自定义环境 URL
10         String url = this.environment.getUrl();
11         String expandedUrl = expandEnvironmentVariables(url);
12         builder.environment(Environment.custom(expandedUrl));
13     }
14 
15     @Override
16     protected void setAdditional(ClientOptions.Builder builder) {
17         // 添加自定义标头
18         builder.addHeader("X-Request-ID", () -> UUID.randomUUID().toString());
19     }
20 }

使用您的自定义构建器

1 BaseClient client = new CustomApiBuilder()
2     .token("my-token")        // 返回 CustomApiBuilder
3     .tenantId("tenant-123")   // 返回 CustomApiBuilder  
4     .timeout(30)              // 返回 CustomApiBuilder
5     .build();
6 
7 client.users().list();

更新 `.fernignore`

将您的自定义构建器添加到 .fernignore，这样 Fern 就不会覆盖它：

.fernignore

1 + src/main/java/com/example/CustomApiBuilder.java

默认实现

如果您不需要扩展构建器，请使用提供的 Impl 类：

1 BaseClient client = BaseClientBuilder.Impl()
2     .token("my-token")
3     .timeout(30)
4     .build();

方法参考

每个方法都有特定的目的，仅在需要时生成：

方法	目的	可用时机
`self()`	返回用于链接的具体构建器类型	始终（抽象）
`setEnvironment(builder)`	自定义环境/URL 配置	始终
`setAuthentication(builder)`	修改或添加身份验证	仅当 API 具有认证时
`setCustomHeaders(builder)`	添加 API 规范中定义的自定义标头	仅当 API 定义标头时
`setVariables(builder)`	配置 API 变量	仅当 API 具有变量时
`setHttpClient(builder)`	自定义 OkHttp 客户端	始终
`setTimeouts(builder)`	修改超时设置	始终
`setRetries(builder)`	修改重试设置	始终
`setAdditional(builder)`	任何自定义配置的最终扩展点	始终
`validateConfiguration()`	添加自定义验证逻辑	始终

常见模式

多租户 URL

1 @Override
2 protected void setEnvironment(ClientOptions.Builder builder) {
3     String url = this.environment.getUrl()
4         .replace("/api/", "/tenants/" + tenantId + "/");
5     builder.environment(Environment.custom(url));
6 }

动态身份验证

1 @Override
2 protected void setAuthentication(ClientOptions.Builder builder) {
3     super.setAuthentication(builder); // 保留现有认证
4     builder.addHeader("Authorization", () ->
5         "Bearer " + tokenProvider.getAccessToken()
6     );
7 }

环境变量扩展

1 @Override
2 protected void setEnvironment(ClientOptions.Builder builder) {
3     String url = this.environment.getUrl();
4     // 使用环境变量替换 ${VAR_NAME}
5     Pattern pattern = Pattern.compile("\\$\\{([^}]+)\\}");
6     Matcher matcher = pattern.matcher(url);
7     StringBuffer result = new StringBuffer();
8     
9     while (matcher.find()) {
10         String envVar = System.getenv(matcher.group(1));
11         matcher.appendReplacement(result, 
12             envVar != null ? envVar : matcher.group(0));
13     }
14     matcher.appendTail(result);
15     
16     builder.environment(Environment.custom(result.toString()));
17 }

请求跟踪

1 @Override
2 protected void setAdditional(ClientOptions.Builder builder) {
3     builder.addHeader("X-Request-ID", () -> UUID.randomUUID().toString());
4     builder.addHeader("X-Tenant-ID", this.tenantId);
5     
6     if (FeatureFlags.isEnabled("new-feature")) {
7         builder.addHeader("X-Feature-Flag", "new-feature");
8     }
9 }

要求

Fern Java SDK 版本：2.39.6 或更高版本
配置：在 generators.yml 中设置 enable-extensible-builders: true

添加自定义依赖项

专业版和企业版功能

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

要添加您的自定义代码所需的包，请更新您的 generators.yml。

generators.yml

1 - name: fernapi/fern-java-sdk
2   version: "..."
3   config:
4     custom-dependencies:
5       - org.apache.commons:commons-lang3:3.12.0
6       - org.slf4j:slf4j-api:2.0.7

添加自定义逻辑

创建新文件并添加您的自定义逻辑

将您的文件添加到 .fernignore

使用助手方法

添加自定义 SDK 方法

更新 generators.yml 配置

导入并扩展生成的客户端

更新 .fernignore

使用方法

添加自定义客户端配置

启用可扩展构建器

工作原理

创建自定义构建器

使用您的自定义构建器

更新 .fernignore

默认实现

方法参考

常见模式

多租户 URL

动态身份验证

环境变量扩展

请求跟踪

要求

添加自定义依赖项

专业版和企业版功能

将您的文件添加到 `.fernignore`

更新 `generators.yml` 配置

更新 `.fernignore`

更新 `.fernignore`