マイクロサービスの相互作用のフレームワークとしてのGo-swagger

NickNameこんにちは！プログラマーでマイクロサービスアーキテクチャを使用している場合は、サービスAと新しいまだ不明なサービスBとの相互作用を構成する必要があると想像してください。最初に何をしますか？



さまざまな企業の100人のプログラマーにこの質問をすると、100の異なる回答が得られる可能性があります。誰かが契約をスワッガーで説明し、gRPCの誰かが、契約を説明せずに単にクライアントをサービスに誘導します。そして誰かがJSONをgoogleokに保存することさえあります：D。ほとんどの企業は、いくつかの歴史的要因、能力、テクノロジースタックなどに基づいて、サービス間相互作用に対する独自のアプローチを開発しています。 Delivery Clubのサービスがどのように相互に通信し、なぜそのような選択をしたのかをお話ししたいと思います。そして最も重要なことは、時間の経過とともにドキュメントの関連性をどのように確保するかです。たくさんのコードがあります！



また会ったね！私の名前はセルゲイ・ポポフです。アプリとデリバリークラブのウェブサイトでレストランの検索結果を担当するチームのチームリーダーであり、Goの社内開発ギルドの積極的なメンバーでもあります（これについては後で話しますが、今は話しません）。



すぐに予約します。主に囲碁で書かれたサービスについて話します。PHPサービスのコード生成はまだ実装していませんが、異なる方法でアプローチの均一性を実現しています。



最終的にやりたかったこと：

1. サービス契約が最新であることを確認してください。これにより、新しいサービスの導入がスピードアップし、チーム間のコミュニケーションが容易になります。
2. サービス間のHTTPを介した相互作用の統一された方法を考えてみましょう（現時点では、キューやイベントストリーミングを介した相互作用については考慮しません）。
3. サービス契約を扱うアプローチを標準化する。
4. あらゆる種類の合流点のドックを探さないように、契約の単一のリポジトリを使用します。
5. 理想的には、さまざまなプラットフォーム用のクライアントを生成します。

上記のすべてから、Protobufは契約を説明するための統一された方法として思い浮かびます。優れたツールがあり、さまざまなプラットフォーム用のクライアントを生成できます（第5項）。しかし、明らかな欠点もあります。多くの場合、gRPCは新しい未知のものであり、これにより実装が非常に複雑になります。もう1つの重要な要素は、会社が長い間「仕様優先」アプローチを採用しており、すべてのサービスのドキュメントがスワッガーまたはRAMLの説明の形式ですでに存在していたことです。

ゴースワッガー

偶然にも、同時に、私たちは会社でGoを採用し始めました。したがって、次に検討する候補はgo-swaggerでした。これは、swagger仕様からクライアントとサーバーコードを生成できるツールです。明らかな欠点は、Goのコードしか生成しないことです。実際、goshコード生成を使用し、go-swaggerを使用するとテンプレートを柔軟に操作できるため、理論的にはPHPコードの生成に使用できますが、まだ試していません。



Go-swaggerは、トランスポートレイヤーの生成だけではありません。実際、それはアプリケーションスケルトンを生成します。ここで、DCの開発文化について少し触れておきたいと思います。内部ソースがあります。つまり、どのチームのどの開発者も、私たちが持っているすべてのサービスへのプルリクエストを作成できます。このようなスキームが機能するために、開発におけるアプローチを標準化しようとしています。一般的な用語、ロギング、メトリック、依存関係の操作、そしてもちろんプロジェクト構造への単一のアプローチを使用します。



このように、go-swaggerを実装することにより、Goでサービスを開発するための標準を導入しています。これは、当初は予期していなかった目標に向けたもう1つのステップですが、開発全般にとって重要です。

最初のステップ

だから、行く-闊歩は、私たちのほとんどカバーすることができるように思われる興味深い候補であることが判明したかったの要件を。

注：すべての更なるコードはバージョン0.24.0に関連する、インストール手順はで見つけることができる例で私たちのリポジトリ、および公式サイトでは、現在のバージョンのインストール手順について説明しています。

彼に何ができるか見てみましょう。スワガースペックを取り、サービスを生成しましょう：

> goswagger generate server \
    --with-context -f ./swagger-api/swagger.yml \
    --name example1

以下を取得しました：







Makefileとgo.mod私はすでに自分で作成しました。



実際、swaggerで説明されているリクエストを処理するサービスになりました。

> go run cmd/example1-server/main.go
2020/02/17 11:04:24 Serving example service at http://127.0.0.1:54586
 
 
 
> curl http://localhost:54586/hello -i
HTTP/1.1 501 Not Implemented
Content-Type: application/json
Date: Sat, 15 Feb 2020 18:14:59 GMT
Content-Length: 58
Connection: close
 
"operation hello HelloWorld has not yet been implemented"

ステップ2。テンプレーティングを理解する

明らかに、私たちが生成したコードは、私たちが運用中に見たいものとはかけ離れています。



アプリケーションの構造に求めるもの：

• アプリケーションを構成できます。データベースに接続するための設定を転送したり、HTTP接続のポートを指定したりできます。
• アプリケーションの状態、データベース接続などを格納するアプリケーションオブジェクトを選択します。
• アプリケーションのハンドラー関数を作成します。これにより、コードの作業が簡素化されます。
• メインファイルの依存関係を初期化します（この例では、これは発生しませんが、それでも必要です。

新しい問題を解決するために、いくつかのテンプレートをオーバーライドできます。これを行うには、私が行ったように（Github）、次のファイルについて説明します。サービスを生成するための







テンプレートファイル（`*.gotmpl`）と構成用のファイル（）を説明する必要があり`*.yml`ます。



次に、私が作成したテンプレートを順番に分析します。ゴー闊歩ドキュメントはかなりたとえば、詳述されているので、私は、彼らと協力に深く潜るませんここにある設定ファイルの記述が。Go-templatingが使用されていることに注意してください。これについて既に経験がある場合、またはHELM構成について説明する必要がある場合は、それを理解するのは難しくありません。

アプリケーションの構成

config.gotmplには、1つのパラメーター（アプリケーションが着信HTTP要求をリッスンするポート）を持つ単純な構造が含まれています。またInitConfig、環境変数を読み取り、この構造を埋める関数も作成しました。main.goから呼び出すのでInitConfig、パブリック関数にしました。

package config
 
import (
    "github.com/pkg/errors"
    "github.com/vrischmann/envconfig"
)
 
// Config struct
type Config struct {
    HTTPBindPort int `envconfig:"default=8001"`
}
 
// InitConfig func
func InitConfig(prefix string) (*Config, error) {
    config := &Config{}
    if err := envconfig.InitWithPrefix(config, prefix); err != nil {
        return nil, errors.Wrap(err, "init config failed")
    }
 
    return config, nil
}

このテンプレートをコードの生成時に使用するには、YML構成でテンプレートを指定する必要があります。

layout:
  application:
    - name: cfgPackage
      source: serverConfig
      target: "./internal/config/"
      file_name: "config.go"
      skip_exists: false

パラメータについて少し説明します。

• name -純粋に有益な機能があり、生成には影響しません。
• source-実際には、camelCaseのテンプレートファイルへのパス、つまり serverConfigは./server/config.gotmplと同等です。
• target-生成されたコードが保存されるディレクトリ。ここでは、テンプレートを使用してパスを動的に生成できます（例）。
• file_name -生成されたファイルの名前。ここではテンプレートを使用することもできます。
• skip_exists-ファイルが1回だけ生成され、既存のファイルを上書きしないことを示します。構成ファイルはアプリケーションの成長に応じて変更され、生成されたコードに依存するべきではないため、これは私たちにとって重要です。

コード生成構成では、オーバーライドするファイルだけでなく、すべてのファイルを指定する必要があります。変更しないファイルの場合、たとえば、ここでsource指摘する意味の範囲内で：。ちなみに、オリジナルのテンプレートをご覧になりたい方はこちら。asset:< >asset:serverConfigureapi

アプリケーションオブジェクトとハンドラー

状態やデータベース接続などを保存するためのアプリケーションオブジェクトについては説明しません。すべてが作成したばかりの構成に似ています。しかし、ハンドラーを使用すると、すべてがもう少し興味深いものになります。私たちの主な目標は、仕様にURLを追加するときに別のファイルにスタブ関数を作成することです。最も重要なことは、サーバーがこの関数を呼び出して要求を処理することです。



関数テンプレートとスタブについて説明しましょう。

package app
 
import (
    api{{ pascalize .Package }} "{{.GenCommon.TargetImportPath}}/{{ .RootPackage }}/operations/{{ .Package }}"
    "github.com/go-openapi/runtime/middleware"
)
 
func (srv *Service){{ pascalize .Name }}Handler(params api{{ pascalize .Package }}.{{ pascalize .Name }}Params{{ if .Authorized }}, principal api{{ .Package }}.{{ if not ( eq .Principal "interface{}" ) }}*{{ end }}{{ .Principal }}{{ end }}) middleware.Responder {
    return middleware.NotImplemented("operation {{ .Package }} {{ pascalize .Name }} has not yet been implemented")
}

例を詳しく見てみましょう。

• pascalize--CamelCase（他の機能の説明はこちら）で一線を画します。
• .RootPackage -生成されたWebサーバーパッケージ。
• .Package-生成されたコード内のパッケージの名前。HTTP要求と応答に必要なすべての構造を記述します。構造。たとえば、リクエスト本文の構造やレスポンス構造などです。
• .Name-ハンドラーの名前。指定されている場合は、仕様のoperationIDから取得されます。operationIDより明白な結果を得るために、常に指定することをお勧めします。

ハンドラーの構成は次のとおりです。

layout:
  operations:
    - name: handlerFns
      source: serverHandler
      target: "./internal/app"
      file_name: "{{ (snakize (pascalize .Name)) }}.go"
      skip_exists: true

ご覧のとおり、ハンドラーコードは上書きされず（skip_exists: true）、ファイル名はハンドラー名から生成されます。



さて、スタブ関数がありますが、Webサーバーは、これらの関数を使用して要求を処理する必要があることをまだ認識していません。main.goでこれを修正しました（コード全体を提供するわけではありません。完全版はここにあります）：

package main
 
{{ $name := .Name }}
{{ $operations := .Operations }}
import (
    "fmt"
    "log"
 
    "github.com/delivery-club/go-swagger-example/{{ dasherize .Name }}/internal/generated/restapi"
    "github.com/delivery-club/go-swagger-example/{{ dasherize .Name }}/internal/generated/restapi/operations"
    {{range $index, $op := .Operations}}
        {{ $found := false }}
        {{ range $i, $sop := $operations }}
            {{ if and (gt $i $index ) (eq $op.Package $sop.Package)}}
                {{ $found = true }}
            {{end}}
        {{end}}
        {{ if not $found }}
        api{{ pascalize $op.Package }} "{{$op.GenCommon.TargetImportPath}}/{{ $op.RootPackage }}/operations/{{ $op.Package }}"
        {{end}}
    {{end}}
 
    "github.com/go-openapi/loads"
    "github.com/vrischmann/envconfig"
 
    "github.com/delivery-club/go-swagger-example/{{ dasherize .Name }}/internal/app"
)
 
func main() {
    ...
    api := operations.New{{ pascalize .Name }}API(swaggerSpec)
 
    {{range .Operations}}
    api.{{ pascalize .Package }}{{ pascalize .Name }}Handler = api{{ pascalize .Package }}.{{ pascalize .Name }}HandlerFunc(srv.{{ pascalize .Name }}Handler)
    {{- end}}
    ...
}

インポートのコードは複雑に見えますが、実際にはGo-templatingとgo-swaggerリポジトリからの構造にすぎません。また、関数でmainは、生成された関数をハンドラーに割り当てるだけです。



構成を示すコードを生成する必要があります。

> goswagger generate server \
        -f ./swagger-api/swagger.yml \
        -t ./internal/generated -C ./swagger-templates/default-server.yml \
        --template-dir ./swagger-templates/templates \
        --name example2

最終結果は、リポジトリで表示できます。



私たちが得たもの：

• アプリケーション、構成、および必要なものに構造を使用できます。最も重要なことは、生成されたコードに埋め込むのがかなり簡単なことです。
• 個々のファイルの名前に至るまで、プロジェクトの構造を柔軟に管理できます。
• テンプレーティングは複雑に見え、慣れるまでに時間がかかりますが、全体としては非常に強力なツールです。

ステップ3。クライアントの生成

Go-swaggerを使用すると、他のGoサービスが使用できるサービスのクライアントパッケージを生成することもできます。ここでは、コード生成について詳しくは説明しません。アプローチは、サーバー側のコードを生成する場合とまったく同じです。



Goプロジェクトの場合、パブリックパッケージをに入れるのが通例./pkgです。同じことを行います。サービスのクライアントをpkgに入れ、次のようにコード自体を生成します。

> goswagger generate client -f ./swagger-api/swagger.yml -t ./pkg/example3

生成されたコードの例はここにあります。



これで、サービスのすべての利用者は、たとえばタグを使用して、このクライアントを自分でインポートできます（私の例では、タグはになりますexample3/pkg/example3/v0.0.1）。



クライアントテンプレートは、たとえば、open tracing idコンテキストからヘッダーへのフローにカスタマイズできます。

結論

当然、内部実装は、主に内部パッケージの使用とCIへのアプローチ（さまざまなテストとリンターの実行）が原因で、ここに示されているコードとは異なります。箱から出して生成されたコードでは、技術メトリックの収集、構成の操作、およびロギングが構成されています。すべての一般的なツールを標準化しました。このため、開発全般、特に新しいサービスのリリースを簡素化し、製品に展開する前にサービスチェックリストをより迅速に通過できるようにしました。



最初の目標を達成したかどうかを確認しましょう。

1. サービスについて説明されている契約の関連性を確認します。これにより、新しいサービスの導入が加速され、チーム間のコミュニケーションが簡素化されます-はい。
2. HTTP ( event streaming) — .
3. , .. Inner Source — .
4. , — ( — Bitbucket).
5. , — ( , , ).
6. Go — ( ).

注意深い読者はおそらくすでに質問をしているでしょう：テンプレートファイルはどのように私たちのプロジェクトに入るのですか？現在、各プロジェクトにそれらを保存しています。これにより、日常の作業が簡素化され、特定のプロジェクトに合わせて何かをカスタマイズできます。しかし、コインには別の側面があります。主にCIに関連する、テンプレートの集中更新と新機能の提供のためのメカニズムがありません。



PSこの資料が気に入った場合は、将来、サービスの標準アーキテクチャに関する記事を作成し、Goでサービスを開発するときに使用する原則について説明します。