Golang类型检查与TypeScript声明导出插件库typex的使用

typex是一个用于检查Go类型及其传递性依赖关系的工具，可以将结果导出为TypeScript值对象或类型的声明。

安装

go install github.com/dtgorski/typex@latest

简介

CLI命令typex可以过滤和显示Go类型结构、接口及其跨包边界的关联关系。它会生成一个类型层次结构树，并包含对过滤类型至关重要的传递性依赖的额外引用。作为附加功能，typex可以将结果树导出为TypeScript的投影，表示值对象或纯类型。

示例

Go类型层次结构布局

$ typex -f=Rune io/...

├── error interface {
│       Error() string
│   }
└── io
    ├── RuneReader interface {
    │       ReadRune() (r rune, size int, err error)
    │   }
    └── RuneScanner interface {
            io.RuneReader
            ReadRune() (r rune, size int, err error)
            UnreadRune() error
        }

$ typex -f=Render github.com/dtgorski/typex/...

└── github.com
    └── dtgorski
        └── typex
            └── internal
                ├── PathReplaceFunc func(string) string
                ├── go
                │   └── TypeRender struct {
                │           PathReplaceFunc internal.PathReplaceFunc
                │           IncludeUnexported bool
                │       }
                └── ts
                    └── TypeRender struct {
                            PathReplaceFunc internal.PathReplaceFunc
                            IncludeUnexported bool
                        }

TypeScript值对象布局

$ typex -f=File -l=ts-class mime/multipart

export module mime {
    export module multipart {
        export class FileHeader {
            constructor(
                readonly Filename: string,
                readonly Header: net.textproto.MIMEHeader,
                readonly Size: number,
            ) {}
        }
    }
}
export module net {
    export module textproto {
        export type MIMEHeader = Record<string, string[]>
    }
}

TypeScript纯类型布局

$ typex -f=File -l=ts-type mime/multipart

export module mime {
    export module multipart {
        export type FileHeader = {
            Filename: string,
            Header: net.textproto.MIMEHeader,
            Size: number,
        }
    }
}
export module net {
    export module textproto {
        export type MIMEHeader = Record<string, string[]>
    }
}

TypeScript与保留关键字

基本上，类型和字段的名称将从Go导出而不做修改。可能会与目标语言中的保留关键字或标准类型名称发生冲突。为避免冲突，您可以使用结构导出字段的JSON标签注释。

TypeScript与可导出类型

由于基本语言差异，typex无法将所有类型声明一对一导出。请参考下面的类型映射表。Go的通道、接口和函数声明将被省略，对这些类型的引用将使用any类型。

TypeScript类型映射

TypeScript(即JavaScript或ECMAScript)缺乏原生整数类型。那里提供的数字类型本质上是一个64位浮点数。在处理导出的数字类型时应该记住这一点，这包括byte和rune类型别名。

使用

$ typex -h

Usage: typex [options] package...
Examine Go types and their transitive dependencies. Export
results as TypeScript value objects (or types) declaration.

Options:
    -f <name>
        Type name filter expression. Repeating the -f option
        is allowed, all expressions aggregate to an OR query.

        The <name> filter can be a type name, a path part or
        a regular expression. Especially in the latter case,
        <name> should be quoted or escaped correctly to avoid
        errors during shell interpolation. Filters are case
        sensitive, see examples below.

        The result tree will contain additional references to
        transitive dependencies vital for the filtered types.

    -l <layout>
        Modify the export layout. Available layouts are:
          * "go":       the default Go type dependency tree
          * "ts-type":  TypeScript type declaration projection
          * "ts-class": TypeScript value object projection

    -r <old-path>:<new-path>
        Replace matching portions of <old-path> in a fully
        qualified type name with <new-path> string. Repeating
        the -r option is allowed, substitutions will perform
        successively. <old-path> can be a regular expression.
        
        The path replacement/relocation can be used to modify
        locations of type hierarchies, e.g. prune off the
        "github.com" reference from qualified type name path
        by omitting the <new-path> part after the colon. 

    -t  Go tests (files suffixed _test.go) will be included
        in the result tree available for a filter expression

    -u  Unexported types (lowercase names) will be included
        in the result tree available for a filter expression.

    -x <name> 
        Exclude type names from export. Repeating this option
        is allowed, all expressions aggregate to an OR query.
        The exclusion filter can be a type name, a path part
        or a regular expression.

More options:
    -h  Display this usage help and exit.
    -v  Print program version and exit.

The 'package' argument denotes one or more package import path
patterns to be inspected. Patterns must be separated by space.
A pattern containing '...' specifies the active modules whose
modules paths match the pattern.

Examples:
    $ typex -u go/...
    $ typex -u -f=URL net/url
    $ typex github.com/your/repository/...
    $ typex -l=ts-type github.com/your/repository/...
    $ typex -r=github.com:a/b/c github.com/your/repository/...

This tool relies heavily on Go's package managing subsystem and
is bound to its features and environmental execution context.

已知问题

• 在Go 1.14.6 darwin/amd64上偶尔(?)会从Go的包管理子系统中报告internal error。更新的Go版本>=1.15似乎不受影响。

免责声明

typex的实现和功能遵循YAGNI原则。不保证完整性和可靠性。

@dev

尝试make:

$ make

 make help       Displays this list
 make clean      Removes build/test artifacts
 make build      Builds a static binary to ./bin/typex
 make debug      Starts debugger [:2345] with ./bin/typex
 make install    Compiles and installs typex in Go environment
 make test       Runs tests, reports coverage
 make tidy       Formats source files, cleans go.mod
 make sniff      Checks format and runs linter (void on success)

许可证

MIT - © dtg [at] lengo [dot] org