典型：代数数据类型的互操作

典型 是一个 数据序列化 框架。您在一个名为 schema 的文件中定义数据类型，然后典型为各种语言生成高效的序列化和反序列化代码。生成的代码可以用于在服务之间打包消息、在磁盘上存储结构化数据等。紧凑的 二进制编码 支持不同版本 schema 之间的向前和向后兼容性，以适应不断变化的需求。

典型可以与 协议缓冲区 和 Apache Thrift 进行比较。主要区别在于典型有一个更现代的类型系统，它基于 代数数据类型，强调使用不可为空的类型和穷尽模式匹配的更安全的编程风格。如果您熟悉这种风格的编程语言，如 Rust 和 Haskell，您会感到很自在。典型提供了一种新的解决方案 (“非对称”字段) 来解决在 记录类型 中安全地添加或删除字段而不会破坏兼容性的经典问题。非对称字段的这一概念还解决了在 和类型 中添加或删除案例时如何保持兼容性的双重问题。

简而言之，典型提供了两个通常被认为相互矛盾的重要功能

1. 无妥协的类型安全
2. schema 版本之间的二进制兼容性

典型的设计受到了在谷歌使用协议缓冲区和在 Airbnb 使用 Apache Thrift 的经验的启发。这不是这两家公司的官方支持产品。如果您想支持典型，您可以通过 这里 做到。

支持的编程语言

以下语言目前得到支持

• Rust
• TypeScript
• JavaScript（通过 TypeScript）

教程

为了理解这一切，让我们通过一个示例场景进行说明。假设你想构建一个简单的API来发送电子邮件，并且你需要决定如何对请求和响应进行序列化。你可以使用JSON或XML这样的自描述格式，但你可能想要更好的类型安全和性能。Typical在这方面有很多话要说。

尽管我们的示例场景涉及客户端与服务器通信，但Typical没有客户端或服务器的概念。它只处理序列化和反序列化。网络、加密和认证等其他问题超出了Typical的范畴。

步骤 1：编写一个模式

你可以从创建一个名为 types.t （或任何你喜欢的其他名称）的模式文件开始，其中包含你的API的一些类型

struct SendEmailRequest {
    to: String = 0
    subject: String = 1
    body: String = 2
}

choice SendEmailResponse {
    success = 0
    error: String = 1
}

此模式定义了两种类型：SendEmailRequest 和 SendEmailResponse。第一种类型是 结构体，这意味着它描述了包含一组固定字段的消息（在这种情况下，to、subject 和 body）。第二种类型是 联合体，这意味着它描述了包含从一组固定可能性中恰好一个字段的邮件（在这种情况下，success 和 error）。结构体和联合体被称为 代数数据类型，因为它们可以抽象地理解为类型乘法和加法，但你不需要了解这些就可以使用Typical。

每个字段都有一个名称（例如，body）和一个整数索引（例如，2）。名称仅用于人类，因为只使用索引来识别二进制编码中的字段。只要不更改索引，你可以自由地重命名字段而不用担心二进制不兼容。

每个字段还有一个类型（例如，String）。如果类型缺失，就像上面提到的 success 字段一样，则默认为内置类型 Unit。Unit 类型不包含任何信息，编码时占用零字节。

一旦你编写了你的模式，Typical可以对其进行格式化，以确保一致的语法定义，如缩进、字母大小写等。以下命令将执行此操作，尽管由于我们的示例已经正确格式化，它不会产生任何影响

typical format types.t

步骤 2：生成序列化和反序列化代码

现在我们已经定义了一些类型，我们可以使用Typical来生成序列化和反序列化代码。例如，你可以使用以下命令生成Rust和TypeScript代码：

typical generate types.t --rust types.rs --typescript types.ts

有关如何自动化的说明，请参考示例项目。总之

• 对于Rust，你可以使用一个Cargo构建脚本，当调用 cargo build 时执行。
• 对于TypeScript，你可以使用你的 package.json 中的 scripts 属性。

使用Typical不需要设置自动构建系统，但我们推荐这样做以提高便利性。

步骤 3：序列化和反序列化消息

在前一节生成的代码基础上，让我们编写一个简单的Rust程序来序列化一条消息。我们可以将消息写入内存缓冲区、套接字，或者任何实现了std::io::Write的任何东西。在这个例子中，我们将数据流式传输到文件。

let message = SendEmailRequestOut {
    to: "[email protected]".to_owned(),
    subject: "I love Typical!".to_owned(),
    body: "It makes serialization easy and safe.".to_owned(),
};

let mut file = BufWriter::new(File::create(REQUEST_FILE_PATH)?);
message.serialize(&mut file)?;
file.flush()?;

另一个程序可以按如下方式读取文件并反序列化消息

let file = BufReader::new(File::open(FILE_PATH)?);
let message = SendEmailRequestIn::deserialize(file)?;

println!("to: {}", message.to);
println!("subject: {}", message.subject);
println!("body: {}", message.body);

本例的完整代码可以在这里找到。TypeScript版本在这里。

在下一节中，我们将看到为什么我们的SendEmailRequest类型变成了SendEmailRequestOut和SendEmailRequestIn。

必填、可选和非对称字段

字段默认是必填的。这是一个不寻常的设计决策，因为通常认为必填字段会在架构版本之间的前后兼容性中引起麻烦。让我们详细探讨这个主题，并看看Typical是如何处理它的。

添加或删除必填字段是危险的

经验告诉我们，向已经使用的类型中引入必填字段可能会有困难。例如，假设你的电子邮件API正在运行，你想要在请求类型中添加一个新的from字段

struct SendEmailRequest {
    to: String = 0

    # A new required field
    from: String = 3

    subject: String = 1
    body: String = 2
}

实施这个变更的唯一安全方式（按照这种方式编写）是在开始更新任何服务器之前完成所有客户端的更新。否则，仍在运行旧代码的客户端可能会向更新后的服务器发送请求，服务器会立即拒绝该请求，因为它缺少新字段。

这种部署可能不可行。你可能无法控制客户端和服务器更新的顺序。或者，也许客户端和服务器是一起更新的，但不是原子的。客户端和服务器甚至可能是同一个复制服务的一部分，因此无论你多么小心，都无法先更新一个再更新另一个。

删除必填字段可能会遇到类似的问题。假设，尽管存在上述挑战，你成功地将from引入为必填字段。现在，另一个相关问题迫使你回滚。这就像最初添加它一样危险：如果客户端在服务器之前更新，那么该客户端可能会发送一个没有from字段的请求，服务器会拒绝该请求，因为它仍然期望该字段存在。

将可选字段提升为必填或反之亦然是危险的

引入必填字段的一种稍微安全的方法是首先将其引入为可选的，然后将其提升为必填。例如，你可以安全地引入这个变更

struct SendEmailRequest {
    to: String = 0

    # A new optional field
    optional from: String = 3

    subject: String = 1
    body: String = 2
}

然后更新客户端以设置新字段。一旦你确信新字段总是被设置，你就可以将其提升为必填。

问题在于，只要字段是可选的，你就不能依赖类型系统来确保新字段总是被设置。即使你确信你已适当地更新了客户端代码，你的队友可能在你有机会将其提升为必填之前，可能会引入一个新实例的字段未被设置。

当你将必填字段降级为可选时，也可能会遇到类似的问题。一旦字段已被降级，客户端可能会在服务器能够处理其缺失之前停止设置该字段，除非你能确保服务器首先更新。

使所有字段都可选既不舒适也不安全

由于必填字段相关的问题，传统观点是根本不用它们；所有字段都应该声明为可选。例如

struct SendEmailRequest {
    optional to: String = 0
    optional subject: String = 1
    optional body: String = 2
}

然而，这种建议忽略了这样一个现实：有些事物在语义上确实是必需的，即使根据模式它们不是必需的。如果没有它所需的数据，API无法正常工作。将语义上必需的字段声明为可选，给作者和读者都带来了额外的负担：作者不能依赖类型系统来防止他们不小心忘记设置字段，而读者必须处理字段缺失的情况，以满足类型检查器，尽管这些字段始终应该是设置的。

不对称的字段可以安全地提升为必需，反之亦然

为了帮助您安全地添加和删除必需字段，Typical提供了一个介于可选和必需之间的中间状态：不对称。结构体中的不对称字段对于作者来说是必需的，但对于读者来说是可选的。与可选字段不同，不对称字段可以安全地提升为必需，反之亦然。

让我们用一个电子邮件API示例来具体说明这一点。我们不是直接将from字段作为必需字段引入，而是首先将其作为不对称字段引入

struct SendEmailRequest {
    to: String = 0

    # A new asymmetric field
    asymmetric from: String = 3

    subject: String = 1
    body: String = 2
}

让我们看看这个模式的生成代码；我们将使用Rust作为示例。生成的代码有两种版本的我们的SendEmailRequest类型，一个是用于序列化，另一个是用于反序列化

pub struct SendEmailRequestOut {
    pub to: String,
    pub from: String,
    pub subject: String,
    pub body: String,
}

pub struct SendEmailRequestIn {
    pub to: String,
    pub from: Option<String>,
    pub subject: String,
    pub body: String,
}

impl Serialize for SendEmailRequestOut {
    // Serialization code omitted.
}

impl Deserialize for SendEmailRequestIn {
    // Deserialization code omitted.
}

我们可以看到from作为一个不对称字段的影响：在SendEmailRequestOut中，其类型是String，但在SendEmailRequestIn中，其类型是Option<String>。这意味着客户端（使用SendEmailRequestOut）现在必须设置新字段，但服务器（使用SendEmailRequestIn）还不允许依赖它。一旦这个变更已经推出（至少针对客户端），我们就可以在后续变更中安全地将字段提升为必需。

fn handle_response(response: SendEmailResponseIn) {
    match response {
        Success => println!("The email was sent!"),
        Error(message) => println!("An error occurred: {message}"),
    }
}

choice SendEmailResponse {
    success = 0
    error: String = 1

    # A more specific type of error for curious clients
    optional authentication_error: String = 2

    # To be promoted to required in the future
    asymmetric please_try_again = 3
}

pub enum SendEmailResponseOut {
    Success,
    Error(String),
    AuthenticationError(String, Box<SendEmailResponseOut>),
    PleaseTryAgain(Box<SendEmailResponseOut>),
}

pub enum SendEmailResponseIn {
    Success,
    Error(String),
    AuthenticationError(String, Box<SendEmailResponseIn>),
    PleaseTryAgain,
}

impl Serialize for SendEmailResponseOut {
    // Serialization code omitted.
}

impl Deserialize for SendEmailResponseIn {
    // Deserialization code omitted.
}

struct Address {
    local_part: String = 0
    domain: String = 1
}

import 'email_util.t'

struct SendEmailRequest {
    to: email_util.Address = 0
    subject: String = 1
    body: String = 2
}

import 'apis/email.t'
import 'util/email.t'

struct Employee {
    name: String = 0

    # Uh oh! Which schema is this type from?
    email: email.Address = 1
}

import 'apis/email.t' as email_api
import 'util/email.t' as email_util

struct Employee {
    name: String = 0
    email: email_util.Address = 1
}

import 'apis/email.t'
import 'net/ip.t'

choice DeviceIpAddress {
    static_v4: ip.V4Address = 0
    static_v6: ip.V6Address = 1
    dynamic = 2
}

struct Device {
    hostname: String = 0
    asymmetric ip_address: DeviceIpAddress = 1
    optional owner: email.Address = 2
}

choice Weekday {
    monday = 0
    tuesday = 1
    wednesday = 2
    thursday = 3
    friday = 4
}

struct Device {
    hostname: String = 0

    deleted 1 2
}

# This file contains types relating to a hypothetical email sending API.

# A request to send an email
struct SendEmailRequest {
    # To whom the email is addressed
    to: String = 0

    # The subject line of the email
    subject: String = 1

    # The contents of the email
    body: String = 2
}

# The result of attempting to send an email
choice SendEmailResponse {
    # The email was delivered
    success = 0

    # There was a problem sending the email
    error: String = 1
}

typical generate types.t --rust types.rs --typescript types.ts

USAGE:
    typical <SUBCOMMAND>

OPTIONS:
    -h, --help
            Prints help information

    -v, --version
            Prints version information


SUBCOMMANDS:
    format
            Formats a schema and its transitive dependencies

    generate
            Generates code for a schema and its transitive dependencies

    help
            Prints this message or the help of the given subcommand(s)

    shell-completion
            Prints a shell completion script. Supports Zsh, Fish, Zsh, PowerShell, and Elvish.

USAGE:
    typical generate [FLAGS] [OPTIONS] <SCHEMA_PATH>

FLAGS:
    -h, --help            Prints help information
        --list-schemas    Lists the schemas imported by the given schema (and the given schema
                          itself)

OPTIONS:
        --rust <PATH>          Sets the path of the Rust file to emit
        --typescript <PATH>    Sets the path of the TypeScript file to emit

ARGS:
    <SCHEMA_PATH>    Sets the path of the schema

curl https://raw.githubusercontent.com/stepchowfun/typical/main/install.sh -LSfs | sh

curl https://raw.githubusercontent.com/stepchowfun/typical/main/install.sh -LSfs | PREFIX=. sh

brew install typical

cargo install typical