hGEN

面向人类的API模式语言

[!警告]
此项目处于早期开发阶段，尚未准备好投入生产使用。

用法

可以使用hGEN CLI生成给定模式文件的代码。

$ cargo install hgen
$ hgen -i schema.hgen -o schema.ts

哲学

• 单一真相来源：确保您的API在所有服务和客户端之间保持一致是困难的。使用hGEN，您可以在一个地方定义和维护您的API，同时快速代码生成可以降低开销。

• 设计严格：如果模式语言不强制执行严格规则，那么它的意义何在？hGEN深受Rust类型系统的影响，确保您的API尽可能安全。

• 编译时反射：由于生成的代码文件不打算直接编辑，hGEN以易于使用且强类型化的反射元数据格式的形式提供这种功能，允许您在生成的代码上构建以实现自己的类型、验证、映射逻辑等。

• 可扩展元数据：其他模式或反射方法需要大量难看的注释，并且缺乏类型安全。这就是为什么hGEN的目标之一是提供一种可扩展的方式，直接在模式中定义元数据，允许您以类型安全的方式定义验证、序列化等，而不会影响模式的可读性。

模式语言

hGEN定义了自己的模式语言来描述API。这种语言深受TypeScript、Kotlin和Dart等语言的影响，使其易于学习和使用。然而，hGEN的原始类型基于Rust，推动更严格和安全的API设计。

extern alias Instant = String;

alias UUID = String & {
  type: uuid,
};

struct Todo {
  id: UUID,
  title: String,
  createdAt: Instant,
  checkedAt: Instant?,
}

struct CreateTodoParams {
  title: String,
}

service TodoService {
  create(params: CreateTodoParams) -> Todo,
  find() -> List<Todo>,
  check(id: UUID) -> Unit,
  uncheck(id: UUID) -> Unit,
}

参考

类型

• 原始类型

  • 结构体
  • 枚举
  • 布尔型
  • Int8、Int16、Int32、Int64、Int128
  • UInt8、UInt16、UInt32、UInt64、UInt128
  • Float32、Float64
  • 字符
  • 字符串
  • 可以为空
  • 单元
  • (T1, T2, ...,Tn)
  • 列表<T>
  • 映射<K, V>
  • 联合

• 概念

  • 类型别名
  • 自定义类型
  • 结果类型