Golang微服务框架Kratos使用问题小结

官方默认的 layout 目录已其实已经包含第三方包，但proto 文件仍然会出现红色波浪线，如import "google/api/annotations.proto";，以 VS Code 为例，只需要添加如下文件及配置：

.vscode/settings.json

{
  "protoc": {
    "options": [
      "--proto_path=${workspaceRoot}/third_party",
    ]
  }
}

在 protobuf文件中添加的验证规则未生效

首先要确保在 protoc 命令中添加参数：

--validate_out=paths=source_relative,lang=go:. \

其次在grpc.go或http.go文件（取决于你使用的服务）中应加入validate.Validator中间件

import "github.com/go-kratos/kratos/v2/middleware/validate"
....
		http.Middleware(
			recovery.Recovery(),
			validate.Validator(),
		),
....

unsupported Scan, storing driver.Value type []uint8 into type *time.Time
这个错误与 Kratos 无关，顺便记录在此，大概率你不会碰到这个问题，因为对 MySQL的配置一般都会怼上charset=utf8mb4&parseTime=True&loc=Local，万一出现这个报错，那就是缺少parseTime所致。

成功及错误响应值格式可通过http.ResponseEncoder和http.ErrorEncode进行定制

Kratos 默认返回的错误消息同时反馈在 HTTP状态码中（在kratos/v2/error中还内置了多个方法，如BadRequest、UnAuthorized等），设计者应该是觉得HTTP状态码的语义更为前端所熟悉，但目前大多使用axios库来发起 HTTP请求，这样默认service.interceptors.response.use的拦截会直接进入error部分，那返回的消息体岂不是毫无价值了？原因从axios源码可以找到：

validateStatus: function validateStatus(status) {
  return status >= 200 && status < 300;
}

一种方式是修改Kratos中的错误处理或者一律返回200到300之间的状态码，但这便辜负了框架的精妙设计，另一种自然就是从前端下手，比如假定简单粗暴地将500以下的状态码都视为正常，错误消息在response由前端处理，可以使用如下配置：

const service = axios.create({
  validateStatus: (status)=>{
    return status < 500
  },
...
}

Protobuf和OpenAPI关于变量的使用方式有点烦，如果使用camelCase，一切太平，但如果使用snake_case，就开始麻烦了，你会发现接口本身字段没有问题，但 OpenAPI 开始作妖，文档里会显示为camelCase，那如何让文档里也显示为snake_case呢？那就还要再加一个注解，比如：

string captcha_id = 1 [json_name="captcha_id"];

顺便说一下，如果字段定义与json_name不统一也会出问题，这种方法的缺点是太烦琐，需要为每个字段添加注解。
经过进一步的探索，在生成时可通过protoc-gen-openapi的参数naming=proto来配置生成使用Protobuf文件定义名称的文档字段（此步骤在 Kratos 中并无必要，只需关注下面的一个配置即可，但如果将生成的 openapi.yaml拿到外面使用，比如editor.swagger.io/， 未加参数会显示为camelCase）。

api:
    protoc --proto_path=./api \
...
           --openapi_out=fq_schema_naming=true,naming=proto,default_response=false:. \
...

但如果使用Kratos直接启动swagger，需要在server/http.go中添加配置generator.UseJSONNamesForFields(false)，因其默认值为true：

openAPIhandler := openapiv2.NewHandler(
    openapiv2.WithGeneratorOptions(
        generator.UseJSONNamesForFields(false), 
        generator.EnumsAsInts(true)))
srv.HandlePrefix("/q/", openAPIhandler)

以上都是针对文档，实际返回字段需要对protojson添加UseProtoNames来进行序列化配置，Kratos中已暴露了相关配置（github.com/go-kratos/k… ），只需将其加入到 main.go 文件的init()中即可：

func init() {
	json.MarshalOptions = protojson.MarshalOptions{
		EmitUnpopulated: true,
		UseProtoNames:   true,
	}
	flag.StringVar(&flagconf, "conf", "../../configs", "config path, eg: -conf config.yaml")
}

GRPC 不似 HTTP 那样利于调试，可以考虑使用以下工具：

• grpcui（这个工具我在安装时出现go:linkname must refer to declared function or variable，这是本地使用的版本是 go 1.18有关，解决方案是go get -u golang.org/x/sys，如果你也有这个问题，可能像我一样克隆代码在本地编译安装）
• bloomrpc
• Postman，是的，Postman 也有相关支持，但要求首先注册一个账号

在make api时出现添加--experimental_allow_proto3_optional参数的提示是因为 在 proto中使用了optional，但在3.15.0中这个特性已经转正，所以可以直接升级解决问题，当然不愿意升级请直接对protoc命令添加该参数；那我们为什么要添加optional呢（你还会在网上看到官方不建议使用optional，并且在3.15.0之前它一直作为experimental，要额外添加参数运行）？其实这与 Go 语言对零值的处理有关，在 Go 语言中数值、字符串等类型会默认被置为零值，那么问题就来了，我们怎么值知道一个int类型的变量是未传参还是传参的值为0，这时就要使用引用类型*int，在 Protobuf 中对应的就是在定义字段时在前面添加optional。
补充一个知识点，使用 Vue 进行前端开发的同学很多人会使用element-ui，它也有一个坑，就是在添加clearable属性后清空字段会默认将v-model对应的变量（即使它是一个数值类型）设置为空字符串，那问题来了，传一个空字符串给后端明显类型不匹配呀！于是我们又需要再添加一个@clear="status = null"（假定变量名称为status）来进行处理。

POST 等请求如何获取query string，也就说怎么获取到mydomain.com/url?query1=… 中query1和 query2的值，一开始我以为要通过http.RequestDecoder进行自定义，其实并不需要：

  rpc Post (PostRequest) returns (google.protobuf.Empty){
    option (google.api.http) = {
      post: "/url",
      body: "body",
    };
  };
...

message PostRequest {
  string query1 = 1;
  string query2 = 2;
  Body body = 3;
}

message Body {
....
}

这里考虑到请求体可能有多个字段，定义了一个嵌套的Body类型来接收POST请求本身提交的字段 body:"body"中第二个body为 PostRequest 中的自定义字段，如仅一个字段，自然可以直接使用 string 等类型。