volo.yml 配置文件格式

功能

  1. 多个生产文件:支持不同协议和仓库版本冲突隔离
  2. 单文件去重:支持单个生成文件中的重复结构消除
  3. 灵活的生成代码配置:keep_unknown_fields、touch list、custom config、special_namings 等
  4. 跨库引用:在 repos 列表中给出跨仓库引用的仓库信息,即可支持跨库引用

yaml 格式

entries:
  {entry_name}: # entry_name = "default" by default
    filename: {filename} # filename = "volo_gen.rs" by default
    protocol: thrift | protobuf
    repos: # exist if non-local
        {repo}: # repo = extract the name from url by default
          url: {git} # url = repo git url
          ref: {ref} # ref = "HEAD" by default
          lock: {commit hash} # lock is the last commit hash
    services:
    - idl:
        source: git | local
        repo: {repo} # required for git source
        path: {path} # git path must be relative to the repo root dir
        includes: {includes list} # required for protobuf
      codegen_option:
        touch: [] #
        keep_unknown_fields: false # A->B->C, B could use this to transfer the unknown fields which is needed by A and C.
        config: {custom config}
    touch_all: false
    dedups: [] # remove the repeated structure generation in one entry
    special_namings: []

volo.yml 文件示例

entries:
  proto:
    filename: proto_gen.rs
    protocol: protobuf
    repos:
      protobuf:
        url: https://github.com/protocolbuffers/protobuf.git
        ref: HEAD
        lock: 704d0454ddc58da683e8cec22896ff3498089549
    services:
    - idl:
        source: local
        path: ../proto/echo.proto
        includes:
        - ../proto
    - idl:
        source: local
        path: ../proto/streaming.proto
        includes:
        - ../proto
    - idl:
        source: local
        path: ../proto/hello.proto
        includes:
        - ../proto
    - idl:
        source: git
        repo: protobuf
        path: examples/addressbook.proto
        includes:
        - examples
  thrift:
    filename: thrift_gen.rs
    protocol: thrift
    repos:
      thrift:
        url: https://github.com/apache/thrift.git
        ref: HEAD
        lock: 9bd1f1bee7bf59080492bbd3213ca1fed57ab4d6
    services:
    - idl:
        source: local
        path: ../thrift_idl/hello.thrift
    - idl:
        source: local
        path: ../thrift_idl/echo.thrift
    - idl:
        source: local
        path: ../thrift_idl/echo_unknown.thrift
      codegen_option:
        keep_unknown_fields: true
    - idl:
        source: git
        repo: thrift
        path: test/Service.thrift

volo-cli

  1. init

    1. $ volo init --help
      init your thrift or grpc project
      
      Usage: volo init [OPTIONS] <NAME> <IDL>
      
      Arguments:
        <NAME>  The name of project
        <IDL>   Specify the path for idl.
                If -g or --git is specified, then this should be the path in the specified git repo.
                Example: 	-g not specified:	./idl/server.thrift
                        -g specified:		/path/to/idl/server.thrift
      
      Options:
            --repo <REPO>          Specify the git repo name for repo.
                                   Example: cloudwego_volo
        -v, --verbose...           Turn on the verbose mode.
        -g, --git <GIT>            Specify the git repo for idl.
                                   Should be in the format of "git@domain:path/repo.git".
                                   Example: git@github.com:cloudwego/volo.git
        -r, --ref <REF>            Specify the git repo ref(branch) for idl.
                                   Example: main / $TAG
        -i, --includes <INCLUDES>  Specify the include dirs for idl.
                                   If -g or --git is specified, then this should be the path in the specified git repo.
        -h, --help                 Print help
        -V, --version              Print version
      
    2. 在项目根目录下使用 volo init 命令,会自动创建 server 代码模版和生成代码

  2. idl

    1. $ volo idl --help
      manage your idl
      
      Usage: volo idl [OPTIONS] <COMMAND>
      
      Commands:
        add
        help  Print this message or the help of the given subcommand(s)
      
      Options:
        -v, --verbose...               Turn on the verbose mode.
        -n, --entry-name <ENTRY_NAME>  The entry name, defaults to 'default'. [default: default]
        -h, --help                     Print help
        -V, --version                  Print version
      
    2. idl add

      1. $ volo idl add --help
        Usage: volo idl add [OPTIONS] <IDL>
        
        Arguments:
          <IDL>  Specify the path for idl.
                 If -g or --git is specified, then this should be the path in the specified git repo.
                 Example: 	-g not specified:	./idl/client.thrift
                       -g specified:		/path/to/idl/client.thrift
        
        Options:
              --repo <REPO>              Specify the git repo name for repo.
                                         Example: cloudwego_volo
          -v, --verbose...               Turn on the verbose mode.
          -g, --git <GIT>                Specify the git repo for idl.
                                         Should be in the format of "git@domain:path/repo.git".
                                         Example: git@github.com:cloudwego/volo.git
          -n, --entry-name <ENTRY_NAME>  The entry name, defaults to 'default'. [default: default]
          -r, --ref <REF>                Specify the git repo ref(branch) for idl.
                                         Example: main / $TAG
          -i, --includes <INCLUDES>      Specify the include dirs for idl.
                                         If -g or --git is specified, then this should be the path in the specified git repo.
          -f, --filename <FILENAME>      Specify the output filename, defaults to 'volo_gen.rs'. [default: volo_gen.rs]
          -h, --help                     Print help
          -V, --version                  Print version
        
    3. [deprecated] idl update -> repo update

  3. repo

    1. $ volo repo --help
      manage your repo
      
      Usage: volo repo [OPTIONS] <COMMAND>
      
      Commands:
        update  update your repo by repo name, split by ','
        add
        help    Print this message or the help of the given subcommand(s)
      
      Options:
        -v, --verbose...               Turn on the verbose mode.
        -n, --entry-name <ENTRY_NAME>  The entry name, defaults to 'default'. [default: default]
        -h, --help                     Print help
        -V, --version                  Print version
      
    2. repo add

      1. $ volo repo add --help
        Usage: volo repo add [OPTIONS] --git <GIT>
        
        Options:
              --repo <REPO>              Specify the git repo name for repo.
                                         Example: cloudwego_volo
          -v, --verbose...               Turn on the verbose mode.
          -g, --git <GIT>                Specify the git repo for idl.
                                         Should be in the format of "git@domain:path/repo.git".
                                         Example: git@github.com:cloudwego/volo.git
          -n, --entry-name <ENTRY_NAME>  The entry name, defaults to 'default'. [default: default]
          -r, --ref <REF>                Specify the git repo ref(branch) for idl.
                                         Example: main / $TAG
          -h, --help                     Print help
          -V, --version                  Print version
        
    3. Repo update

      1. $ volo repo update --help
        update your repo by repo name, split by ','
        
        Usage: volo repo update [OPTIONS] [REPOS]...
        
        Arguments:
          [REPOS]...
        
        Options:
          -v, --verbose...               Turn on the verbose mode.
          -n, --entry-name <ENTRY_NAME>  The entry name, defaults to 'default'. [default: default]
          -h, --help                     Print help
          -V, --version                  Print version
        

最后修改 April 7, 2024 : add repo (eec0cf5)