tygo

tygo 项目介绍

项目概述

tygo 是一款工具，用于从 Golang（也是我们所熟知的 Go语言）源文件生成 Typescript 类型定义。这个工具运作流畅，只需简单操作便可实现类型定义的自动转换。它保留了注释信息，能够理解常量，并支持非结构体的 type 表达式。因此，tygo 是生成 Golang REST API 对应类型以在前端代码中使用的理想选择。值得一提的是，它支持 Golang 1.18 版本的泛型以及结构体继承。

安装

在命令行中执行以下命令即可安装 tygo：

go install github.com/gzuidhof/tygo@latest

使用示例

假设有一个 Golang 输入文件，其内容如下：

type UserRole = string
const (
    UserRoleDefault UserRole = "viewer"
    UserRoleEditor  UserRole = "editor"
)

type UserEntry struct {
    ID uuid.NullUUID `json:"id" tstype:"string | null"`
    Preferences map[string]struct {
        Foo uint32 `json:"foo"`
        Bar uuid.UUID `json:"bar"`
    } `json:"prefs"`
    Nickname string `json:"nickname,omitempty"`
    Role UserRole `json:"role"`
    unexported bool
}

通过 tygo 转换后，生成的 Typescript 输出如下：

export type UserRole = string;
export const UserRoleDefault: UserRole = "viewer";
export const UserRoleEditor: UserRole = "editor";

export interface UserEntry {
  id: string | null;
  prefs: {
    [key: string]: {
      foo: number;
      bar: any;
    };
  };
  nickname?: string;
  role: UserRole;
}

用法

选项A：命令行接口使用（推荐）

用户需要创建一个 tygo.yaml 文件，该文件用于指定待转换的包以及可能需要添加的特殊类型映射。然后，通过运行以下命令生成 Typescript 定义：

tygo generate

生成的 Typescript 文件会被放在 Go 源文件相同的目录中。

选项B：库模式使用

用户可以在 Go 代码中配置 tygo.Config，并调用 Generate 方法生成 Typescript 类型。

配置文件示例

packages:
  - path: "github.com/my/package"
    output_path: "webapp/api/types.ts"
    indent: "    "
    type_mappings:
      time.Time: "string"
      my.Type: "SomeType"
    frontmatter: |
      "import {SomeType} from "../lib/sometype.ts"
    exclude_files:
      - "private_stuff.go"
    extends: "SomeType"

类型提示及自定义映射

用户可以通过在结构体字段中使用 tstype 标签来指定其输出到 Typescript 文件中的类型。此外，还可以使用 tygo:emit 指令为无法直接用 Go 表示的类型生成对应的 Typescript 代码。

支持的特性

tygo 支持多种特性，包括字段的必需性和只读性、接口的继承、以及泛型等。用户可以通过 tstype 标签对指针类型字段进行标记以保证它们的必需性，或将字段设置为不可变，标记为只读字段等。

相关项目

tygo 项目与其他同类项目不同，它不依赖反射，因此能更好地保留代码中的注释和细节信息。其他类似项目如 typescriptify-golang-structs 和 go2ts 也各有优缺点，适合不同的使用场景。

许可证

tygo 项目采用 MIT 协议，用户可以自由使用和分发这个工具。

通过简单的配置和命令行操作，tygo 能够大大提高 Go 项目与 Typescript 项目间的数据交互效率，是开发人员的极佳辅助工具。