快速开始

Volo-gRPC 开发环境准备、快速上手与基础教程。

Part 1. 安装命令行工具

Volo 提供了同名的命令行工具,用来初始化项目、管理 IDL 等。

cargo install volo-cli

需要 rust 版本>= 1.75.0

随后,我们输入:

volo help

就能看到类似以下输出啦:

USAGE:
    volo [OPTIONS] <SUBCOMMAND>

OPTIONS:
    -h, --help       Print help information
    -n, --entry-name <ENTRY_NAME>    The entry name, defaults to 'default'. [default: default]
    -v, --verbose    Turn on the verbose mode.
    -V, --version    Print version information

SUBCOMMANDS:
    help    Print this message or the help of the given subcommand(s)
    idl     manage your idl
    init    init your project

Part 2. 创建一个 gRPC Server

Volo-gRPC 是一个 RPC 框架,既然是 RPC,底层就需要两大功能:

  1. Serialization 序列化
  2. Transport 传输

IDL 全称是 Interface Definition Language,接口定义语言。

2.1 Why IDL

如果我们要进行 RPC,就需要知道对方的接口是什么,需要传什么参数,同时也需要知道返回值是什么样的,就好比两个人之间交流,需要保证在说的是同一个语言、同一件事。 这时候,就需要通过 IDL 来约定双方的协议,就像在写代码的时候需要调用某个函数,我们需要知道函数签名一样。

Protobuf IDL 是一套跨语言的全栈式 RPC 解决方案,具体的语法可以看参考 protocol-buffers/docs/proto3

2.2 编写 IDL

为了创建一个 gRPC 项目,我们需要先编写一个 protobuf IDL。

在你的工作目录下,我们先执行以下命令:

mkdir volo-example && cd volo-example
mkdir idl && touch idl/volo_example.proto

随后,使用您喜欢的文本编辑器输入以下内容:

syntax = "proto3";
package volo.example;

message Item {
    int64 id = 1;
    string title = 2;
    string content = 3;

    map<string, string> extra = 10;
}

message GetItemRequest {
    int64 id = 1;
}

message GetItemResponse {
    Item item = 1;
}

service ItemService {
    rpc GetItem(GetItemRequest) returns (GetItemResponse);
}

保存退出后,我们执行以下命令:

volo init --includes=idl volo-example idl/volo_example.proto

这里我们使用init命令,后面跟了我们项目的名字,意思是需要生成模板代码。在末尾,需要指定一个 IDL 表示 server 使用的 IDL。

如果只需要增加一个 IDL(如 client 的 IDL)而不需要生成模板的话,如:

volo idl add idl/volo_example.proto

| 插播一个广告,volo 工具还支持从 git 下载 IDL 并生成代码哦,如:

volo idl add -g git@github.com:org/repo.git -r main /path/to/your/idl.proto

| 感兴趣可以直接输入 volo 看详细用法~ 接下来回到正题~

这时候,我们整个目录的结构如下:

.
├── Cargo.toml
├── idl
│   └── volo_example.proto
├── rust-toolchain.toml
├── src
│   ├── bin
│   │   └── server.rs
│   └── lib.rs
└── volo-gen
    ├── Cargo.toml
    ├── build.rs
    ├── src
    │   └── lib.rs
    └── volo.yml

然后,我们打开 src/lib.rs,在 impl 块中加入方法的实现,最终的代码应该是这样的:

pub struct S;

impl volo_gen::volo::example::ItemService for S {
    // 这部分是我们需要增加的代码
    async fn get_item(
        &self,
        _req: volo_grpc::Request<volo_gen::volo::example::GetItemRequest>,
    ) -> core::result::Result<volo_grpc::Response<volo_gen::volo::example::GetItemResponse>, volo_grpc::Status>
    {
        Ok(volo_grpc::Response::new(Default::default()))
    }
}

然后执行:

cargo update && cargo build

这时候,就会发现 OUT_DIR 目录下多出来一个 volo_gen.rs 的文件了。

然后执行以下命令,即可把我们的 server 端跑起来:

cargo run --bin server

至此,我们已经能把我们的 server 跑起来啦!

Part 3. 编写 Client 端

上一节中,我们编写完成了 server 端,现在让我们来编写我们的 client 端并调用我们的 server 端。

首先,创建一个文件 src/bin/client.rs,输入以下内容:

use lazy_static::lazy_static;
use std::net::SocketAddr;

lazy_static! {
    static ref CLIENT: volo_gen::volo::example::ItemServiceClient = {
        let addr: SocketAddr = "[::1]:8080".parse().unwrap();
        volo_gen::volo::example::ItemServiceClientBuilder::new("volo-example")
            .address(addr)
            .build()
    };
}

#[volo::main]
async fn main() {
    tracing_subscriber::fmt::init();
    let req = volo_gen::volo::example::GetItemRequest { id: 1024 };
    let resp = CLIENT.get_item(req).await;
    match resp {
        Ok(info) => tracing::info!("{:?}", info),
        Err(e) => tracing::error!("{:?}", e),
    }
}

然后,在 Cargo.toml 文件中加入所需的依赖,加入后的文件如下:

[package]
name = "volo-example"
version = "0.1.0"
edition = "2021"

# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html

[dependencies]
anyhow = "1"
async-trait = "0.1"
lazy_static = "1"
tokio = { version = "1", features = ["full"] }
tracing = "0.1"
prost = "0.11"
tracing-subscriber = "0.3"

pilota = "*"
volo =  "*"        # we recommend to use the latest framework version for new features and bug fixes
volo-grpc =  "*"  # we recommend to use the latest framework version for new features and bug fixes

volo-gen = { path = "./volo-gen" }

[profile.release]
opt-level = 3
debug = true
debug-assertions = false
overflow-checks = false
lto = true
panic = 'unwind'
incremental = false
codegen-units = 1
rpath = false

[workspace]
members = ["volo-gen"]
resolver = "2"

接着,新建一个 terminal,执行以下命令,把我们的 server 端跑起来:

cargo run --bin server

最后,我们再回到当前目录,执行以下命令,即可看到执行成功:

cargo run --bin client

大功告成!

Part 4. 添加一个中间件

接下来,让我们来看下如何给 Volo 添加一个中间件。

例如,我们需要一个中间件,打印出我们收到的请求、返回的响应以及消耗的时间,那我们可以在 lib.rs 中写这么一个 Service:

#[derive(Clone)]
pub struct LogService<S>(S);

#[volo::service]
impl<Cx, Req, S> volo::Service<Cx, Req> for LogService<S>
where
    Req: Send + 'static,
    S: Send + 'static + volo::Service<Cx, Req> + Sync,
    Cx: Send + 'static,
{
    async fn call(&self, cx: &mut Cx, req: Req) -> Result<S::Response, S::Error> {
        let now = std::time::Instant::now();
        let resp = self.0.call(cx, req).await;
        tracing::info!("Request took {}ms", now.elapsed().as_millis());
        resp
    }
}

随后,我们给这个 Service 包装一层 Layer:

pub struct LogLayer;

impl<S> volo::Layer<S> for LogLayer {
    type Service = LogService<S>;

    fn layer(self, inner: S) -> Self::Service {
        LogService(inner)
    }
}

最后,我们在 client 和 server 里面加一下这个 Layer:

use volo_example::LogLayer;

// client.rs
static ref CLIENT: volo_gen::volo::example::ItemServiceClient = {
    let addr: SocketAddr = "[::1]:8080".parse().unwrap();
    volo_gen::volo::example::ItemServiceClientBuilder::new("volo-example")
        .layer_outer(LogLayer)
        .address(addr)
        .build()
};

// server.rs
Server::new()
    .add_service(ServiceBuilder::new(volo_gen::volo::example::ItemServiceServer::new(S)).build())
    .layer_front(LogLayer)
    .run(addr)
    .await
    .unwrap();

这时候,在 info 日志级别下,我们会打印出请求的耗时。

Part 5. What’s Next?

恭喜你,阅读到了这里! 至此,我们已经基本学会了 Volo 的大部分使用了,可以使用 Volo 来开启我们愉快的 Rust 之旅啦~

接下来,你可能需要选择合适的组件,组装在一起,和你的系统进行对接。

Volo 维护的相关生态会集中在:https://github.com/volo-rs 中,我们正在努力打造我们的生态,也非常欢迎大家一起参与~

如果有比较急缺的组件,也欢迎在官方仓库:https://github.com/cloudwego/volo 的 issue 中提出,我们也会优先支持社区最急缺的组件。

同时,欢迎加入我们的飞书用户群,交流 Volo 的使用心得~

Volo_feishu


期待你使用 Volo 创造出属于你的独一无二的作品~


最后修改 March 19, 2024 : chore: slack to discord (#1044) (4c2f994)