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" 键来创建对象：

1types:
2  Person:
3    properties:
4      name: string
5      address: Address
6
7  Address:
8    properties:
9      line1: string
10      line2: optional<string>
11      city: string
12      state: string
13      zip: string
14      country: literal<"USA">

这些表示 JSON 对象：

1{
2  "name": "Alice",
3  "address": {
4    "line1": "123 Happy Lane",
5    "city": "New York",
6    "state": "NY",
7    "zip": "10001",
8    "country": "USA"
9  }
10}

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

1types:
2  Pet:
3    properties:
4      name: string
5  Dog:
6    extends: Pet
7    properties:
8      breed: string

您可以扩展多个对象：

1types:
2  GoldenRetriever:
3    extends:
4      - Dog
5      - Pet
6    properties:
7      isGoodBoy: boolean

别名

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

1types:
2  # UserId 是 string 的别名
3  UserId: string
4
5  User:
6    properties:
7      id: UserId
8      name: string

枚举

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

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

1types:
2  WeatherReport:
3    enum:
4      - SUNNY
5      - CLOUDY
6      - RAINING
7      - SNOWING

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

1types:
2  Operator:
3    enum:
4      - name: LESS_THAN # <--- 将在 SDK 中使用的名称
5        value: '<' # <--- 将被序列化的值
6      - name: GREATER_THAN
7        value: '>'
8      - name: NOT_EQUAL
9        value: '!='

判别联合

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

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

1types:
2  Animal:
3    union:
4      dog: Dog
5      cat: Cat
6  Dog:
7    properties:
8      likesToWoof: boolean
9  Cat:
10    properties:
11      likesToMeow: boolean

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

1{
2  "type": "dog",
3  "likesToWoof": true
4}

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

1 types:
2   Animal:
3     discriminant: animalType
4     union:
5       dog: Dog
6       cat: Cat
7   Dog:
8     properties:
9       likesToWoof: boolean
10   Cat:
11     properties:
12       likesToMeow: boolean

这对应于如下的 JSON 对象：

1{
2  "animalType": "dog",
3  "likesToWoof": true
4}

无判别联合

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

1MyUnion:
2  discriminated: false
3  union:
4    - string
5    - integer

泛型

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

1MySpecialMapItem<Key, Value>:
2  properties:
3    key: Key, 
4    value: Value,
5    diagnostics: string

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

1StringIntegerMapItem:
2  type: Response<string, number>
3
4StringStringMapItem:
5  type: Response<string, string>

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

1type StringIntegerMapItem = {
2  key: string,
3  value: number,
4  diagnostics: string
5}   
6 
7type StringStringMapItem = {
8  key: string,
9  value: string,
10  diagnostics: string
11}

文档化类型

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

Fern Definition
1types:
2  Person:
3    docs: 一个人代表一个人类
4    properties:
5      name: string
6      age:
7        docs: 年龄（以年为单位）
8        type: integer
Generated TypeScript SDK from Fern Definition
1/**
2 * 一个人代表一个人类
3 */
4interface Person {
5  name: string;
6  // 年龄（以年为单位）
7  age: number;
8}

验证类型

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

Fern Definition
1types:
2  Person:
3    docs: 一个人代表一个人类
4    properties:
5      name:
6        docs: 该人的全名
7        type: string
8        validation:
9          minLength: 2
10          maxLength: 100
11          pattern: "^[A-Za-z ]+$"
12      age:
13        docs: 年龄（以年为单位）
14        type: integer
15        validation:
16          min: 0
17          max: 150

字符串类型支持几个验证约束。

1types:
2  Word:
3    type: string
4    validation:
5      minLength: 2
6      maxLength: 26
7  User:
8    properties:
9      email:
10        type: string
11        validation:
12          format: email
13          maxLength: 254
14      username:
15        type: string
16        validation:
17          minLength: 3
18          maxLength: 20
19          pattern: "^[a-zA-Z0-9_]+$"
minLength
integer

所需的最小字符数

maxLength
integer

允许的最大字符数

pattern
string

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

format
string

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

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

1types:
2  Age:
3    type: integer
4    validation:
5      min: 0
6      max: 150
7  Product:
8    properties:
9      name: string
10      price:
11        type: double
12        validation:
13          min: 0
14          exclusiveMin: true
15          multipleOf: 0.01
16      quantity:
17        type: integer
18        validation:
19          min: 1
20          max: 1000
min
number

最小值（默认包含）

max
number

最大值（默认包含）

exclusiveMin
boolean

为 true 时，最小值为独占（值必须大于 min）

exclusiveMax
boolean

为 true 时，最大值为独占（值必须小于 max）

multipleOf
number

值必须是此数字的倍数