gRPC服务调用+protoc 生成swagger API文档

最新推荐文章于 2025-08-08 09:06:45 发布

原创最新推荐文章于 2025-08-08 09:06:45 发布 · 7.6k 阅读

2 ·

CC 4.0 BY-SA版权

文章标签：

#rpc

grpc 专栏收录该内容

2 篇文章

订阅专栏

本文档详细介绍了如何在Ubuntu 18.04环境下，通过gRPC、Protocol Buffers v3以及相关插件安装，编写proto文件并编译生成Go源码及swagger.json。接着，利用docker启动Swagger UI服务来展示API文档，同时阐述了如何编写和调用RPC服务，包括server.go和client.go的实现，并提供了完整的项目目录结构。

1、环境

操作系统：ubuntu 18.04
go版本：1.14.2
docker版本：19.03.1
docker-compose版本：1.24.0

2、gRPC环境安装

# 启用 module模式
GO111MODULE="on"
# 配置 goproxy
go env -w GOPROXY="https://goproxy.io,https://goproxy.cn,direct"
# 安装 grpc
$ go get -u google.golang.org/grpc

3、安装 Protocol Buffers v3

$ wget https://github.com/protocolbuffers/protobuf/releases/download/v3.11.4/protobuf-all-3.11.4.tar.gz
$ sudo tar -zxvf protobuf-all-3.11.4.tar.gz -C /usr/local
$ cd /usr/local/protobuf-3.11.4/
$ sudo ./configure
$ sudo make
$ sudo make install
$ sudo ldconfig

检查是否安装成功

$ protoc --version
libprotoc 3.11.4

4、安装插件 protoc-gen-go、protoc-gen-grpc-gateway、protoc-gen-swagger

go get -u github.com/golang/protobuf/protoc-gen-go
go get -u github.com/grpc-ecosystem/grpc-gateway/protoc-gen-grpc-gateway
go get -u github.com/grpc-ecosystem/grpc-gateway/protoc-gen-swagger

5、编写protot文件并编译

5.1 生成swagger API 文档，需要用到`google/api`中`http.proto`、`annotations.proto`这两个文件，先拷贝到项目目录下

# 进入项目的根目录
$ cd /path/to/project
$ mkdir -p ./proto/google/api
$ cp -r $GOPATH/pkg/mod/github.com/grpc-ecosystem/grpc-gateway@v1.14.4/third_party/googleapis/google/api/* ./proto/google/api

5.2 编写protot文件

syntax = "proto3";

package proto;

import "google/api/annotations.proto";

// 源.proto文件应包含go_package选项，该选项指定文件的完整Go导入路径。
// 如果没有go_package选项，则编译器将尝试猜测一个。将来的编译器版本将要求go_package选项。
// 生成的代码的Go包名称将是go_package选项的最后一个路径组件。
option go_package = "../proto";

message StringMessage {
  string value = 1;
}

//定义RPC服务
service HelloService {
  rpc Hello (StringMessage) returns (StringMessage) {
    option (google.api.http) = {
      post: "/v1/hello"
      body: "*"
    };
  }
}

5.3 使用protoc命令编译生成go源码及swagger.json

# 生成proto对应的go源码
protoc --go_out=plugins=grpc:. *.proto

# 生成proto对应的swagger.json文件(/path/to/project为项目的根目录)
protoc -I /usr/local/include -I . -I /path/to/project/proto/google/api --swagger_out=logtostderr=true:. ./hello.proto

6、使用docker启动swagger ui服务，查看生成的API文档

docker run --rm -d -p 80:8080 -e SWAGGER_JSON=/foo/hello.swagger.json -v /path/to/project/proto:/foo swaggerapi/swagger-ui

访问swagger ui服务所在的主机的80端口，即可查看API文档在这里插入图片描述

7、编写`server.go`和`client.go`调用RPC服务

7.1 server.go

package main

import (
	"context"
	pb "github.com/king-tu/helloGRPC/proto"
	"google.golang.org/grpc"
	"log"
	"net"
)

type HelloService struct{}

func (*HelloService) Hello(ctx context.Context, msg *pb.StringMessage) (*pb.StringMessage, error) {
	log.Println("client request message: ", msg)
	reply := &pb.StringMessage{
		Value: "hello " + msg.Value,
	}
	return reply, nil
}

func main() {
	address := ":1234"
	//获取grpc服务端对象
	grpcServer := grpc.NewServer()
	//注册grpc服务
	pb.RegisterHelloServiceServer(grpcServer, new(HelloService))

	//设置服务端监听
	lis, err := net.Listen("tcp", address)
	if err != nil {
		panic(err)
	}
	//在指定端口上提供grpc服务
	log.Println("gRPC Server listen on: ", address)
	if err := grpcServer.Serve(lis); err != nil {
		panic(err)
	}
}

7.2 client.go

package main

import (
	"context"
	pb "github.com/king-tu/helloGRPC/proto"
	"google.golang.org/grpc"
	"log"
)

func main() {
	//和grpc服务建立连接
	conn, err := grpc.Dial("localhost:1234", grpc.WithInsecure())
	if err != nil {
		panic(err)
	}
	defer conn.Close()

	client := pb.NewHelloServiceClient(conn)
	reply, err := client.Hello(context.Background(), &pb.StringMessage{Value: "lisi"})
	if err != nil {
		panic(err)
	}
	log.Println("reply: ", reply)
}

7.3 测试效果

服务端

$ go run server.go 
2020/04/28 01:04:54 gRPC Server listen on:  :1234
2020/04/28 01:05:10 client request message:  value:"lisi"

客户端

$ go run client.go 
2020/04/28 01:06:01 reply:  value:"hello lisi"

8、完整项目目录

$ tree
.
├── client
│   └── client.go
├── go.mod
├── go.sum
├── proto
│   ├── google
│   │   └── api
│   │       ├── annotations.proto
│   │       ├── httpbody.proto
│   │       └── http.proto
│   ├── hello.pb.go
│   ├── hello.proto
│   └── hello.swagger.json
└── server
    └── server.go

5 directories, 10 files