Kratos微服务框架API工程化指南

Kratos的RPC默认使用的是gRPC，与此同时我们还可以通过gRPC的grpc-gateway功能对RESTfull进行支持。这样，我们就可以同时支持gRPC和REST了。而这一切Kratos都已经封装好，无需知道底层的一切，用就好了。

gRPC是基于Protobuf作为接口规范的描述语言（IDL，Interface Description Language）。换句通俗的话来说，gRPC使用Protobuf来设计和管理API。我们只需要编写一套Protobuf文件，就能够支持gRPC协议和RESTfull协议。Protobuf支持很多编程语言，比如：C++、Java、JavaScript、Python、Go、Ruby、Objective-C、C#……这也就意味着，它很适合多语言异构化架构，这样的场景在现实中是很稀松平常的，这使得Protobuf具有很强的实用性。

Protobuf具有序列化后数据量更小、序列化/反序列化速度更快、更简单的特性；而JSON则相反，序列化后数据量较大，序列化和反序列化速度不优的特性，但是前端对JSON是原生支持，对前端极其友好。那么，我们可以在服务之间使用gRPC进行通讯，服务与前端之间可以通过RESTfull进行通讯。

Protobuf和gRPC已经发展了许多年，极其稳定，生态链丰富。它具有强大的工具链可供使用，只要你想得到的，都能够找得到相对应的工具。没有合适的工具也没有关系，它的工具是使用插件方式来实现可扩展性的，因此我们可以容易的开发出自己的工具插件，Kratos就为此开发了自己的一系列的工具插件方便开发使用。

综上，我们可知使用gRPC/protobuf的好处：

一套proto，同时支持gRPC协议和RESTfull协议；
支持多编程语言，适合多语言异构化架构；
gRPC协议，数据量小、序列化/反序列化速度更快、更简单，适合服务之间通讯；
RESTfull协议，数据量较大、序列化/反序列化速度较慢、前端原生支持JSON，适合同前端的通讯。
强大的工具链，使用插件的方式实现强大的可扩展性，可方便的扩展。

那么，这篇文章将会带来一些什么呢？

Protobuf设计API的一丢丢基本知识；
相关工具链的使用方法；
如何实施工程化的方法。

工具安装

工欲善其事，必先利其器。

让我们先安装所需要的工具。

安装 protoc

protoc是一款用C++编写的工具，其可以将proto文件翻译为指定语言的代码。

具体用法可以使用protoc --help命令查看。

goctl一键安装

$ goctl env check -i -f --verbose                                 
[goctl-env]: preparing to check env

[goctl-env]: looking up "protoc"
[goctl-env]: "protoc" is not found in PATH
[goctl-env]: preparing to install "protoc"
"protoc" installed from cache
[goctl-env]: "protoc" is already installed in "/Users/keson/go/bin/protoc"

macOS安装

brew install protobuf

Ubuntu安装

sudo apt update; sudo apt upgrade
sudo apt install libprotobuf-dev protobuf-compiler

非Windows系统源代码安装

进入 protobuf release 下载页面下载；

解压并进入文件夹：

tar -xzvf protobuf-cpp-x.x.x.tar.gz
cd protobuf-cpp-x.x.x

设置编译目录

./configure --prefix=/usr/local/protobuf

安装检测
```
make check
```
安装及编译
```
make && make install
```

配置环境变量

vim ~/.bash_profile

在文件结尾添加环境变量

export PROTOBUF=/usr/local/protobuf
export PATH=$PATH:$PROTOBUF/bin

使用source命令，使配置文件生效

source ~/.bash_profile

非Windows系统源二进制文件安装

进入 protobuf release 下载页面，选择适合自己操作系统的压缩包文件下载；

解压文件：

tar -xzvf protoc-x.x.x-{OS}-x86_64.tar.gz

拷贝protoc文件

cd protoc-x.x.x-{OS}-x86_64/bin
sudo chmod a+x protoc
mv protoc /usr/local/bin

拷贝头文件

cd protoc-x.x.x-{OS}-x86_64/include
cp google /usr/local/include

Windows安装

在Windows下可以使用包管理器Choco和Scoop来安装。

Choco
```
choco install protoc
```

Scoop

scoop bucket add extras
scoop install protobuf

后端工具

后端工具都可以使用go install进行安装：

用于生成struct代码：

go install google.golang.org/protobuf/cmd/protoc-gen-go@latest

用于生成grpc服务代码：

go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest

用于生成rest服务代码：

go install github.com/go-kratos/kratos/cmd/protoc-gen-go-http/v2@latest

用于生成kratos的错误定义代码：

go install github.com/go-kratos/kratos/cmd/protoc-gen-go-errors/v2@latest

用于生成消息验证器代码：

go install github.com/envoyproxy/protoc-gen-validate@latest

用于生成OpenAPI V2文档：

go install github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-openapiv2@latest

用于生成OpenAPI V3文档：

go install github.com/google/gnostic/cmd/protoc-gen-openapi@latest

前端工具

这是protobuf.js提供的一个Protobuf转换为Typescript的工具：

pnpm i pbts -g

设计API

在开始前，首先要说明的是，本文并不是一个Protobuf或者gRPC的教程，这方面，谷歌官方以及其他第三方（gRPC-Gateway）提供的资料已经足够详尽了：

CURD

在现实场景下，业务代码写得最多的恐怕还属CURD（增、删、改、查）了，不说多，80%是肯定有的，可以说，只要搞定了CURD，就搞定了大部分的业务代码的编写。

以下是一个gRPC官方提供的示例，是一个书店的接口，里面包含了基本的Protobuf的语法和用法，以及gRPC服务和REST服务的设计。

syntax = "proto3";

package endpoints.examples.bookstore;

option java_multiple_files = true;
option java_outer_classname = "BookstoreProto";
option java_package = "com.google.endpoints.examples.bookstore";

option go_package = "endpoints/examples/bookstore;bookstore";


import "google/api/annotations.proto";
import "google/protobuf/empty.proto";

// A simple Bookstore API.
//
// The API manages shelves and books resources. Shelves contain books.
service Bookstore {
  // Returns a list of all shelves in the bookstore.
  rpc ListShelves(google.protobuf.Empty) returns (ListShelvesResponse) {
    // Define HTTP mapping.
    // Client example (Assuming your service is hosted at the given 'DOMAIN_NAME'):
    //   curl http://DOMAIN_NAME/v1/shelves
    option (google.api.http) = { get: "/v1/shelves" };
  }
  // Creates a new shelf in the bookstore.
  rpc CreateShelf(CreateShelfRequest) returns (Shelf) {
    // Client example:
    //   curl -d '{"theme":"Music"}' http://DOMAIN_NAME/v1/shelves
    option (google.api.http) = {
      post: "/v1/shelves"
      body: "shelf"
    };
  }
  // Returns a specific bookstore shelf.
  rpc GetShelf(GetShelfRequest) returns (Shelf) {
    // Client example - returns the first shelf:
    //   curl http://DOMAIN_NAME/v1/shelves/1
    option (google.api.http) = { get: "/v1/shelves/{shelf}" };
  }
  // Deletes a shelf, including all books that are stored on the shelf.
  rpc DeleteShelf(DeleteShelfRequest) returns (google.protobuf.Empty) {
    // Client example - deletes the second shelf:
    //   curl -X DELETE http://DOMAIN_NAME/v1/shelves/2
    option (google.api.http) = { delete: "/v1/shelves/{shelf}" };
  }
}

// A shelf resource.
message Shelf {
  // A unique shelf id.
  int64 id = 1;
  // A theme of the shelf (fiction, poetry, etc).
  string theme = 2;
}

// Response to ListShelves call.
message ListShelvesResponse {
  // Shelves in the bookstore.
  repeated Shelf shelves = 1;
}

// Request message for CreateShelf method.
message CreateShelfRequest {
  // The shelf resource to create.
  Shelf shelf = 1;
}

// Request message for GetShelf method.
message GetShelfRequest {
  // The ID of the shelf resource to retrieve.
  int64 shelf = 1;
}

// Request message for DeleteShelf method.
message DeleteShelfRequest {
  // The ID of the shelf to delete.
  int64 shelf = 1;
}

需要说明的是，REST的接口是由google.api.http这个option提供的。上面这一套接口定义，既可以生成gRPC的服务，又可以生成REST的服务，而这是根据protoc调用的插件决定的，这方面内容不是这部分所要阐述的，暂且不表，且看后面部分。

Kratos Errors

在实际应用当中，存在着一个问题：gRPC状态码和 REST HTTP状态码是不一样的。为了解决这个问题，就需要一个映射表，用来互相转换状态码。

以下就是一个映射表的示例：

syntax = "proto3";

// 定义包名
package api.kratos.v1;
import "errors/errors.proto";

// 多语言特定包名，用于源代码引用
option go_package = "kratos/api/helloworld;helloworld";
option java_multiple_files = true;
option java_package = "api.helloworld";

enum ErrorReason {
  // 设置缺省错误码
  option (errors.default_code) = 500;

  // 为某个枚举单独设置错误码
  USER_NOT_FOUND = 0 [(errors.code) = 404];

  CONTENT_MISSING = 1 [(errors.code) = 400];
}

它利用了Protobuf的enum和option关键字实现了这样一个状态码的映射。再由protoc插件生成的代码实现映射和互换。

Message Validator

在实际应用当中，需要对接口的参数进行一些校验，比如：用户名的长度只能够大于或者小于某一个长度，身份证、手机号、EMail等特定格式的有效校验。

其实，都不过是一些字符串、数字类型和布尔类型校验的简单规则。如果手写校验代码，都是一些机械无比的重复代码，而且要作修改起来也很痛苦。

那么，有什么办法可以解决这个问题吗？必须有：规则写在Protobuf里面，利用proto-gen-validate插件生成代码，使用 Kratos Validate 中间件作支持。

以下是proto-gen-validate插件的示例接口：

syntax = "proto3";

package examplepb;

import "validate/validate.proto";

message Person {
  uint64 id = 1 [(validate.rules).uint64.gt = 999];

  string email = 2 [(validate.rules).string.email = true];

  string name = 3 [(validate.rules).string = {
    pattern:   "^[^[0-9]A-Za-z]+( [^[0-9]A-Za-z]+)*$",
    max_bytes: 256,
  }];

  Location home = 4 [(validate.rules).message.required = true];

  message Location {
    double lat = 1 [(validate.rules).double = {gte: -90,  lte: 90}];
    double lng = 2 [(validate.rules).double = {gte: -180, lte: 180}];
  }
}

只需要利用validate.rulesoption就可以定义规则了，简单明了，又方便。

OpenAPI

OpenAPI是一个用于描述REST API的描述格式，包含端点、参数、输入输出格式、说明、认证等，本质上它是一个JSON或者YAML格式文档，而文件内的Schema则是有OpenAPI所定义的。

以下是一个OpenAPI v3的JSON文件范例：

{
  "openapi": "3.0",
  "info": {
    "version": "1.0.0",
    "title": "OpenAPI Petstore",
    "license": {
      "name": "MIT"
    }
  },
  "servers": [
    {
      "url": "https://petstore.openapis.org/v1",
      "description": "Development server"
    }
  ],
  "paths": {
    "/pets": {
      "get": {
        "summary": "List all pets",
        "operationId": "listPets",
        "tags": [
          "pets"
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "description": "How many items to return at one time (max 100)",
            "required": false,
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "An paged array of pets",
            "headers": {
              "x-next": {
                "schema": {
                  "type": "string"
                },
                "description": "A link to the next page of responses"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Pets"
                }
              }
            }
          },
          "default": {
            "description": "unexpected error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "post": {
        "summary": "Create a pet",
        "operationId": "createPets",
        "tags": [
          "pets"
        ],
        "responses": {
          "201": {
            "description": "Null response"
          },
          "default": {
            "description": "unexpected error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/pets/{petId}": {
      "get": {
        "summary": "Info for a specific pet",
        "operationId": "showPetById",
        "tags": [
          "pets"
        ],
        "parameters": [
          {
            "name": "petId",
            "in": "path",
            "required": true,
            "description": "The id of the pet to retrieve",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Expected response to a valid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Pets"
                }
              }
            }
          },
          "default": {
            "description": "unexpected error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Pet": {
        "required": [
          "id",
          "name"
        ],
        "properties": {
          "id": {
            "type": "integer",
            "format": "int64"
          },
          "name": {
            "type": "string"
          },
          "tag": {
            "type": "string"
          }
        }
      },
      "Pets": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/Pet"
        }
      },
      "Error": {
        "required": [
          "code",
          "message"
        ],
        "properties": {
          "code": {
            "type": "integer",
            "format": "int32"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  }
}

以及OpenAPI v3 的 YAML文件范例：

openapi: "3.0"
info:
  version: 1.0.0
  title: OpenAPI Petstore
  license:
    name: MIT
servers:
- url: https://petstore.openapis.org/v1
  description: Development server
paths:
  /pets:
    get:
      summary: List all pets
      operationId: listPets
      tags:
      - pets
      parameters:
      - name: limit
        in: query
        description: How many items to return at one time (max 100)
        required: false
        schema:
          type: integer
          format: int32
      responses:
        "200":
          description: An paged array of pets
          headers:
            x-next:
              schema:
                type: string
              description: A link to the next page of responses
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pets'
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      summary: Create a pet
      operationId: createPets
      tags:
      - pets
      responses:
        "201":
          description: Null response
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /pets/{petId}:
    get:
      summary: Info for a specific pet
      operationId: showPetById
      tags:
      - pets
      parameters:
      - name: petId
        in: path
        required: true
        description: The id of the pet to retrieve
        schema:
          type: string
      responses:
        "200":
          description: Expected response to a valid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pets'
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Pet:
      required:
      - id
      - name
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
        tag:
          type: string
    Pets:
      type: array
      items:
        $ref: '#/components/schemas/Pet'
    Error:
      required:
      - code
      - message
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string

以上文本当中的Schema，有些可以望文生义，也有一些根本看不出来意义。可是，真要让人去阅读，只会有一个感受：头大。它主要还是给程序读取的，展现在UI之上，才能够让人感受到愉快。

现在，市面上有非常非常多的工具可以读取OpenAPI JSON / YAML文档：

Swagger UI / SwaggerHub / Swagger Editor
Redoc / Redocly
Stoplight Elements / Stoplight
ReadMe Documentation
Eolink
YApi
Postman
Apifox

这些工具当中，最常见的是本家的Swagger UI（OpenAPI在成为开放标准之前是Swagger产品线当中的一部分），Kratos原生支持Swagger UI：https://github.com/go-kratos/swagger-api

在本文接着后面，我要着重讲的，要推荐的是国产神器：Apifox。我这人对国产软件一向都是抱有藐视的态度，但是Apifox是真好使，绝对的开发利器，使得我一改对国产软件的态度，大力推荐。

现在OpenAPI有两个版本：v2和v3。

主流的protoc插件也刚好对应有两个：

OpenAPI v2使用grpc-gateway出的protoc-gen-openapiv2；
OpenAPI v3使用谷歌出品的gnostic下的protoc-gen-openapi。

正常来说，只要是使用了google.api.http这个option定义的API，使用这两个插件就能够生成OpenAPI的文档。

但是，实际应用中，我们还希望能够提供更多更丰富的一些信息，比如：描述信息、版本号、版权信息、认证信息……显然，光凭着google.api.http的定义是不够的。这两个插件提供了各自的option，可以定义这些信息。

我们可以看一看都是怎样定义的：

OpenAPI v2

syntax = "proto3";

package grpc.gateway.examples.internal.proto.examplepb;

import "protoc-gen-openapiv2/options/annotations.proto";

option go_package = "github.com/grpc-ecosystem/grpc-gateway/v2/examples/internal/proto/examplepb";
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_swagger) = {
  info: {
    title: "A Bit of Everything";
    version: "1.0";
    contact: {
      name: "gRPC-Gateway project";
      url: "https://github.com/grpc-ecosystem/grpc-gateway";
      email: "none@example.com";
    };
    license: {
      name: "BSD 3-Clause License";
      url: "https://github.com/grpc-ecosystem/grpc-gateway/blob/master/LICENSE.txt";
    };
    extensions: {
      key: "x-something-something";
      value {
        string_value: "yadda";
      }
    }
  };
  // Overwriting host entry breaks tests, so this is not done here.
  external_docs: {
    url: "https://github.com/grpc-ecosystem/grpc-gateway";
    description: "More about gRPC-Gateway";
  }
  schemes: HTTP;
  schemes: HTTPS;
  schemes: WSS;
  consumes: "application/json";
  consumes: "application/x-foo-mime";
  produces: "application/json";
  produces: "application/x-foo-mime";
  security_definitions: {
    security: {
      key: "BasicAuth";
      value: {
        type: TYPE_BASIC;
      }
    }
    security: {
      key: "ApiKeyAuth";
      value: {
        type: TYPE_API_KEY;
        in: IN_HEADER;
        name: "X-API-Key";
        extensions: {
          key: "x-amazon-apigateway-authtype";
          value {
            string_value: "oauth2";
          }
        }
        extensions: {
          key: "x-amazon-apigateway-authorizer";
          value {
            struct_value {
              fields {
                key: "type";
                value {
                  string_value: "token";
                }
              }
              fields {
                key: "authorizerResultTtlInSeconds";
                value {
                  number_value: 60;
                }
              }
            }
          }
        }
      }
    }
    security: {
      key: "OAuth2";
      value: {
        type: TYPE_OAUTH2;
        flow: FLOW_ACCESS_CODE;
        authorization_url: "https://example.com/oauth/authorize";
        token_url: "https://example.com/oauth/token";
        scopes: {
          scope: {
            key: "read";
            value: "Grants read access";
          }
          scope: {
            key: "write";
            value: "Grants write access";
          }
          scope: {
            key: "admin";
            value: "Grants read and write access to administrative information";
          }
        }
      }
    }
  }
  security: {
    security_requirement: {
      key: "BasicAuth";
      value: {};
    }
    security_requirement: {
      key: "ApiKeyAuth";
      value: {};
    }
  }
  security: {
    security_requirement: {
      key: "OAuth2";
      value: {
        scope: "read";
        scope: "write";
      }
    }
    security_requirement: {
      key: "ApiKeyAuth";
      value: {};
    }
  }
  responses: {
    key: "403";
    value: {
      description: "Returned when the user does not have permission to access the resource.";
    }
  }
  responses: {
    key: "404";
    value: {
      description: "Returned when the resource does not exist.";
      schema: {
        json_schema: {
          type: STRING;
        }
      }
    }
  }
  responses: {
    key: "418";
    value: {
      description: "I'm a teapot.";
      schema: {
        json_schema: {
          ref: ".grpc.gateway.examples.internal.proto.examplepb.NumericEnum";
        }
      }
    }
  }
  responses: {
    key: "500";
    value: {
      description: "Server error";
      headers: {
        key: "X-Correlation-Id"
        value: {
          description: "Unique event identifier for server requests"
          type: "string"
          format: "uuid"
          default: "\"2438ac3c-37eb-4902-adef-ed16b4431030\""
          pattern: "^[0-9A-F]{8}-[0-9A-F]{4}-4[0-9A-F]{3}-[89AB][0-9A-F]{3}-[0-9A-F]{12}$"
        }
      };
      schema: {
        json_schema: {
          ref: ".grpc.gateway.examples.internal.proto.examplepb.ErrorResponse";
        }
      }
    }
  }
  tags: {
    name: "echo rpc"
    description: "Echo Rpc description"
    extensions: {
      key: "x-traitTag";
      value {
        bool_value: true;
      }
    }
  }
  extensions: {
    key: "x-grpc-gateway-foo";
    value {
      string_value: "bar";
    }
  }
  extensions: {
    key: "x-grpc-gateway-baz-list";
    value {
      list_value: {
        values: {
          string_value: "one";
        }
        values: {
          bool_value: true;
        }
      }
    }
  }
};

message ErrorResponse {
  string correlationId = 1 [(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
    pattern: "^[0-9A-F]{8}-[0-9A-F]{4}-4[0-9A-F]{3}-[89AB][0-9A-F]{3}-[0-9A-F]{12}$",
    title: "x-correlation-id",
    description: "Unique event identifier for server requests",
    format: "uuid",
    example: "\"2438ac3c-37eb-4902-adef-ed16b4431030\""
  }];
  ErrorObject error = 2;
}

message ErrorObject {
  int32 code = 1 [(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
    pattern: "^[0-9]$",
    title: "code",
    description: "Response code",
    format: "integer"
  }];
  string message = 2 [(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
    pattern: "^[a-zA-Z0-9]{1, 32}$",
    title: "message",
    description: "Response message"
  }];
}

// ABitOfEverything service is used to validate that APIs with complicated
// proto messages and URL templates are still processed correctly.
service ABitOfEverythingService {
  option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_tag) = {
    description: "ABitOfEverythingService description -- which should not be used in place of the documentation comment!"
    external_docs: {
      url: "https://github.com/grpc-ecosystem/grpc-gateway";
      description: "Find out more about EchoService";
    }
  };

  // Create a new ABitOfEverything
  //
  // This API creates a new ABitOfEverything
  rpc Create(ABitOfEverything) returns (ABitOfEverything) {
    option (google.api.http) = {
      post: "/v1/example/a_bit_of_everything/{float_value}/{double_value}/{int64_value}/separator/{uint64_value}/{int32_value}/{fixed64_value}/{fixed32_value}/{bool_value}/{string_value=strprefix/*}/{uint32_value}/{sfixed32_value}/{sfixed64_value}/{sint32_value}/{sint64_value}/{nonConventionalNameValue}/{enum_value}/{path_enum_value}/{nested_path_enum_value}/{enum_value_annotation}"
    };
  }
  rpc CreateBody(ABitOfEverything) returns (ABitOfEverything) {
    option (google.api.http) = {
      post: "/v1/example/a_bit_of_everything"
      body: "*"
    };
  }
}

OpenAPI v3

syntax = "proto3";

package tests.openapiv3annotations.message.v1;

import "google/api/annotations.proto";
import "openapiv3/annotations.proto";

option go_package = "github.com/google/gnostic/apps/protoc-gen-openapi/examples/tests/openapiv3annotations/message/v1;message";

option (openapi.v3.document) = {
  info: {
    title: "Title from annotation";
    version: "Version from annotation";
    description: "Description from annotation";
    contact: {
      name: "Contact Name";
      url: "https://github.com/google/gnostic";
      email: "gnostic@google.com";
    }
    license: {
      name: "Apache License";
      url: "https://github.com/google/gnostic/blob/master/LICENSE";
    }
  }
  components: {
    security_schemes: {
      additional_properties: [
        {
          name: "BasicAuth";
          value: {
            security_scheme: {
              type: "http";
              scheme: "basic";
            }
          }
        }
      ]
    }
  }
};

service Messaging1 {
  rpc UpdateMessage(Message) returns(Message) {
    option(google.api.http) = {
        patch: "/v1/messages/{message_id}"
        body: "*"
    };
    option(openapi.v3.operation) = {
        security: [
          {
            additional_properties: [
              {
                name: "BasicAuth";
                value: {
                  value: []
                }
              }
            ]
          }
        ]
    };
  }
}

service Messaging2 {
  rpc UpdateMessage(Message) returns (Message) {}
}

message Message {
  option (openapi.v3.schema) = {
    title: "This is an overridden message schema title";
  };

  int64 id = 1;
  string label = 2 [
    (openapi.v3.property) = {
      title: "this is an overriden field schema title";
      max_length: 255;
    }
  ];
}

管理生成API

Protobuf生成代码使用的工具是protoc，它是基于插件机制开发的，实际生成代码全靠插件，生成代码的命令如下所示：

生成 go 代码（struct和enum等基础类型）

protoc --proto_path=. --go_out=paths=source_relative:../ ./*.proto

生成 grpc 服务代码

protoc --proto_path=. --go-grpc_out=paths=source_relative:../ ./*.proto

生成 rest 服务代码

protoc --proto_path=. --go-http_out=paths=source_relative:../ ./*.proto

生成 gRPC状态码映射代码

protoc --proto_path=. --go-errors_out=paths=source_relative:../ ./*.proto

生成消息参数校验代码

protoc --proto_path=. --validate_out=paths=source_relative,lang=go:../ ./*.proto

生成 OpenAPI v2 json文档

protoc --proto_path=. --openapiv2_out=paths=source_relative:../ --openapiv2_opt logtostderr=true --openapiv2_opt json_names_for_fields=true ./*.proto

生成 OpenAPI v3 yaml文档

protoc --proto_path=. --openapi_out=naming=json=paths=source_relative:../ ./*.proto

插件生成文件一览表

插件名	生成文件名
[protoc-gen-go]	XXXXX.pb.go
[protoc-gen-go-grpc]	XXXXXX_grpc.pb.go
[protoc-gen-go-http]	XXXXXX_http.pb.go
[protoc-gen-go-errors]	XXXXXX_errors.pb.go
[protoc-gen-validate]	XXXXXX.pb.validate.go
[protoc-gen-openapiv2]	XXXXXX.swagger.json
[protoc-gen-openapi]	openapi.yaml

这里要提醒一下，细心的你一定会发现，生成OpenAPI文档的参数里面各有一个--openapiv2_opt json_names_for_fields=true和--openapi_out=naming=json，这两个参数的作用是一样的，那么它们是做什么用的呢？我们先来看下面这个消息定义：

// NonStandardMessageWithJSONNames maps odd field names to odd JSON names for maximum confusion.
message NonStandardMessageWithJSONNames {
  // Id represents the message identifier.
  string id = 1 [json_name = "ID"];
  int64 Num = 2 [json_name = "Num"];
  int64 line_num = 3 [json_name = "LineNum"];
  string langIdent = 4 [json_name = "langIdent"];
  string STATUS = 5 [json_name = "status"];
  int64 en_GB = 6 [json_name = "En_GB"];
  string no = 7 [json_name = "yes"];

  message Thing {
    message SubThing {
      string sub_value = 1 [json_name = "sub_Value"];
    }
    SubThing subThing = 1 [json_name = "SubThing"];
  }
  Thing thing = 8 [json_name = "Thingy"];
}

你一定发现了json_name这个参数，没错，就是为了它，proto那两个参数就是它的开关。如果，字段定义了json_name参数之后，REST的JSON字段名便会采用json_name所定义的字段名。这是一个非常有用的特性，因为前后端的命名规则不一致是常态，golang用的是驼峰命名法，而前端用蛇形命名法的是很多，这就可以用上了。

实施工程化

好，我们现在已经知道如何去生成API的代码和文档了。但是，这还远远不够。因为我们不可能每次都去手打命令生成代码，这是不科学，不人道的，不现实的。

我们需要工程化，使之可管理。CI/CD、自动化也能够实现。

首先，我们把可用的方法列举出来，然后再一个个的讲解各个方法：

BAT批处理脚本（Windows）或者Shell脚本（非Windows）；
Makefile；
go:generate注解；
buf.build。

结论在前：推荐使用buf.build

BAT批处理脚本（Windows）或者Shell脚本（非Windows）

BAT批处理脚本

:: generate go struct code
protoc --proto_path=. --go_out=paths=source_relative:../ ./*.proto
    
:: generate grpc service code
protoc --proto_path=. --go-grpc_out=paths=source_relative:../ ./*.proto
    
:: generate rest service code
protoc --proto_path=. --go-http_out=paths=source_relative:../ ./*.proto
    
:: generate kratos errors code
protoc --proto_path=. --go-errors_out=paths=source_relative:../ ./*.proto
    
:: generate message validator code
protoc --proto_path=. --validate_out=paths=source_relative,lang=go:../ ./*.proto
    
:: generate openapi v2 json doc
protoc --proto_path=. --openapiv2_out=paths=source_relative:../ --openapiv2_opt logtostderr=true --openapiv2_opt json_names_for_fields=true ./*.proto
    
:: generate openapi v3 yaml doc
protoc --proto_path=. --openapi_out=naming=json=paths=source_relative:../ ./*.proto

Shell脚本

#!/bin/bash

# generate go struct code
protoc --proto_path=. --go_out=paths=source_relative:../ ./*.proto
    
# generate grpc service code
protoc --proto_path=. --go-grpc_out=paths=source_relative:../ ./*.proto
    
# generate rest service code
protoc --proto_path=. --go-http_out=paths=source_relative:../ ./*.proto
    
# generate kratos errors code
protoc --proto_path=. --go-errors_out=paths=source_relative:../ ./*.proto
    
# generate message validator code
protoc --proto_path=. --validate_out=paths=source_relative,lang=go:../ ./*.proto
    
# generate openapi v2 json doc
protoc --proto_path=. --openapiv2_out=paths=source_relative:../ --openapiv2_opt logtostderr=true --openapiv2_opt json_names_for_fields=true ./*.proto
    
# generate openapi v3 yaml doc
protoc --proto_path=. --openapi_out=naming=json=paths=source_relative:../ ./*.proto

这个方法除了能用，没有别的好处了。它需要在每一组proto文件的同级目录下都冗余放一对脚本，如果要执行所有的生成脚本，另外还需要写一个脚本来调用生成脚本，维护起来很痛苦。

2. Makefile

Kratos官方layout就是使用的Makefile的方法来生成代码的。

它在根目录下的Makefile文件里：

.PHONY: api
# generate api proto
api:
    protoc --proto_path=./api \
           --proto_path=./third_party \
            --go_out=paths=source_relative:./api \
            --go-http_out=paths=source_relative:./api \
            --go-grpc_out=paths=source_relative:./api \
           --openapi_out=fq_schema_naming=true,default_response=false:. \
           $(API_PROTO_FILES)

.PHONY: conf
# generate config define code
conf:
    protoc --proto_path=. \
           --proto_path=../../../third_party \
           --go_out=paths=source_relative:. \
           ./internal/conf/*.proto

根目录下的Makefile由app\{服务名}\service\Makefile引用，调用者在服务目录app\{服务名}\service\下调用make api执行代码生成。

这个方法很有局限性，掣手掣脚，你只能够依照严格的固定的项目结构来，只要有一些变动就完犊子了。

MonoRepo的项目结构下，因为会有多个Makefile入口，所以没办法一键执行全部的Makefile，必须借助第三方工具，比如Shell脚本。偷懒如我，总觉得很麻烦。

3. go:generate注解

go1.4版本之后，可以通过go generate命令执行一些go:generate注解下的预处理命令，可以拿来生成API代码之用。因为在非Windows系统下，命令如果带通配符，会执行出错，需要加sh -c才行，而Windows系统不存在这样的问题，可以直接执行，所以需要使用go:build注解来区分操作系统，go generate命令会根据操作系统执行相对应的go代码文件。所以，我写了两个go文件：

generate_windows.go

//go:build windows

// generate go struct code
//go:generate protoc --proto_path=. --go_out=paths=source_relative:../ ./*.proto

// generate grpc service code
//go:generate protoc --proto_path=. --go-grpc_out=paths=source_relative:../ ./*.proto

// generate rest service code
//go:generate protoc --proto_path=. --go-http_out=paths=source_relative:../ ./*.proto

// generate kratos errors code
//go:generate protoc --proto_path=. --go-errors_out=paths=source_relative:../ ./*.proto

// generate message validator code
//go:generate protoc --proto_path=. --validate_out=paths=source_relative,lang=go:../ ./*.proto

// generate openapi v2 json doc
//go:generate protoc --proto_path=. --openapiv2_out=paths=source_relative:../ --openapiv2_opt logtostderr=true --openapiv2_opt json_names_for_fields=true ./*.proto

// generate openapi v3 yaml doc
//go:generate protoc --proto_path=. --openapi_out=naming=json=paths=source_relative:../ ./*.proto

package api

generate_xnix.go

//go:build !windows
// +build !windows

// generate go struct code
//go:generate sh -c "protoc --proto_path=. --go_out=paths=source_relative:../ ./*.proto"

// generate grpc service code
//go:generate sh -c "protoc --proto_path=. --go-grpc_out=paths=source_relative:../ ./*.proto"

// generate rest service code
//go:generate sh -c "protoc --proto_path=. --go-http_out=paths=source_relative:../ ./*.proto"

// generate kratos errors code
//go:generate sh -c "protoc --proto_path=. --go-errors_out=paths=source_relative:../ ./*.proto"

// generate message validator code
//go:generate sh -c "protoc --proto_path=. --validate_out=paths=source_relative,lang=go:../ ./*.proto"

// generate openapi v2 json doc
//go:generate sh -c "protoc --proto_path=. --openapiv2_out=paths=source_relative:../ --openapiv2_opt logtostderr=true --openapiv2_opt json_names_for_fields=true ./*.proto"

// generate openapi v3 yaml doc
//go:generate sh -c "protoc --proto_path=. --openapi_out=naming=json=paths=source_relative:../ ./*.proto"

package api

它可以很好的完成生成代码的任务。主流的IDE（Goland、VSC）都可以很好的支持编辑界面执行注解。

要自动化吧，也能实现，只要在项目根目录执行go generate ./...就能够执行整个项目的go:generate注解。

但是，有一个很大的问题，它需要在每一组proto文件的同级目录下冗余一套go代码，维护起来就比较糟心了。

4. buf.build

buf.build是专门编译管理protobuf API的工具。

它总共有3组配置文件：buf.work.yaml、buf.gen.yaml、buf.yaml。

另外，还有一个buf.lock文件，但是它不需要进行人工配置，它是由buf mod update命令所生成。这跟前端的npm、yarn等的lock文件差不多，golang的go.sum也差不多。

它的配置文件不多，也不复杂，维护起来非常方便，支持远程proto插件，支持远程第三方proto。对构建系统Bazel支持很好，对CI/CD系统也支持得很好。它还有很多优秀的特性。

buf.build非常棒，用它，很方便。值得使用，值得推荐。

buf.work.yaml

它一般放在项目的根目录下面，它代表的是一个工作区，通常一个项目也就一个该配置文件。

该配置文件最重要的就是directories配置项，列出了要包含在工作区中的模块的目录。目录路径必须相对于buf.work.yaml，像../external就是一个无效的配置。

version: v1
directories:
  - api
  - third_party

buf.gen.yaml

它一般放在buf.work.yaml的同级目录下面，它主要是定义一些protoc生成的规则和插件配置。

# 配置protoc生成规则
version: v1
managed:
  enabled: false
plugins:
  # generate go struct code
  - name: go
    out: gen/api/go
    opt: paths=source_relative
  # generate grpc service code
  - name: go-grpc
    out: gen/api/go
    opt:
      - paths=source_relative
  # generate rest service code
  - name: go-http
    out: gen/api/go
    opt:
      - paths=source_relative
  # generate kratos errors code
  - name: go-errors
    out: gen/api/go
    opt:
      - paths=source_relative
  # generate message validator code
  - name: validate
    out: gen/api/go
    opt:
      - paths=source_relative
      - lang=go

buf.yaml

它放置的路径，你可以视之为protoc的--proto-path参数指向的路径，也就是proto文件里面import的相对路径。

需要注意的是，buf.work.yaml的同级目录必须要放一个该配置文件。

该配置文件的内容通常来说都是下面这个配置，不需要做任何修改，需要修改的情况不多。

version: v1
deps:
breaking:
  use:
    - FILE
lint:
  use:
    - DEFAULT

生成代码

我有开源了一个Kratos的CMS项目kratos-blog，它是一个MonoRepo结构的项目，我们以它的项目结构来做讲解。

.
├── buf.work.yaml
├── buf.gen.yaml
├── buf.yaml
├── buf.lock
├── api
│   ├── admin
│   │   └── service
│   │       └── v1
│   │           └── admin_errors.proto
│   │           └── buf.openapi.gen.yaml
│   │           └── i_user.proto
│   └── buf.yaml
└── third_party
    ├── errors
    │   └── errors.proto
    ├── google
    ├── openapiv3
    ├── protoc-gen-openapiv2
    ├── validate
    └── buf.yaml

大家可以看到，我只在根目录、api、third_party放了3个buf.yaml，整体需求的配置文件并不多。

buf.build使用buf generate命令进行构建，调用该命令必须在buf.work.yaml的同级目录下。执行了buf generate命令之后，将会在根目录下产生一个gen/api/go的文件夹，生成的代码都将被放在了这个目录下。

细心的你肯定早就发现了在api/admin/service/v1下面有一个buf.openapi.gen.yaml的配置文件，这是什么配置文件呢？我现在把该配置文件放出来：

# 配置protoc生成规则
version: v1
managed:
  enabled: false
plugins:
  # generate openapi v2 yaml doc
  - name: openapi
    out: gen/api/go/admin/service/v1
    opt:
      - naming=json
      - paths=source_relative

没错，它是为了生成OpenAPI v3文档。我之前尝试了放在根目录下的buf.gen.yaml，但是产生了错误，因为OpenAPI v3文档，它全局只能产生一个openapi.yaml文件。所以，没辙，只能单独对待了。那么，怎么使用这个配置文件呢？还是使用buf generate命令，但是得带参数：

buf generate --path api/admin/service/v1 --template api/admin/service/v1/buf.openapi.gen.yaml

该命令还是在项目根目录下执行。

与前端协同

与前端协同，全靠一点：OpenAPI。前端只要拿到了OpenAPI的文档，他就可以开始上手干活了。

在这里，我只介绍两个工具的使用：

Apifox
pbts

Apifox

我在前面提到的那些支持OpenAPI的工具，随便拿出来一样都很好使。但本文只介绍国产神器Apifox。

为什么要推荐它呢？有这么几点让我很爽：

可以方便的导入导出OpenAPI文档；
可以不需要配置Mock就可以使用MockServer，大部分的字段其实都不需要格外去配置，需要配置的字段其实只有微乎其微，而且就算是配置起来也很容易，这极大的提高了开发效率；
MockServer支持本地和云端，当团队成员在异地的时候，当我们需要向客户或者领导演示的时候，云端Mock都很好使；
同时还支持自动化测试。

导入OpenAPI是很简单的，它支持手动和自动，手动就是自己拖动OpenAPI文档进来，一次性导入；自动就是通过url自动导入，它会定时导入，这样接口修改了也不用管了，像不像导弹的射后不管？

手动导入的界面如下：

自动导入的界面如下：

pbts

pbts是protobuf.js提供的一个Protobuf转Typescript的工具。

对于自由惯了的前端程序员来说，这会让他很不解，难受，觉得束手束脚的——都已经有了OpenAPI了，还要这个作甚？

要的就是约束。

这么一个场景，我有一个协议做了修改，字段增删改了，但是，我代码里面依赖这个协议的地方很多，如果没有这个约束，改变了IDE也没有办法感知到，现在有了约束之后，IDE立马就可以感知到，并且提醒给前端程序员，循着这个提示去修改代码就变得很轻松了，不至于让一些隐藏很深的bug隐匿在深处，寻，也寻不到。

pbts的功能其实还很不够，比如，无法把REST的路径导出。比如，生成协议的REST客户端代码。如果有这样一个工具，必将事半功倍。

pbts命令的使用非常简单，就是只能一次处理一个proto，需要写一个脚本才好：

pbts convert -i ./admin.proto -o ts/admin.d.ts

Kratos微服务框架API工程化指南

Kratos微服务框架API工程化指南

工具安装

安装 protoc

goctl一键安装

macOS安装

Ubuntu安装

非Windows系统源代码安装

非Windows系统源二进制文件安装

Windows安装

后端工具

前端工具

设计API

CURD

Kratos Errors

Message Validator

OpenAPI

管理生成API

实施工程化

BAT批处理脚本（Windows）或者Shell脚本（非Windows）

2. Makefile

3. go:generate注解

4. buf.build

buf.work.yaml

buf.gen.yaml

buf.yaml

生成代码

与前端协同

Apifox

pbts

参考资料

微服务

热门文章

最新文章

相关课程

相关电子书

相关实验场景