Fern 定义中的类型 | Fern Documentation

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

内置类型

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

自定义类型

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

对象

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

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

1 types:
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 来组合对象：

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

您可以扩展多个对象：

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

别名

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

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

枚举

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

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

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

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

1 types:
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" 键来创建联合：

1 types:
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 }

非判别联合

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

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

泛型

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

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

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

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

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

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

为类型添加文档

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

Fern 定义

1 types:
2   Person:
3     docs: 一个人代表一个人类
4     properties:
5       name: string
6       age:
7         docs: 年龄（年）
8         type: integer

从 Fern 定义生成的 TypeScript SDK

1 /**
2  * 一个人代表一个人类
3  */
4 interface Person {
5   name: string;
6   // 年龄（年）
7   age: number;
8 }

验证类型

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

Fern 定义

1 types:
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

字符串验证参考

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

1 types:
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）支持多种验证约束。

1 types:
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 时，最小值为排他（值必须大于最小值）

exclusiveMax

boolean

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

multipleOf

number

值必须是此数字的倍数