Créer une API RESTful avec Go Fiber : un passe-partout inspiré d'Express-Golang-php.cn

Building a RESTful API with Go Fiber: An Express-Inspired Boilerplate
Un projet standard/de démarrage pour créer rapidement des API RESTful à l'aide de Go, Fiber et PostgreSQL. Inspiré du passe-partout Express.

L'application est livrée avec de nombreuses fonctionnalités intégrées, telles que l'authentification à l'aide de JWT et Google OAuth2, la validation des demandes, les tests unitaires et d'intégration, la prise en charge de Docker, la documentation API, la pagination, etc. Pour plus de détails, consultez la liste des fonctionnalités ci-dessous.

Table des matières

Caractéristiques
Commandes
Variables d'environnement
Structure du projet
Documentation API
Gestion des erreurs
Validation
Authentification
Autorisation
Journalisation
Peluchage
Contribuer

Caractéristiques

Base de données SQL : Mappage des relations d'objets PostgreSQL à l'aide de Gorm
Migrations de bases de données : avec golang-migrate
Validation : demander la validation des données à l'aide du validateur de package
Logging : utilisation de Logrus et Fiber-Logger
Tests : tests unitaires et d'intégration à l'aide de Testify et sortie de test formatée à l'aide de gotestsum
Gestion des erreurs : mécanisme centralisé de gestion des erreurs
Documentation API : avec Swag et Swagger
Envoi d'email : avec Gomail
Variables d'environnement : utilisation de Viper
Sécurité : définissez les en-têtes HTTP de sécurité à l'aide de Fiber-Helmet
CORS : partage de ressources entre origines activées à l'aide de Fiber-CORS
Compression : compression gzip avec Fiber-Compress
Support Docker
Linting : avec golangci-lint

Commandes

Cloner le dépôt :


git clone --depth 1 https://github.com/indrayyana/go-fiber-boilerplate.git
cd go-fiber-boilerplate
rm -rf ./.git

Copier après la connexion

Installer les dépendances :


go mod tidy

Copier après la connexion

Définissez les variables d'environnement :


cp .env.example .env

# open .env and modify the environment variables (if needed)

Copier après la connexion

Courir localement :


make start

Copier après la connexion

Ou courir avec rechargement en direct :

air

Copier après la connexion

Remarque :
Assurez-vous que Air est installé.
Voir ? Comment installer Air

Test :


# run all tests
make tests

# run all tests with gotestsum format
make testsum

# run test for the selected function name
make tests-TestUserModel

Copier après la connexion

Docker :


# run docker container
make docker

# run all tests in a docker container
make docker-test

Copier après la connexion

Peluchage :


# run lint
make lint

Copier après la connexion

Swagger :


# generate the swagger documentation
make swagger

Copier après la connexion

Migration :


# Create migration
make migration-<table-name>

# Example for table users
make migration-users

Copier après la connexion


# run migration up in local
make migrate-up

# run migration down in local
make migrate-down

# run migration up in docker container
make migrate-docker-up

# run migration down all in docker container
make migrate-docker-down

Copier après la connexion

Variables d'environnement

Les variables d'environnement peuvent être trouvées et modifiées dans le fichier .env. Ils sont livrés avec ces valeurs par défaut :


# server configuration
# Env value : prod || dev
APP_ENV=dev
APP_HOST=0.0.0.0
APP_PORT=3000

# database configuration
DB_HOST=postgresdb
DB_USER=postgres
DB_PASSWORD=thisisasamplepassword
DB_NAME=fiberdb
DB_PORT=5432

# JWT
# JWT secret key
JWT_SECRET=thisisasamplesecret
# Number of minutes after which an access token expires
JWT_ACCESS_EXP_MINUTES=30
# Number of days after which a refresh token expires
JWT_REFRESH_EXP_DAYS=30
# Number of minutes after which a reset password token expires
JWT_RESET_PASSWORD_EXP_MINUTES=10
# Number of minutes after which a verify email token expires
JWT_VERIFY_EMAIL_EXP_MINUTES=10

# SMTP configuration options for the email service
SMTP_HOST=email-server
SMTP_PORT=587
SMTP_USERNAME=email-server-username
SMTP_PASSWORD=email-server-password
EMAIL_FROM=support@yourapp.com

# OAuth2 configuration
GOOGLE_CLIENT_ID=yourapps.googleusercontent.com
GOOGLE_CLIENT_SECRET=thisisasamplesecret
REDIRECT_URL=http://localhost:3000/v1/auth/google-callback

Copier après la connexion

Structure du projet


src\
 |--config\         # Environment variables and configuration related things
 |--controller\     # Route controllers (controller layer)
 |--database\       # Database connection & migrations
 |--docs\           # Swagger files
 |--middleware\     # Custom fiber middlewares
 |--model\          # Postgres models (data layer)
 |--response\       # Response models
 |--router\         # Routes
 |--service\        # Business logic (service layer)
 |--utils\          # Utility classes and functions
 |--validation\     # Request data validation schemas
 |--main.go         # Fiber app

Copier après la connexion

Documentation API

Pour afficher la liste des API disponibles et leurs spécifications, exécutez le serveur et accédez à http://localhost:3000/v1/docs dans votre navigateur.

Building a RESTful API with Go Fiber: An Express-Inspired Boilerplate

Cette page de documentation est automatiquement générée à l'aide des définitions Swag écrites sous forme de commentaires dans les fichiers du contrôleur.

Vous voyez ? Format des commentaires déclaratifs.

Points de terminaison de l'API

Liste des itinéraires disponibles :

Routes d'authentification :
POST /v1/auth/register - s'inscrire
POST /v1/auth/login - connexion
POST /v1/auth/logout - déconnexion
POST /v1/auth/refresh-tokens - actualiser les jetons d'authentification
POST /v1/auth/forgot-password - envoyer un e-mail de réinitialisation du mot de passe
POST /v1/auth/reset-password - réinitialiser le mot de passe
POST /v1/auth/send-verification-email - envoyer un e-mail de vérification
POST /v1/auth/verify-email - vérifier l'e-mail
GET /v1/auth/google - connectez-vous avec un compte Google

Itinéraires utilisateur :
POST /v1/users - créer un utilisateur
GET /v1/users - obtenir tous les utilisateurs
GET /v1/users/:userId - obtenir l'utilisateur
PATCH /v1/users/:userId - mettre à jour l'utilisateur
DELETE /v1/users/:userId - supprimer l'utilisateur

Gestion des erreurs

L'application comprend un mécanisme de gestion des erreurs personnalisé, qui peut être trouvé dans le fichier src/utils/error.go.

Il utilise également le middleware Fiber-Recover pour récupérer gracieusement de toute panique pouvant survenir dans la pile de gestionnaires, empêchant ainsi l'application de planter de manière inattendue.

Le processus de gestion des erreurs envoie une réponse d'erreur au format suivant :


{
  "code": 404,
  "status": "error",
  "message": "Not found"
}

Copier après la connexion

Fiber fournit une structure d'erreur personnalisée utilisant fiber.NewError(), où vous pouvez spécifier un code de réponse et un message. Cette erreur peut ensuite être renvoyée depuis n'importe quelle partie de votre code, et le ErrorHandler de Fiber la détectera automatiquement.

Par exemple, si vous essayez de récupérer un utilisateur de la base de données mais que l'utilisateur n'est pas trouvé et que vous souhaitez renvoyer une erreur 404, le code peut ressembler à ceci :


func (s *userService) GetUserByID(c *fiber.Ctx, id string) {
    user := new(model.User)

    err := s.DB.WithContext(c.Context()).First(user, "id = ?", id).Error

    if errors.Is(err, gorm.ErrRecordNotFound) {
        return fiber.NewError(fiber.StatusNotFound, "User not found")
    }
}

Copier après la connexion

Validation

Request data is validated using Package validator. Check the documentation for more details on how to write validations.

The validation schemas are defined in the src/validation directory and are used within the services by passing them to the validation logic. In this example, the CreateUser method in the userService uses the validation.CreateUser schema to validate incoming request data before processing it. The validation is handled by the Validate.Struct method, which checks the request data against the schema.


import (
    "app/src/model"
    "app/src/validation"

    "github.com/gofiber/fiber/v2"
)

func (s *userService) CreateUser(c *fiber.Ctx, req validation.CreateUser) (*model.User, error) {
    if err := s.Validate.Struct(&req); err != nil {
        return nil, err
    }
}

Copier après la connexion

Authentication

To require authentication for certain routes, you can use the Auth middleware.


import (
    "app/src/controllers"
    m "app/src/middleware"
    "app/src/services"

    "github.com/gofiber/fiber/v2"
)

func SetupRoutes(app *fiber.App, u services.UserService, t services.TokenService) {
  userController := controllers.NewUserController(u, t)
    app.Post("/users", m.Auth(u), userController.CreateUser)
}

Copier après la connexion

These routes require a valid JWT access token in the Authorization request header using the Bearer schema. If the request does not contain a valid access token, an Unauthorized (401) error is thrown.

Generating Access Tokens:

An access token can be generated by making a successful call to the register (POST /v1/auth/register) or login (POST /v1/auth/login) endpoints. The response of these endpoints also contains refresh tokens (explained below).

An access token is valid for 30 minutes. You can modify this expiration time by changing the JWT_ACCESS_EXP_MINUTES environment variable in the .env file.

Refreshing Access Tokens:

After the access token expires, a new access token can be generated, by making a call to the refresh token endpoint (POST /v1/auth/refresh-tokens) and sending along a valid refresh token in the request body. This call returns a new access token and a new refresh token.

A refresh token is valid for 30 days. You can modify this expiration time by changing the JWT_REFRESH_EXP_DAYS environment variable in the .env file.

Authorization

The Auth middleware can also be used to require certain rights/permissions to access a route.


import (
    "app/src/controllers"
    m "app/src/middleware"
    "app/src/services"

    "github.com/gofiber/fiber/v2"
)

func SetupRoutes(app *fiber.App, u services.UserService, t services.TokenService) {
  userController := controllers.NewUserController(u, t)
    app.Post("/users", m.Auth(u, "manageUsers"), userController.CreateUser)
}

Copier après la connexion

In the example above, an authenticated user can access this route only if that user has the manageUsers permission.

The permissions are role-based. You can view the permissions/rights of each role in the src/config/roles.go file.

If the user making the request does not have the required permissions to access this route, a Forbidden (403) error is thrown.

Logging

Import the logger from src/utils/logrus.go. It is using the Logrus logging library.

Logging should be done according to the following severity levels (ascending order from most important to least important):


import "app/src/utils"

utils.Log.Panic('message') // Calls panic() after logging
utils.Log.Fatal('message'); // Calls os.Exit(1) after logging
utils.Log.Error('message');
utils.Log.Warn('message');
utils.Log.Info('message');
utils.Log.Debug('message');
utils.Log.Trace('message');

Copier après la connexion