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

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

Installer les dépendances :

go mod tidy

Définissez les variables d'environnement :

cp .env.example .env

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

Courir localement :

make start

Ou courir avec rechargement en direct :

air

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

Docker :

# run docker container
make docker

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

Peluchage :

# run lint
make lint

Swagger :

# generate the swagger documentation
make swagger

Migration :

# Create migration
make migration-<table-name>

# Example for table users
make migration-users


</table-name>

# 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

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

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

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.

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

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

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

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

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

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');

Note:
API request information (request url, response code, timestamp, etc.) are also automatically logged (using Fiber-Logger).

Linting

Linting is done using golangci-lint

See ? How to install golangci-lint

To modify the golangci-lint configuration, update the .golangci.yml file.

Contributing

Contributions are more than welcome! Please check out the contributing guide.

If you find this boilerplate useful, consider giving it a star! ⭐

The full source code is available at the GitHub link below:

https://github.com/indrayyana/go-fiber-boilerplate

Ce qui précède est le contenu détaillé de. pour plus d'informations, suivez d'autres articles connexes sur le site Web de PHP en chinois!