xiaozhuang

大家好,我是失业在家,正在找工作的博主Jerry,找工作之余,看到.Net 7.0 RC2发布了,就想测试下.Net 7.0 RC2 gRPC JSON 转码为 Swagger/OpenAPI文档的特性,这个特性大大提高了测试gRPC接口的方便性。本来以为按照官方文档,也就是几分钟的事,结果搞了几个小时才成功!我也是服了官方的文档了!

我现在把要要注意的几个问题列出来,给要使用这个特性的程序员节约一点时间。

一、官方文档对gRPC JSON 转码配置描述不完整

这个特性是基于gRPC JSON 转码配置的,也就是说我们先要配置gRPC JSON 转码才能使用该特性。

// Add services to the container.
builder.Services.AddGrpc().AddJsonTranscoding();

如上我们在Program.cs中的代码,先要先加上gRPC JSON转码。如果按照官方文档直接在.proto文件的rpc方法中增加option

 option (google.api.http) = {
      get: "/v1/greeter/{name}"
    };

则编译会报错,“Option "(google.api.http)" unknown. Ensure that your proto definition file imports the proto which defines the option.”

要先按照另一个官方文档专门配置gRPC JSON转码。要在.proto文件中增加“import "google/api/annotations.proto";   

import "google/api/annotations.proto";

二、官方文档对gRPC JSON 转码配置描述不清楚

加上了import..., 还是会编译出错,"Import "google/api/annotations.proto" was not found or had errors.".

原因就是文档里的这一句“Imported from the google/api/annotations.proto file. The google/api/http.proto and google/api/annotations.proto files need to be in the project.”实在说的不清楚。

 其实,我们要在我们项目的根目录建立google文件夹,然后在下面建立api文件夹,再把这两个文件放到里面。如下截图:

然后还要确保项目文件中,不要把这两个文件包含到Protobuf节点中。不然在启动程序的时候就会出现对象转换失败的错误,“[A]Google.Protobuf.ExtensionValue`1[Google.Api.HttpRule] cannot be cast to [B]Google.Protobuf.ExtensionValue`1[Google.Api.HttpRule]. Type A originates from 'Google.Protobuf, Version=3.19.4.0, Culture=neutral, PublicKeyToken=a7d26565bac4d604' in the context 'Default' at location 'D:\\Study\\Test\\GrpcService4TestSwagger\\bin\\Debug\\net7.0\\Google.Protobuf.dll'. Type B originates from 'Google.Protobuf, Version=3.19.4.0, Culture=neutral, PublicKeyToken=a7d26565bac4d604' in the context 'Default' at location 'D:\\Study\\Test\\GrpcService4TestSwagger\\bin\\Debug\\net7.0\\Google.Protobuf.dll'”

<ItemGroup>
    <Protobuf Include="Protos\greet.proto" GrpcServices="Server" />
  </ItemGroup>

 这样就算配置gRPC JSON转码完成了,程序终于可以运行起来了。

三、官方文档上的代码片段不正确

这时候,如果你访问Swagger的页面还是会出错,“System.IO.FileNotFoundException:“Could not find file 'D:\Study\Test\GrpcService4TestSwagger\bin\Debug\net7.0\Server.xml”,我真是服了这个官方文档了,要把官方文档给的代码:

var filePath = Path.Combine(System.AppContext.BaseDirectory, "Server.xml");
    c.IncludeXmlComments(filePath);
    c.IncludeGrpcXmlComments(filePath, includeControllerXmlComments: true);

改成这样才行:

 var xmlFilename = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
    var filePath = Path.Combine(AppContext.BaseDirectory, xmlFilename);
    c.IncludeXmlComments(filePath);
    c.IncludeGrpcXmlComments(filePath, includeControllerXmlComments: true);

终于, gRPC JSON 转码为 Swagger/OpenAPI文档的特性可以成功运行了。

四、找工作

▪ 博主有15年以上的软件技术实施经验(Technical Leader),专注于微服务和云原生(K8s)软件架构设计、专注于 .Net Core\Java开发和Devops构建发布。
▪ 博主10年以上的软件交付管理经验(Project Manager & Product Ower),致力于敏捷(Scrum)项目管理、软件产品业务需求分析和原型设计。
▪ 博主熟练配置和使用 Microsoft Azure云。
▪ 博主为人诚恳,积极乐观,工作认真负责。 

我家在广州,也可以去深圳工作。做架构和项目管理都可以。有工作机会推荐的朋友可以加我微信 15920128707,微信名字叫Jerry。

相关文章: