Resources

Fern vs. OpenAPI Generator

以 Markdown 格式查看

Fern 生成生产级 SDK,内置 OAuth token 刷新、分页、重试、类型错误处理和全面的文档。OpenAPI Generator 生成基本的 API 包装器,需要您自己实现这些功能。

功能FernOpenAPI Generator
文档全面的 README + 端点文档最小化(仅标题)
身份验证自动 OAuth token 刷新手动 token 管理
分页for await 的异步迭代器手动游标处理
错误处理每个状态码的类型化错误类通用的 ResponseError
弹性内置重试、超时、中止信号无(需要自定义代码)

文档和用户引导

Fern SDK 包含全面的文档,涵盖安装、身份验证、类型、错误、分页和重试。OpenAPI Generator 提供最小化的文档。

功能FernOpenAPI Generator
README涵盖安装、认证、类型、错误、分页、重试、超时、日志记录和运行时兼容性的全面指南最小化(通常只有标题)
端点文档为每个端点生成包含使用示例的 reference.md
代码示例方法文档中的内联示例

客户端人体工程学

Fern 提供具有命名空间资源的单一统一客户端。OpenAPI Generator 为每个资源使用单独的 API 类。

功能FernOpenAPI Generator
客户端结构具有命名空间资源的单一统一客户端每个资源的单独 API 类
方法命名简洁、惯用的名称(client.plant.add()冗长的名称(plantApi.addPlant()
配置在客户端构造函数中集中配置传递给每个 API 类

Fern
1const client = new PlantStoreClient({ clientId, clientSecret });
2await client.plant.add({ name: "Fern", status: "available" });
3await client.user.login();
OpenAPI Generator
1const config = new Configuration({ accessToken: async () => token });
2const plantApi = new PlantApi(config);
3const userApi = new UserApi(config);
4await plantApi.addPlant({ plant: { name: "Fern", status: "available" } });
5await userApi.loginUser({ username, password });

身份验证和 token 生命周期

Fern 包含内置的 OAuth token 提供者,自动检索和刷新 token,并在过期前配置缓冲时间。OpenAPI Generator 需要手动 token 管理。

功能FernOpenAPI Generator
OAuth token 刷新使用 OAuthTokenProvider 自动处理需要手动实现
Token 过期处理内置过期前缓冲开发者责任
环境变量自动回退到环境变量手动配置

分页

Fern 为分页提供异步迭代器,支持 for await。OpenAPI Generator 返回原始响应,需要手动游标跟踪。

功能FernOpenAPI Generator
异步迭代器内置 for await 支持
页面导航hasNextPage() / getNextPage() 方法手动游标跟踪
底层响应通过 page.response 访问直接返回值

Fern
1const pageableResponse = await client.plant.list();
2for await (const item of pageableResponse) {
3 console.log(item);
4}
5
6// 或手动迭代页面
7let page = await client.plant.list();
8while (page.hasNextPage()) {
9 page = await page.getNextPage();
10}
OpenAPI Generator
1let cursor: string | undefined;
2do {
3 const response = await plantApi.listPlants({ cursor });
4 for (const plant of response.plants) {
5 console.log(plant);
6 }
7 cursor = response.pagination?.nextCursor;
8} while (cursor);

错误处理

Fern 为特定的 HTTP 状态码生成类型化错误类。OpenAPI Generator 使用通用的 ResponseError 类。

功能FernOpenAPI Generator
类型化错误BadRequestErrorNotFoundErrorMethodNotAllowedError通用的 ResponseError
错误体解析并类型化需要手动解析
原始响应访问err.rawResponseerr.response

Fern
1try {
2 await client.plant.add({ name: "Fern", status: "available" });
3} catch (err) {
4 if (err instanceof PlantStore.BadRequestError) {
5 console.log("Invalid request:", err.body);
6 } else if (err instanceof PlantStore.NotFoundError) {
7 console.log("Plant not found");
8 } else if (err instanceof PlantStoreError) {
9 console.log("Status:", err.statusCode, "Body:", err.body);
10 }
11}
OpenAPI Generator
1try {
2 await plantApi.addPlant({ plant });
3} catch (err) {
4 if (err instanceof ResponseError) {
5 const body = await err.response.json();
6 if (err.response.status === 400) {
7 console.log("Invalid request:", body);
8 } else if (err.response.status === 404) {
9 console.log("Plant not found");
10 }
11 }
12}

弹性功能

Fern 包含带指数退避的自动重试、可配置超时和请求取消。OpenAPI Generator 需要自定义实现这些功能。

功能FernOpenAPI Generator
自动重试针对 408、429、5xx 的带抖动的指数退避
Retry-After 头自动遵守手动实现
可配置超时timeoutInSeconds 选项(默认 60s)
请求取消abortSignal 选项可通过 initOverrides 实现
最大重试次数可按请求或全局配置

Fern
1const response = await client.plant.add(
2 { name: "Fern", status: "available" },
3 {
4 maxRetries: 3,
5 timeoutInSeconds: 30,
6 abortSignal: controller.signal
7 }
8);

日志记录和可观测性

Fern 包含可配置的日志记录,自动编辑认证头、token 和 API 密钥。OpenAPI Generator 没有内置日志记录。

功能FernOpenAPI Generator
内置日志记录可配置级别(Debug/Info/Warn/Error)
自定义记录器可插拔(winston、pino 等)
敏感数据编辑自动处理认证头、token、API 密钥
请求/响应日志记录Debug 级别,带编辑的 URL手动实现

Fern
1const client = new PlantStoreClient({
2 clientId,
3 clientSecret,
4 logging: {
5 level: logging.LogLevel.Debug,
6 logger: new logging.ConsoleLogger(),
7 silent: false
8 }
9});

原始响应访问

Fern 提供 .withRawResponse() 方法来访问 HTTP 响应详细信息。OpenAPI Generator 使用单独的 *Raw() 方法。

功能FernOpenAPI Generator
访问模式使用 .withRawResponse() 的单一方法单独的 *Raw() 方法
头部访问rawResponse.headersresponse.raw.headers
响应体data 属性value() 方法

Fern
1const { data, rawResponse } = await client.plant.add({
2 name: "Fern",
3 status: "available"
4}).withRawResponse();
5
6console.log(rawResponse.headers);
OpenAPI Generator
1const response = await plantApi.addPlantRaw({ plant });
2const data = await response.value();
3console.log(response.raw.headers);

运行时兼容性和打包

Fern 支持多个 JavaScript 运行时,具有 ESM/CJS 双重构建和自动运行时检测。OpenAPI Generator 提供 ESM/CJS 支持。

功能FernOpenAPI Generator
Node.js18+支持
Denov1.25+不支持
Bun1.0+不支持
Cloudflare Workers支持不支持
React Native支持不支持
ESM/CJS 构建具有正确导出的双重构建基本的 ESM/CJS
子包导出可摇树优化的导入
运行时检测自动

测试和质量

Fern SDK 包含启用了代码检查的单元和线路测试。OpenAPI Generator 不包含测试。

功能FernOpenAPI Generator
单元测试
线路测试
代码检查Biome(启用)禁用(/* eslint-disable */
零依赖