跳到导航
Fern 定义

Fern 定义中的类型

以 Markdown 格式查看

类型描述了 API 的数据模型。

内置类型

类型描述
string基本字符串类型
integer整数类型
long长整型
double双精度浮点数
boolean布尔值 true/false
datetimeRFC 3339, section 5.6 datetime 格式。例如：2017-07-21T17:32:28Z
dateRFC 3339, section 5.6 日期格式 (YYYY-MM-DD)。例如：2017-07-21
uuidUUID 标识符
base64Base64 编码的数据
list允许重复元素的有序集合，例如：list<string>
set包含唯一元素的无序集合，例如：set<string>
map键值映射，例如：map<string, integer>
optional可选值，例如：optional<string>
literal字面值，例如：literal<"Plants">
file文件上传类型，例如：文件上传
unknown表示任意 JSON

自定义类型

在 Fern 中创建自定义类型非常简单！

对象

最常见的自定义类型是对象。

在 Fern 中，您使用 "properties" 键来创建对象：

types:
  Person:
    properties:
      name: string
      address: Address
  Address:
    properties:
      line1: string
      line2: optional<string>
      city: string
      state: string
      zip: string
      country: literal<"USA">

这些表示 JSON 对象：

{
  "name": "Alice",
  "address": {
    "line1": "123 Happy Lane",
    "city": "New York",
    "state": "NY",
    "zip": "10001",
    "country": "USA"
  }
}

您还可以使用 extends 来组合对象：

types:
  Pet:
    properties:
      name: string
  Dog:
    extends: Pet
    properties:
      breed: string

您可以扩展多个对象：

types:
  GoldenRetriever:
    extends:
      - Dog
      - Pet
    properties:
      isGoodBoy: boolean

别名

别名类型是对现有类型的重命名。这通常是为了清晰起见。

types:
  # UserId 是 string 的别名
  UserId: string
  User:
    properties:
      id: UserId
      name: string

枚举

枚举表示具有一组允许值的字符串。

在 Fern 中，您使用 "enum" 键来创建枚举：

types:
  WeatherReport:
    enum:
      - SUNNY
      - CLOUDY
      - RAINING
      - SNOWING

枚举名称仅限于 A-Z、a-z、0-9 和 _，以确保生成的代码能够在 Fern 可以输出的所有语言中编译。如果您的枚举不遵循此约定，您可以使用 "name" 键来指定自定义名称：

types:
  Operator:
    enum:
      - name: LESS_THAN # <--- 将在 SDK 中使用的名称
        value: '<' # <--- 将被序列化的值
      - name: GREATER_THAN
        value: '>'
      - name: NOT_EQUAL
        value: '!='

判别联合

Fern 支持标记联合（也称为判别联合）。联合对于多态性很有用。这类似于 OpenAPI 中的 oneOf 概念。

在 Fern 中，您使用 "union" 键来创建联合：

types:
  Animal:
    union:
      dog: Dog
      cat: Cat
  Dog:
    properties:
      likesToWoof: boolean
  Cat:
    properties:
      likesToMeow: boolean

在 JSON 中，联合具有判别属性来区分联合的不同成员。默认情况下，Fern 使用 "type" 作为判别属性：

{
  "type": "dog",
  "likesToWoof": true
}

您可以使用 “discriminant” 键自定义判别属性：

 types:
   Animal:
     discriminant: animalType
     union:
       dog: Dog
       cat: Cat
   Dog:
     properties:
       likesToWoof: boolean
   Cat:
     properties:
       likesToMeow: boolean

这对应于这样的 JSON 对象：

{
  "animalType": "dog",
  "likesToWoof": true
}

非判别联合

非判别联合类似于判别联合，但是您不需要定义显式的判别属性。

MyUnion:
  discriminated: false
  union:
    - string
    - integer

泛型

Fern 支持浅层泛型对象，以最小化代码重复。您可以这样定义泛型以供重用：

MySpecialMapItem<Key, Value>:
  properties:
    key: Key, 
    value: Value,
    diagnostics: string

现在，您可以将泛型类型实例化为类型别名：

StringIntegerMapItem:
  type: Response<string, number>
StringStringMapItem:
  type: Response<string, string>

现在您可以像使用任何其他类型一样自由使用此类型！注意，生成的代码不会使用泛型。上面的示例将在 typescript 中生成为：

type StringIntegerMapItem = {
  key: string,
  value: number,
  diagnostics: string
}   
 
type StringStringMapItem = {
  key: string,
  value: string,
  diagnostics: string
}

为类型添加文档

您可以为类型添加文档。这些文档会传递给编译器，在生成的输出中非常有用（例如，SDK 中的文档字符串）。

Fern 定义
types:
  Person:
    docs: 一个人代表一个人类
    properties:
      name: string
      age:
        docs: 年龄（年）
        type: integer
从 Fern 定义生成的 TypeScript SDK
/**
 * 一个人代表一个人类
 */
interface Person {
  name: string;
  // 年龄（年）
  age: number;
}

验证类型

您可以为类型（别名和引用）添加验证约束，以确保数据完整性。这些验证约束存在于您的 API 定义中，并由服务器强制执行，但生成的客户端 SDK 不包含验证逻辑。

Fern 定义
types:
  Person:
    docs: 一个人代表一个人类
    properties:
      name:
        docs: 此人的全名
        type: string
        validation:
          minLength: 2
          maxLength: 100
          pattern: "^[A-Za-z ]+$"
      age:
        docs: 年龄（年）
        type: integer
        validation:
          min: 0
          max: 150

字符串类型支持多种验证约束。

types:
  Word:
    type: string
    validation:
      minLength: 2
      maxLength: 26
  User:
    properties:
      email:
        type: string
        validation:
          format: email
          maxLength: 254
      username:
        type: string
        validation:
          minLength: 3
          maxLength: 20
          pattern: "^[a-zA-Z0-9_]+$"
minLength
integer

所需的最小字符数

maxLength
integer

允许的最大字符数

pattern
string

字符串必须匹配的正则表达式模式

format
string

字符串格式规范（例如：“email”、“uri”、“date-time”）

数字类型（包括 integer、long 和 double）支持多种验证约束。

types:
  Age:
    type: integer
    validation:
      min: 0
      max: 150
  Product:
    properties:
      name: string
      price:
        type: double
        validation:
          min: 0
          exclusiveMin: true
          multipleOf: 0.01
      quantity:
        type: integer
        validation:
          min: 1
          max: 1000
min
number

最小值（默认为包含）

max
number

最大值（默认为包含）

exclusiveMin
boolean

当为 true 时，最小值为排他（值必须大于最小值）

exclusiveMax
boolean

当为 true 时，最大值为排他（值必须小于最大值）

multipleOf
number

值必须是此数字的倍数