👊🏽 ✋🏽 🤸 Interface de génération de client basée sur la base de données Golang 🚇 ⬜️ 🍄

Générateur de client de base de données Golang basé sur l'interface.

Pour travailler avec des bases de données, Golang propose le package database/sql , qui est une abstraction de l'interface de programmation de base de données relationnelle. D'une part, le package comprend de puissantes fonctionnalités pour gérer le pool de connexions, travailler avec des instructions préparées, des transactions et l'interface de requête de base de données. D'autre part, vous devez écrire une quantité considérable du même type de code dans une application Web pour interagir avec une base de données. La bibliothèque go-gad / sal propose une solution sous forme de génération du même type de code basé sur l'interface décrite.

La motivation

Aujourd'hui, il existe un nombre suffisant de bibliothèques qui proposent des solutions sous la forme d'ORM, d'aides pour la création de requêtes, de génération d'aides basées sur un schéma de base de données.

Lorsque je suis passé à la langue Golang il y a plusieurs années, j'avais déjà de l'expérience avec des bases de données dans différentes langues. Utiliser ORM, comme ActiveRecord, et sans. Après être passé de l'amour à la haine, n'ayant aucun problème à écrire quelques lignes de code supplémentaires, l'interaction avec la base de données de Golang a abouti à quelque chose comme un modèle de référentiel. Nous décrivons l'interface pour travailler avec la base de données, nous l'implémentons en utilisant la norme db.Query, row.Scan. Utiliser des emballages supplémentaires n'avait tout simplement pas de sens, c'était opaque, cela obligerait à être en alerte.

Le langage SQL lui-même est déjà une abstraction entre votre programme et les données du référentiel. Il m'a toujours semblé illogique d'essayer de décrire un schéma de données, puis de créer des requêtes complexes. Dans ce cas, la structure de réponse est différente du schéma de données. Il s'avère que le contrat doit être décrit non pas au niveau du schéma de données, mais au niveau de la demande et de la réponse. Nous utilisons cette approche dans le développement Web lorsque nous décrivons les structures de données des demandes et des réponses d'API. Lors de l'accès au service en utilisant RESTful JSON ou gRPC, nous déclarons le contrat au niveau de la demande et de la réponse en utilisant le schéma JSON ou Protobuf, et non le schéma de données des entités à l'intérieur des services.

Autrement dit, l'interaction avec la base de données se résumait à une méthode similaire:

 type User struct { ID int64 Name string } type Store interface { FindUser(id int64) (*User, error) } type Postgres struct { DB *sql.DB } func (pg *Postgres) FindUser(id int64) (*User, error) { var resp User err := pg.DB.QueryRow("SELECT id, name FROM users WHERE id=$1", id).Scan(&resp.ID, &resp.Name) if err != nil { return nil, err } return &resp, nil } func HanlderFindUser(s Store, id int) (*User, error) { // logic of service object user, err := s.FindUser(id) //... }

De cette façon, votre programme est prévisible. Mais pour être honnête, ce n'est pas le rêve d'un poète. Nous voulons réduire la quantité de code standard pour composer une requête, remplir des structures de données, utiliser la liaison de variables, etc. J'ai essayé de formuler une liste d'exigences auxquelles l'ensemble d'utilitaires souhaité devrait satisfaire.

Prérequis

Description de l'interaction sous forme d'interface.
L'interface est décrite par des méthodes et des messages de demandes et de réponses.
Prise en charge des variables de liaison et des instructions préparées.
Prise en charge des arguments nommés.
Lier la réponse de la base de données aux champs de la structure de données du message.
Prise en charge des structures de données atypiques (array, json).
Travail transparent avec les transactions.
Prise en charge native du middleware.

Nous voulons résumer l'implémentation de l'interaction avec la base de données à l'aide de l'interface. Cela nous permettra d'implémenter quelque chose de similaire à un modèle de conception tel qu'un référentiel. Dans l'exemple ci-dessus, nous avons décrit l'interface Store. Maintenant, nous pouvons l'utiliser comme dépendance. Au stade du test, nous pouvons passer un stub généré sur la base de cette interface, et dans le produit, nous utiliserons notre implémentation basée sur la structure Postgres.

Chaque méthode d'interface décrit une requête de base de données. Les paramètres d'entrée et de sortie de la méthode doivent faire partie du contrat de la demande. La chaîne de requête doit pouvoir être formatée en fonction des paramètres d'entrée. Cela est particulièrement vrai lors de la compilation de requêtes avec une condition d'échantillonnage complexe.

Lors de la compilation d'une requête, nous voulons utiliser la substitution et la liaison de variables. Par exemple, dans PostgreSQL, vous écrivez $1 au lieu d'une valeur et, avec la requête, passez un tableau d'arguments. Le premier argument sera utilisé comme valeur dans la requête convertie. La prise en charge des expressions préparées vous permet de ne pas vous soucier d'organiser le stockage de ces mêmes expressions. La bibliothèque de base de données / sql fournit un outil puissant pour prendre en charge les expressions préparées; elle s'occupe elle-même du pool de connexions, des connexions fermées. Mais de la part de l'utilisateur, une action supplémentaire est nécessaire pour réutiliser l'expression préparée dans la transaction.

Les bases de données, telles que PostgreSQL et MySQL, utilisent une syntaxe différente pour utiliser des substitutions et des liaisons de variables. PostgreSQL utilise le format $1 , $2 , ... MySQL utilise ? quel que soit l'emplacement de la valeur. La bibliothèque de base de données / sql a proposé un format universel pour les arguments nommés https://golang.org/pkg/database/sql/#NamedArg . Exemple d'utilisation:

 db.ExecContext(ctx, `DELETE FROM orders WHERE created_at < @end`, sql.Named("end", endTime))

La prise en charge de ce format est préférable à utiliser par rapport aux solutions PostgreSQL ou MySQL.

La réponse de la base de données qui traite le pilote logiciel peut être conditionnellement représentée comme suit:

 dev > SELECT * FROM rubrics; id | created_at | title | url ----+-------------------------+-------+------------ 1 | 2012-03-13 11:17:23.609 | Tech | technology 2 | 2015-07-21 18:05:43.412 | Style | fashion (2 rows)

Du point de vue de l'utilisateur au niveau de l'interface, il est commode de décrire le paramètre de sortie comme un tableau de structures de la forme:

 type GetRubricsResp struct { ID int CreatedAt time.Time Title string URL string }

Ensuite, resp.ID valeur id sur resp.ID et ainsi de suite. En général, cette fonctionnalité couvre la plupart des besoins.

Lors de la déclaration de messages via des structures de données internes, la question se pose de savoir comment prendre en charge les types de données non standard. Par exemple, un tableau. Si vous utilisez le pilote github.com/lib/pq lorsque vous travaillez avec PostgreSQL, vous pouvez utiliser des fonctions auxiliaires comme pq.Array(&x) lors du passage d'arguments de requête ou de l'analyse d'une réponse. Exemple tiré de la documentation:

 db.Query(`SELECT * FROM t WHERE id = ANY($1)`, pq.Array([]int{235, 401})) var x []sql.NullInt64 db.QueryRow('SELECT ARRAY[235, 401]').Scan(pq.Array(&x))

En conséquence, il doit exister des moyens de préparer des structures de données.

Lors de l'exécution de l'une des méthodes d'interface, une connexion à la base de données peut être utilisée sous la forme d'un *sql.DB Si vous devez exécuter plusieurs méthodes au sein d'une même transaction, je souhaite utiliser une fonctionnalité transparente avec une approche similaire pour travailler en dehors d'une transaction, sans passer d'arguments supplémentaires.

Lorsque vous travaillez avec des implémentations d'interface, il est essentiel pour nous de pouvoir intégrer la boîte à outils. Par exemple, consigner toutes les demandes. La boîte à outils doit avoir accès aux variables de demande, à l'erreur de réponse, à l'exécution et au nom de la méthode d'interface.

Pour la plupart, les exigences ont été formulées comme une systématisation des scénarios de base de données.

Solution: go-gad / sal

Une façon de gérer le code passe-partout est de le générer. Heureusement, Golang a des outils et des exemples pour ce https://blog.golang.org/generate . L'approche https://github.com/golang/mock de GoMock a été considérée comme une solution architecturale pour la génération, où l'analyse d'interface est effectuée par réflexion. Sur la base de cette approche, selon les exigences, l'utilitaire salgen et la bibliothèque sal ont été écrits, qui génèrent du code d'implémentation d'interface et fournissent un ensemble de fonctions auxiliaires.

Afin de commencer à utiliser cette solution, il est nécessaire de décrire une interface qui décrit le comportement de la couche d'interaction avec la base de données. Spécifiez la directive go:generate avec un ensemble d'arguments et lancez la génération. Vous obtiendrez un constructeur et un tas de code passe-partout, prêts à l'emploi.

 package repo import "context" //go:generate salgen -destination=./postgres_client.go -package=dev/taxi/repo dev/taxi/repo Postgres type Postgres interface { CreateDriver(ctx context.Context, r *CreateDriverReq) error } type CreateDriverReq struct { taxi.Driver } func (r *CreateDriverReq) Query() string { return `INSERT INTO drivers(id, name) VALUES(@id, @name)` }

Interface

Tout commence par déclarer l'interface et une commande spéciale pour l'utilitaire go generate :

 //go:generate salgen -destination=./client.go -package=github.com/go-gad/sal/examples/profile/storage github.com/go-gad/sal/examples/profile/storage Store type Store interface { ...

Ici, il est décrit que pour notre interface Store , l'utilitaire de console salgen sera appelé à partir du package, avec deux options et deux arguments. La première option -destination détermine dans quel fichier le code généré sera écrit. La deuxième option -package définit le chemin complet (chemin d'importation) de la bibliothèque pour l'implémentation générée. Voici deux arguments. Le premier décrit le chemin complet du package ( github.com/go-gad/sal/examples/profile/storage ) où se trouve l'interface, le second indique le nom de l'interface elle-même. Notez que la commande go generate peut être située n'importe où, pas nécessairement à côté de l'interface cible.

Après avoir exécuté la commande go generate , nous obtenons un constructeur dont le nom est construit en ajoutant le New préfixe au nom de l'interface. Le constructeur prend un paramètre requis correspondant à l'interface sal.QueryHandler :

 type QueryHandler interface { QueryContext(ctx context.Context, query string, args ...interface{}) (*sql.Rows, error) ExecContext(ctx context.Context, query string, args ...interface{}) (sql.Result, error) PrepareContext(ctx context.Context, query string) (*sql.Stmt, error) }

Cette interface correspond à l'objet *sql.DB

 connStr := "user=pqgotest dbname=pqgotest sslmode=verify-full" db, err := sql.Open("postgres", connStr) client := storage.NewStore(db)

Les méthodes

Les méthodes d'interface déterminent l'ensemble des requêtes de base de données disponibles.

 type Store interface { CreateAuthor(ctx context.Context, req CreateAuthorReq) (CreateAuthorResp, error) GetAuthors(ctx context.Context, req GetAuthorsReq) ([]*GetAuthorsResp, error) UpdateAuthor(ctx context.Context, req *UpdateAuthorReq) error }

Le nombre d'arguments est toujours strictement deux.
Le premier argument est le contexte.
Le deuxième argument contient des données pour les variables de liaison et définit la chaîne de requête.
Le premier paramètre de sortie peut être un objet, un tableau d'objets ou absent.
Le dernier paramètre de sortie est toujours une erreur.

Le premier argument est toujours l'objet context.Context . Ce contexte sera transmis lors de l'appel de la base de données et de la boîte à outils. Le deuxième argument attend un paramètre avec le type de struct (ou un pointeur vers struct ). Le paramètre doit satisfaire l'interface suivante:

 type Queryer interface { Query() string }

La méthode Query() sera appelée avant d'exécuter une requête de base de données. La chaîne résultante sera convertie dans un format spécifique à la base de données. Autrement dit, pour PostgreSQL, @end sera remplacé par $1 , et la valeur &req.End sera transmise au tableau d'arguments

En fonction des paramètres de sortie, il est déterminé laquelle des méthodes (Query / Exec) sera appelée:

Si le premier paramètre est de type struct (ou un pointeur vers struct ), la méthode QueryContext sera appelée. Si la réponse de la base de données ne contient pas une seule ligne, l'erreur sql.ErrNoRows sera sql.ErrNoRows . Autrement dit, le comportement est similaire à db.QueryRow .
Si le premier paramètre est avec la slice type de base, la méthode QueryContext sera appelée. Si la réponse de la base de données ne contient pas de lignes, une liste vide sera retournée. Le type de base de l'élément de liste doit être stuct (ou un pointeur vers une struct ).
Si le paramètre de sortie est un avec le type d' error , la méthode ExecContext sera appelée.

Déclarations préparées

Le code généré prend en charge les expressions préparées. Les expressions préparées sont mises en cache. Après la première préparation de l'expression, elle est mise en cache. La bibliothèque de base de données / sql elle-même garantit que les expressions préparées sont appliquées de manière transparente à la connexion de base de données souhaitée, y compris le traitement des connexions fermées. À son tour, la bibliothèque go-gad/sal se charge de réutiliser l'instruction préparée dans le contexte de la transaction. Lorsque l'expression préparée est exécutée, les arguments sont transmis à l'aide d'une liaison de variable, transparente pour le développeur.

Pour prendre en charge les arguments nommés du côté de la bibliothèque go-gad/sal , la demande est convertie en une vue adaptée à la base de données. Il existe désormais un support de conversion pour PostgreSQL. Les noms de champ de l'objet de requête sont utilisés pour se substituer aux arguments nommés. Pour spécifier un nom différent au lieu du nom de champ d'objet, vous devez utiliser la balise sql pour les champs de structure. Prenons un exemple:

 type DeleteOrdersRequest struct { UserID int64 `sql:"user_id"` CreateAt time.Time `sql:"created_at"` } func (r * DeleteOrdersRequest) Query() string { return `DELETE FROM orders WHERE user_id=@user_id AND created_at<@end` }

La chaîne de requête sera convertie et en utilisant la table de correspondance et la liaison de variable, une liste sera transmise aux arguments d'exécution de la requête:

 // generated code: db.Query("DELETE FROM orders WHERE user_id=$1 AND created_at<$2", &req.UserID, &req.CreatedAt)

Mapper les structures aux arguments de la requête et aux messages de réponse

La bibliothèque go-gad/sal s'occupe d'associer les lignes de réponse de la base de données aux structures de réponse, les colonnes de table aux champs de structure:

 type GetRubricsReq struct {} func (r GetRubricReq) Query() string { return `SELECT * FROM rubrics` } type Rubric struct { ID int64 `sql:"id"` CreateAt time.Time `sql:"created_at"` Title string `sql:"title"` } type GetRubricsResp []*Rubric type Store interface { GetRubrics(ctx context.Context, req GetRubricsReq) (GetRubricsResp, error) }

Et si la réponse de la base de données est:

 dev > SELECT * FROM rubrics; id | created_at | title ----+-------------------------+------- 1 | 2012-03-13 11:17:23.609 | Tech 2 | 2015-07-21 18:05:43.412 | Style (2 rows)

Ensuite, la liste GetRubricsResp nous reviendra, dont les éléments seront des pointeurs vers Rubric, où les champs sont remplis avec des valeurs des colonnes qui correspondent aux noms des balises.

Si la réponse de la base de données contient des colonnes du même nom, les champs de structure correspondants seront sélectionnés dans l'ordre de déclaration.

 dev > select * from rubrics, subrubrics; id | title | id | title ----+-------+----+---------- 1 | Tech | 3 | Politics

 type Rubric struct { ID int64 `sql:"id"` Title string `sql:"title"` } type Subrubric struct { ID int64 `sql:"id"` Title string `sql:"title"` } type GetCategoryResp struct { Rubric Subrubric }

Types de données non standard

Le package database/sql en charge les types de données de base (chaînes, nombres). Afin de traiter des types de données tels que tableau ou json dans une demande ou une réponse, il est nécessaire de prendre en charge les sql.Scanner driver.Valuer et sql.Scanner . Différentes implémentations de pilotes ont des fonctions d'assistance spéciales. Par exemple, lib/pq.Array ( https://godoc.org/github.com/lib/pq#Array ):

 func Array(a interface{}) interface { driver.Valuer sql.Scanner }

Par défaut, la bibliothèque go-gad/sql pour les champs de structure de vue

 type DeleteAuthrosReq struct { Tags []int64 `sql:"tags"` }

utilisera la valeur &req.Tags . Si la structure satisfait l'interface sal.ProcessRower ,

 type ProcessRower interface { ProcessRow(rowMap RowMap) }

alors la valeur utilisée peut être ajustée

 func (r *DeleteAuthorsReq) ProcessRow(rowMap sal.RowMap) { rowMap.Set("tags", pq.Array(r.Tags)) } func (r *DeleteAuthorsReq) Query() string { return `DELETE FROM authors WHERE tags=ANY(@tags::UUID[])` }

Ce gestionnaire peut être utilisé pour les arguments de demande et de réponse. Dans le cas d'une liste dans la réponse, la méthode doit appartenir à l'élément de liste.

Les transactions

Pour prendre en charge les transactions, l'interface (Store) doit être étendue avec les méthodes suivantes:

 type Store interface { BeginTx(ctx context.Context, opts *sql.TxOptions) (Store, error) sal.Txer ...

L'implémentation des méthodes sera générée. La méthode BeginTx utilise la connexion de l'objet sal.QueryHandler actuel et ouvre la transaction db.BeginTx(...) ; renvoie un nouvel objet d'implémentation de l'interface Store , mais utilise l'objet *sql.Tx reçu comme *sql.Tx

Middleware

Des crochets sont fournis pour les outils d'intégration.

 type BeforeQueryFunc func(ctx context.Context, query string, req interface{}) (context.Context, FinalizerFunc) type FinalizerFunc func(ctx context.Context, err error)

Le hook BeforeQueryFunc sera appelé avant l' db.PrepareContext ou db.Query . Autrement dit, au début du programme, lorsque le cache d'expression préparé est vide, lorsque store.GetAuthors appelé, le crochet BeforeQueryFunc sera appelé deux fois. Le hook BeforeQueryFunc peut renvoyer un hook FinalizerFunc , qui sera appelé avant de quitter la méthode utilisateur, dans notre case store.GetAuthors , en utilisant store.GetAuthors .

Au moment de l'exécution des hooks, le contexte est rempli de clés de service avec les valeurs suivantes:

ctx.Value(sal.ContextKeyTxOpened) valeur booléenne détermine si la méthode est appelée ou non dans le contexte de la transaction.
ctx.Value(sal.ContextKeyOperationType) , la valeur de chaîne du type d'opération, "QueryRow" , "Query" , "Exec" , "Commit" , etc.
ctx.Value(sal.ContextKeyMethodName) valeur de chaîne de la méthode d'interface, telle que "GetAuthors" .

En tant qu'arguments, le hook BeforeQueryFunc accepte la chaîne sql de la requête et l'argument req de la méthode de requête utilisateur. Le hook FinalizerFunc prend une variable err comme argument.

 beforeHook := func(ctx context.Context, query string, req interface{}) (context.Context, sal.FinalizerFunc) { start := time.Now() return ctx, func(ctx context.Context, err error) { log.Printf( "%q > Opeartion %q: %q with req %#v took [%v] inTx[%v] Error: %+v", ctx.Value(sal.ContextKeyMethodName), ctx.Value(sal.ContextKeyOperationType), query, req, time.Since(start), ctx.Value(sal.ContextKeyTxOpened), err, ) } } client := NewStore(db, sal.BeforeQuery(beforeHook))

Exemples de sortie:

 "CreateAuthor" > Opeartion "Prepare": "INSERT INTO authors (Name, Desc, CreatedAt) VALUES($1, $2, now()) RETURNING ID, CreatedAt" with req <nil> took [50.819µs] inTx[false] Error: <nil> "CreateAuthor" > Opeartion "QueryRow": "INSERT INTO authors (Name, Desc, CreatedAt) VALUES(@Name, @Desc, now()) RETURNING ID, CreatedAt" with req bookstore.CreateAuthorReq{BaseAuthor:bookstore.BaseAuthor{Name:"foo", Desc:"Bar"}} took [150.994µs] inTx[false] Error: <nil>

Et ensuite

Prise en charge des variables de liaison et des expressions préparées pour MySQL.
Crochet RowAppender pour ajuster la réponse.
Renvoie la valeur de Exec.Result .

Interface de génération de client basée sur la base de données Golang