utils 系列包

utils 系列包包含：

  1. api 包，用于读取项目源码，并生成与 API 有关的所有数据结构，产出的结构可用于生成文档和客户端。
  2. builder 包，利用 api 包读取源码并生成 API 数据。
  3. generators/golang 包，利用 api 包提供的数据结构生成 golang 客户端。
  4. generators/swagger 包，利用 api 包提供的数据结构生成 API 文档。
  5. generators/utils 包，提供公共工具给其他生成器使用。
  6. printer 包，提供了一个在 Terminal 中打印表格的功能。
  7. project 包，提供了基础工具用于读取项目配置文件，通常是 nirvana.yaml。

除了 printer 包以外，其他包都是用于生成文档和客户端用的。

在 api 包中，提供了如下功能：

  1. 对应 golang type 的 Type
    为了能让 golang type 能转换为可读的数据结构，构建了 Type 相关类型：

    1. // TypeName is unique name for go types.
    2. type TypeName string
    4. // TypeNameInvalid indicates an invalid type name.
    5. const TypeNameInvalid = ""
    7. // StructField describes a field of a struct.
    8. type StructField struct {
    9.    // Name is the field name.
    10.    Name string
    11.    // Comments of the type.
    12.    Comments string
    13.    // PkgPath is the package path that qualifies a lower case (unexported)
    14.    // field name. It is empty for upper case (exported) field names.
    15.    PkgPath string
    16.    // Type is field type name.
    17.    Type TypeName
    18.    // Tag is field tag.
    19.    Tag reflect.StructTag
    20.    // Offset within struct, in bytes.
    21.    Offset uintptr
    22.    // Index sequence for Type.FieldByIndex.
    23.    Index []int
    24.    // Anonymous shows whether the field is an embedded field.
    25.    Anonymous bool
    26. }
    28. // FuncField describes a field of function.
    29. type FuncField struct {
    30.    // Name is the field name.
    31.    Name string
    32.    // Type is field type name.
    33.    Type TypeName
    34. }
    36. // Type describes an go type.
    37. type Type struct {
    38.    // Name is short type name.
    39.    Name string
    40.    // Comments of the type.
    41.    Comments string
    42.    // PkgPath is the package for this type.
    43.    PkgPath string
    44.    // Kind is type kind.
    45.    Kind reflect.Kind
    46.    // Key is map key type. Only used in map.
    47.    Key TypeName
    48.    // Elem is the element type of map, slice, array, pointer.
    49.    Elem TypeName
    50.    // Fields contains all struct fields of a struct.
    51.    Fields []StructField
    52.    // In presents fields of function input parameters.
    53.    In []FuncField
    54.    // Out presents fields of function output results.
    55.    Out []FuncField
    56.    // Conflict identifies the index of current type in a list of
    57.    // types which have same type names. In most cases, this field is 0.
    58.    Conflict int
    59. }

  2. 对应 Nirvana API 的 Definition
    此处的 Definition 大部分字段与 definition 包中的相同，之所以不复用之前的结构，是因为有部分类型相关的字段稍有不同。

    1. // Parameter describes a function parameter.
    2. type Parameter struct {
    3.    // Source is the parameter value generated from.
    4.    Source definition.Source
    5.    // Name is the name to get value from a request.
    6.    Name string
    7.    // Description describes the parameter.
    8.    Description string
    9.    // Type is parameter object type.
    10.    Type TypeName
    11.    // Default is encoded default value.
    12.    Default []byte
    13. }
    15. // Result describes a function result.
    16. type Result struct {
    17.    // Destination is the target for the result.
    18.    Destination definition.Destination
    19.    // Description describes the result.
    20.    Description string
    21.    // Type is result object type.
    22.    Type TypeName
    23. }
    25. // Example is just an example.
    26. type Example struct {
    27.    // Description describes the example.
    28.    Description string
    29.    // Type is result object type.
    30.    Type TypeName
    31.    // Instance is encoded instance data.
    32.    Instance []byte
    33. }
    35. // Definition is complete version of def.Definition.
    36. type Definition struct {
    37.    // Method is definition method.
    38.    Method definition.Method
    39.    // HTTPMethod is http method.
    40.    HTTPMethod string
    41.    // HTTPCode is http success code.
    42.    HTTPCode int
    43.    // Summary is a brief of this definition.
    44.    Summary string
    45.    // Description describes the API handler.
    46.    Description string
    47.    // Consumes indicates how many content types the handler can consume.
    48.    // It will override parent descriptor's consumes.
    49.    Consumes []string
    50.    // Produces indicates how many content types the handler can produce.
    51.    // It will override parent descriptor's produces.
    52.    Produces []string
    53.    // ErrorProduces is used to generate data for error. If this field is empty,
    54.    // it means that this field equals to Produces.
    55.    // In some cases, succeessful data and error data should be generated in
    56.    // different ways.
    57.    ErrorProduces []string
    58.    // Function is a function handler. It must be func type.
    59.    Function TypeName
    60.    // Parameters describes function parameters.
    61.    Parameters []Parameter
    62.    // Results describes function retrun values.
    63.    Results []Result
    64.    // Examples contains many examples for the API handler.
    65.    Examples []Example
    66. }

  3. 用于表示代码注释的 Comments
    在源码解析的时候，通常需要通过注释实现一些特殊功能，因此要对注释进行分析。目前注释特殊格式是 +nirvana:api=option:"value"。

    1. const (
    2.    // CommentsOptionDescriptors is the option name of descriptors.
    3.    CommentsOptionDescriptors = "descriptors"
    4.    // CommentsOptionModifiers is the option name of modifiers.
    5.    CommentsOptionModifiers = "modifiers"
    6.    // CommentsOptionAlias is the option name of alias.
    7.    CommentsOptionAlias = "alias"
    8.    // CommentsOptionOrigin is the option name of original name.
    9.    CommentsOptionOrigin = "origin"
    10. )
    12. // Comments is parsed from go comments.
    13. type Comments struct {
    14.    lines   []string
    15.    options map[string][]string
    16. }
    18. var optionsRegexp = regexp.MustCompile(`^[ \t]*\+nirvana:api[ \t]*=(.*)$`)
    19. var options = []string{CommentsOptionDescriptors, CommentsOptionModifiers, CommentsOptionAlias}
    21. // ParseComments parses comments and extracts nirvana options.
    22. func ParseComments(comments string) *Comments

  4. 用于分析源码的 Analyzer
    Analyzer 可以读取源码，获取结构对象和注释信息。

    1. // Analyzer analyzes go packages.
    2. type Analyzer struct {
    3.    ...
    4. }
    6. // NewAnalyzer creates a code ananlyzer.
    7. func NewAnalyzer(root string) *Analyzer
    9. // Import imports a package and all packages it depends on.
    10. func (a *Analyzer) Import(path string) (*types.Package, error)
    12. // PackageComments returns comments above package keyword.
    13. // Import package before calling this method.
    14. func (a *Analyzer) PackageComments(path string) []*ast.CommentGroup
    16. // Packages returns packages under specified directory (including itself).
    17. // Import package before calling this method.
    18. func (a *Analyzer) Packages(parent string, vendor bool) []string
    20. // FindPackages returns packages which contain target.
    21. // Import package before calling this method.
    22. func (a *Analyzer) FindPackages(target string) []string
    24. // Comments returns immediate comments above pos.
    25. // Import package before calling this method.
    26. func (a *Analyzer) Comments(pos token.Pos) *ast.CommentGroup
    28. // ObjectOf returns declaration object of target.
    29. func (a *Analyzer) ObjectOf(pkg, name string) (types.Object, error)

  5. 集合上述所有功能的 Container
    Container 读取源码并进行分析，产出 API 相关的所有定义和类型信息。API 定义和类型信息可以用来生成 API 文档和客户端。

    1. // Definitions describes all APIs and its related object types.
    2. type Definitions struct {
    3.    // Definitions holds mappings between path and API descriptions.
    4.    Definitions map[string][]Definition
    5.    // Types contains all types used by definitions.
    6.    Types map[TypeName]*Type
    7. }
    9. // Container contains informations to generate APIs.
    10. type Container struct {
    11.    ...
    12. }
    14. // NewContainer creates API container.
    15. func NewContainer(root string) *Container
    17. // AddModifier add definition modifiers to container.
    18. func (ac *Container) AddModifier(modifiers ...service.DefinitionModifier)
    20. // AddDescriptor add descriptors to container.
    21. func (ac *Container) AddDescriptor(descriptors ...definition.Descriptor)
    23. // Generate generates API definitions.
    24. func (ac *Container) Generate() (*Definitions, error)

builder 包相对 api 包来说就简单很多了，这个包里包含一个 API Builder：

  1. // APIBuilder builds api definitions by specified package.
  2. type APIBuilder struct {
  3.     ...
  4. }
  6. // NewAPIBuilder creates an api builder.
  7. func NewAPIBuilder(root string, paths ...string) *APIBuilder
  9. // Build build api definitions.
  10. func (b *APIBuilder) Build() (*api.Definitions, error)

API Builder 首先会利用 Analyzer 去读取指定路径的源码，然后从中找到标记了 modifiers 和 descriptors 选项的注释。两个选项的值对应两个函数，分别返回 Modifier 和 Descriptor。然后动态生成一个 main.go 文件 import 这两个函数对应包，然后调用这两个函数，取得返回值。得到返回值之后则利用 api 包的 Container 来生成 API 定义和类型信息。API Builder 执行 main.go 后通过 stdout 取得返回值，反序列化成 Definitions 结构，然后再返回给 API Builder 的调用者。这样就完成了对一个项目的 API 信息的提取。

golang 包和 swagger 包实际上都是利用了 API Builder 的返回结果，构建出相应的客户端和文档。golang 包会为每一个 API 生成一个客户端函数，这个函数的结构和服务读基本一致。函数体的实现则是直接使用了 rest 包 Client 接口。swagger 包则是利用了 github.com/go-openapi/spec 将 API 定义和类型转换成了 openapi 的定义。