Go-swagger comme cadre d'interaction avec les microservices

Bonjour NickName! Si vous êtes programmeur et travaillez avec une architecture de microservices, imaginez que vous devez configurer l'interaction de votre service A avec un nouveau service B encore inconnu. Que ferez-vous en premier?



Si vous posez cette question à 100 programmeurs d'entreprises différentes, nous obtiendrons probablement 100 réponses différentes. Quelqu'un décrit les contrats avec fanfaron, quelqu'un dans gRPC fait simplement des clients à leurs services sans décrire un contrat. Et quelqu'un stocke même JSON dans un googleok: D. La plupart des entreprises développent leur propre approche de l'interaction interservices en fonction de certains facteurs historiques, compétences, pile technologique, etc. Je veux vous dire comment les services de Delivery Club communiquent entre eux et pourquoi nous avons fait un tel choix. Et surtout, comment nous assurons la pertinence de la documentation dans le temps. Il y aura beaucoup de code!



Re-bonjour! Je m'appelle Sergey Popov, je suis le chef d'équipe de l'équipe responsable des résultats de recherche des restaurants dans les applications et sur le site du Delivery Club, et également un membre actif de notre guilde de développement interne à Go (nous en parlerons peut-être plus tard, mais pas maintenant).



Je vais faire une réservation tout de suite, nous parlerons principalement des services écrits en Go. Nous n'avons pas encore implémenté la génération de code pour les services PHP, bien que nous y parvenions d'une manière différente dans les approches.



Ce que nous voulions aboutir:

1. Assurez-vous que les contrats de service sont à jour. Cela devrait accélérer l'introduction de nouveaux services et faciliter la communication entre les équipes.
2. Arrivez à une méthode unifiée d'interaction via HTTP entre les services (nous ne considérerons pas les interactions via les files d'attente et le streaming d'événements pour le moment).
3. Standardiser l'approche du travail avec les contrats de service.
4. Utilisez un référentiel unique de contrats afin de ne pas chercher des quais pour toutes sortes de confluences.
5. Idéalement, générez des clients pour différentes plates-formes.

De tout ce qui précède, Protobuf vient à l'esprit comme une manière unifiée de décrire les contrats. Il dispose de bons outils et peut générer des clients pour différentes plateformes (notre clause 5). Mais il y a aussi des inconvénients évidents: pour beaucoup, gRPC reste quelque chose de nouveau et d'inconnu, ce qui compliquerait grandement sa mise en œuvre. Un autre facteur important était que la société avait depuis longtemps adopté l'approche «la spécification d'abord» et que la documentation existait déjà pour tous les services sous la forme d'un swagger ou d'une description RAML.

Go-swagger

Par coïncidence, en même temps, nous avons commencé à adapter Go dans l'entreprise. Par conséquent, notre prochain candidat à considérer était go-swagger - un outil qui vous permet de générer des clients et du code serveur à partir de la spécification swagger. L'inconvénient évident est qu'il génère uniquement du code pour Go. En fait, il utilise la génération de code gosh, et go-swagger permet un travail flexible avec des modèles, donc en théorie, il peut être utilisé pour générer du code PHP, mais nous ne l'avons pas encore essayé.



Go-swagger ne concerne pas uniquement la génération de couches de transport. En fait, il génère le squelette de l'application, et ici je voudrais parler un peu de la culture du développement dans DC. Nous avons Inner Source, ce qui signifie que tout développeur de n'importe quelle équipe peut créer une pull request vers n'importe quel service que nous avons. Pour qu'un tel schéma fonctionne, nous essayons de standardiser les approches de développement: nous utilisons une terminologie commune, une approche unique de la journalisation, des métriques, du travail avec les dépendances et, bien sûr, de la structure du projet.



Ainsi, en implémentant go-swagger, nous introduisons un standard pour le développement de nos services en Go. C'est un autre pas vers nos objectifs, auquel nous ne nous attendions pas au départ, mais qui est important pour le développement en général.

Les premiers pas

Donc, go-swagger s'est avéré être un candidat intéressant qui semble être en mesure de couvrir la plupart de nos besoins recherchés .

Remarque: tous les autres codes sont pertinents pour la version 0.24.0, les instructions d'installation peuvent être consultées dans notre référentiel avec des exemples , et le site officiel contient des instructions pour installer la version actuelle.

Voyons ce qu'il peut faire. Prenons une spécification swagger et générons un service:

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

Nous avons obtenu ce qui suit:







Makefile et go.mod que j'ai déjà créés moi-même.



En fait, nous nous sommes retrouvés avec un service qui traite les requêtes décrites dans 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"

Deuxième étape. Comprendre la création de modèles

Evidemment, le code que nous avons généré est loin de ce que nous voulons voir en fonctionnement.



Ce que nous attendons de la structure de notre application:

• Être capable de configurer l'application: transférez les paramètres de connexion à la base de données, spécifiez le port des connexions HTTP, etc.
• Sélectionnez un objet d'application qui stockera l'état de l'application, la connexion à la base de données, etc.
• Rendre les fonctions des gestionnaires de notre application, cela devrait simplifier le travail avec le code.
• Initialisez les dépendances dans le fichier principal (dans notre exemple, cela ne se produira pas, mais nous voulons toujours cela.

Pour résoudre de nouveaux problèmes, nous pouvons remplacer certains modèles. Pour ce faire, nous allons décrire les fichiers suivants, comme je l'ai fait ( Github ):







Nous devons décrire les fichiers de modèle ( `*.gotmpl`) et le fichier de configuration ( `*.yml`) de génération de notre service.



Ensuite, dans l'ordre, nous analyserons les modèles que j'ai créés. Je ne vais pas approfondir leur travail avec eux, car la documentation de go-swagger est assez détaillée, par exemple, voici la description du fichier de configuration. Je noterai seulement que Go-templating est utilisé, et si vous avez déjà de l'expérience avec cela ou avez dû décrire des configurations HELM, il ne sera pas difficile de le comprendre.

Configuration de l'application

config.gotmpl contient une structure simple avec un paramètre - le port que l'application écoutera pour les requêtes HTTP entrantes. J'ai également créé une fonction InitConfigqui lira les variables d'environnement et remplira cette structure. Je l'appellerai depuis main.go, donc j'en ai InitConfigfait une fonction publique.

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
}

Pour que ce modèle soit utilisé lors de la génération de code, vous devez le spécifier dans la configuration YML :

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

Je vais vous parler un peu des paramètres:

• name - a une fonction purement informative et n'affecte pas la génération.
• source- en fait le chemin vers le fichier modèle dans camelCase, c'est-à-dire serverConfig équivaut à ./server/config.gotmpl .
• target- répertoire dans lequel le code généré sera sauvegardé. Ici, vous pouvez utiliser la création de modèles pour générer dynamiquement un chemin ( exemple ).
• file_name - le nom du fichier généré, ici vous pouvez également utiliser la création de modèles.
• skip_exists- un signe que le fichier ne sera généré qu'une seule fois et n'écrasera pas l'existant. Ceci est important pour nous, car le fichier de configuration changera à mesure que l'application se développera et ne devrait pas dépendre du code généré.

Dans la configuration de génération de code, vous devez spécifier tous les fichiers, et pas seulement ceux que nous voulons remplacer. Pour les fichiers que nous ne changeons pas, au sens du sourcepoint de sortie asset:< >, par exemple, ici : asset:serverConfigureapi. À propos, si vous souhaitez consulter les modèles originaux, ils sont ici .

Objet d'application et gestionnaires

Je ne décrirai pas l'objet d'application pour stocker l'état, les connexions à la base de données et autres choses, tout est similaire à la configuration que vous venez de créer. Mais avec les gestionnaires, tout est un peu plus intéressant. Notre objectif principal est de créer une fonction de stub dans un fichier séparé lorsque nous ajoutons une URL à la spécification, et surtout, que notre serveur appelle cette fonction pour traiter la demande.



Décrivons le modèle de fonction et les stubs:

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")
}

Regardons un peu un exemple:

• pascalize- apporte une ligne avec CamelCase (description des autres fonctions ici ).
• .RootPackage - package de serveur Web généré.
• .Package- le nom du package dans le code généré, qui décrit toutes les structures nécessaires pour les requêtes et réponses HTTP, i.e. structures. Par exemple, une structure pour le corps de la requête ou une structure de réponse.
• .Name- le nom du gestionnaire. Il est extrait de l' ID d'opération dans la spécification, s'il est spécifié. Je recommande de toujours spécifier operationIDpour un résultat plus évident.

La configuration du gestionnaire est la suivante:

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

Comme vous pouvez le voir, le code du gestionnaire ne sera pas écrasé ( skip_exists: true) et le nom du fichier sera généré à partir du nom du gestionnaire.



D'accord, il y a une fonction stub, mais le serveur Web ne sait pas encore que ces fonctions devraient être utilisées pour traiter les demandes. J'ai corrigé cela dans main.go (je ne donnerai pas le code complet, la version complète peut être trouvée ici ):

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}}
    ...
}

Le code de l'importation semble compliqué, même s'il ne s'agit en réalité que de modèles Go et de structures du référentiel go-swagger. Et dans une fonction, mainnous affectons simplement nos fonctions générées aux gestionnaires.



Il reste à générer le code indiquant notre configuration:

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

Le résultat final peut être consulté dans notre référentiel .



Ce que nous avons:

• Nous pouvons utiliser nos structures pour l'application, les configurations et tout ce que nous voulons. Plus important encore, il est assez facile de l'intégrer dans le code généré.
• Nous pouvons gérer de manière flexible la structure du projet, jusqu'aux noms des fichiers individuels.
• La création de modèles semble complexe et nécessite un certain temps pour s'y habituer, mais dans l'ensemble, c'est un outil très puissant.

Troisième étape. Générer des clients

Go-swagger nous permet également de générer un package client pour notre service que d'autres services Go peuvent utiliser. Ici, je ne m'attarderai pas sur la génération de code en détail, l'approche est exactement la même que lors de la génération de code côté serveur.



Pour les projets Go, il est d'usage de mettre des packages publics ./pkg, nous ferons la même chose: mettre le client de notre service dans pkg, et générer le code lui-même comme suit:

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

Un exemple du code généré est ici .



Désormais, tous les consommateurs de notre service peuvent importer ce client pour eux-mêmes, par exemple, par tag (pour mon exemple, le tag sera example3/pkg/example3/v0.0.1).



Les modèles clients peuvent être personnalisés pour, par exemple, passer open tracing iddu contexte à l'en-tête.

conclusions

Naturellement, notre implémentation interne diffère du code présenté ici principalement en raison de l'utilisation de packages internes et d'approches de CI (exécution de divers tests et linters). Dans le code généré prêt à l'emploi, la collecte de métriques techniques, le travail avec les configurations et la journalisation sont configurés. Nous avons standardisé tous les outils courants. De ce fait, nous avons simplifié le développement en général et la sortie de nouveaux services en particulier, assuré un passage plus rapide de la liste de contrôle des services avant le déploiement sur le produit.



Vérifions si les objectifs d'origine ont été atteints:

1. Assurer la pertinence des contrats décrits pour les services, cela devrait accélérer l'introduction de nouveaux services et simplifier la communication entre les équipes - Oui .
2. HTTP ( event streaming) — .
3. , .. Inner Source — .
4. , — ( — Bitbucket).
5. , — ( , , ).
6. Go — ( ).

Le lecteur attentif a probablement déjà posé la question: comment les fichiers modèles entrent-ils dans notre projet? Nous les stockons désormais dans chacun de nos projets. Cela simplifie le travail quotidien, vous permet de personnaliser quelque chose pour un projet spécifique. Mais il y a un autre aspect de la médaille: il n'y a pas de mécanisme de mise à jour centralisée des modèles et de livraison de nouvelles fonctionnalités, principalement liées à l'IC.



PS Si vous aimez ce matériel, nous préparerons à l'avenir un article sur l'architecture standard de nos services, nous vous indiquerons les principes que nous utilisons lors du développement de services dans Go.