{"id":15095847,"url":"https://github.com/omar-aldesi/go-ecommerce","last_synced_at":"2026-02-06T15:08:08.717Z","repository":{"id":253262746,"uuid":"842974169","full_name":"omar-aldesi/go-ecommerce","owner":"omar-aldesi","description":"Go Ecommerce API is a high-performance, scalable backend API built with Go, Gin, and Gorm. Designed for modern ecommerce applications, it features robust JWT authentication, custom error handling, and advanced product filtering. The project is fully containerized with Docker","archived":false,"fork":false,"pushed_at":"2024-08-19T21:44:36.000Z","size":23984,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-07-08T23:05:01.536Z","etag":null,"topics":["docker","ecommerce","gin","golang","gorm","postgresql","rest-api"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/omar-aldesi.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-08-15T14:05:55.000Z","updated_at":"2024-10-12T17:10:00.000Z","dependencies_parsed_at":"2025-07-08T23:05:03.600Z","dependency_job_id":"4f2a67dd-3cb4-4d18-8dec-facb3bef19b5","html_url":"https://github.com/omar-aldesi/go-ecommerce","commit_stats":null,"previous_names":["omar-aldesi/go-ecommerce"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/omar-aldesi/go-ecommerce","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/omar-aldesi%2Fgo-ecommerce","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/omar-aldesi%2Fgo-ecommerce/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/omar-aldesi%2Fgo-ecommerce/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/omar-aldesi%2Fgo-ecommerce/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/omar-aldesi","download_url":"https://codeload.github.com/omar-aldesi/go-ecommerce/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/omar-aldesi%2Fgo-ecommerce/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29165905,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-06T14:37:12.680Z","status":"ssl_error","status_checked_at":"2026-02-06T14:36:22.973Z","response_time":59,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docker","ecommerce","gin","golang","gorm","postgresql","rest-api"],"created_at":"2024-09-25T15:42:37.081Z","updated_at":"2026-02-06T15:08:08.677Z","avatar_url":"https://github.com/omar-aldesi.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🛒 Go Ecommerce API\n\n[![Golang](https://img.shields.io/badge/Golang-00ADD8?style=for-the-badge\u0026logo=go\u0026logoColor=white)](https://golang.org/)\n[![Gin](https://img.shields.io/badge/Gin-00ADD8?style=for-the-badge\u0026logo=go\u0026logoColor=white)](https://gin-gonic.com/)\n[![Gorm](https://img.shields.io/badge/Gorm-29BEB0?style=for-the-badge\u0026logo=go\u0026logoColor=white)](https://gorm.io/)\n[![Docker](https://img.shields.io/badge/Docker-2496ED?style=for-the-badge\u0026logo=docker\u0026logoColor=white)](https://www.docker.com/)\n[![PostgreSQL](https://img.shields.io/badge/PostgreSQL-316192?style=for-the-badge\u0026logo=postgresql\u0026logoColor=white)](https://www.postgresql.org/)\n[![Swagger](https://img.shields.io/badge/Swagger-85EA2D?style=for-the-badge\u0026logo=swagger\u0026logoColor=black)](https://swagger.io/)\n\n\nWelcome to the Go Ecommerce API project! This repository contains a fully-functional RESTful API built using Go, Gin, and Gorm. The project leverages PostgreSQL as its database and includes full Docker integration for seamless development and deployment. Below you'll find all the information you need to clone, set up, and run this project, as well as an overview of its architecture and features.\n\n🎯 Features\n\n- Go Gin Gorm: A powerful combination for building RESTful APIs with performance and ease of use.\n\n- JWT Authentication: Secure your API endpoints with JSON Web Tokens (JWT) for user authentication.\n\n- Custom Error Handling: Robust error handling including validation and type-specific errors.\n\n- Modern Project Structure: Clean and scalable code organization with clear separation between concerns.\n\n- PostgreSQL Database: Reliable and scalable relational database integration using Gorm.\n\n- Full Docker Integration: Effortless development and deployment with Docker, including Docker Compose.\n\n- Advanced Currency Handling: Manage transactions and prices effectively with the gocurrency package.\n\n- OpenAPI Documentation: Automatically generated API documentation for all endpoints.\n\n- RESTful API Protocols: Adheres to REST principles for easy and predictable API interactions.\n\n- Auth Middleware: Secure endpoints with a custom JWT-based authentication middleware.\n\n- Token Blacklisting: Refresh token blacklisting for enhanced security.\n\n- General Systems for Shipping \u0026 Payment: Modular and extensible design for handling shipping and payment logic.\n\n- Advanced Product Filtering: Powerful and flexible filtering options for product listings.\n\n📁 Project Structure\n\nThe project follows a modern Go project structure:\n\n```bash\necommerce/\n├── app/\n│   ├── core/           # Core functionality like database and middleware\n│   ├── models/         # Data models representing the database schema\n│   ├── crud/           # CRUD operations on models\n│   ├── schemas/        # Request/response schemas for API endpoints\n│   ├── endpoints/      # API endpoints (organized by version)\n│   └── middlewares/    # Custom middleware such as auth and error handling\n├── docs/               # OpenAPI documentation generated by Swaggo\n├── Dockerfile          # Dockerfile for building the application\n├── docker-compose.yml  # Docker Compose configuration for multi-service setup\n├── go.mod              # Go module file\n└── README.md           # Project README file\n```\n\n🛠️ Getting Started\n\nPrerequisites\n\n- Docker: Make sure you have Docker and Docker Compose installed on your machine.\n\n- Go: Go should be installed if you want to run the application locally without Docker (optional).\n\n\n🚀 Cloning the Repository\n\nTo clone the repository, use the following command:\n\n```bash\ngit clone https://github.com/omar-aldesi/go-ecommerce.git\ncd ecommerce\n```\n\n🐳 Running the Application with Docker\n\nThe easiest way to run the project is using Docker and Docker Compose. This will automatically set up the application along with a PostgreSQL database.\n\nBuild and Run the Docker Containers:\n\n```bash\ndocker-compose up --build\n```\n\nAccess the Application:\n\nThe API will be available at http://localhost:8080.\n\nAccess Swagger UI:\n\nThe OpenAPI documentation will be accessible at http://localhost:8080/swagger/index.html.\n\n\n⚙️ Running the Application Locally\n\nIf you prefer to run the application locally without Docker:\n\nSet Up PostgreSQL:\n\n- Install PostgreSQL and create a database for the project.\n- Update the database connection details in the environment variables.\n- Install Dependencies:\n\n```bash\ngo mod download\n```\n\nRun the Application:\n\n```bash\ngo run main.go\n```\n\nAccess the Application:\n\nThe API will be running at http://localhost:8080.\n\n🛡️ Authentication\nThis API uses JWT tokens for authentication. Clients must include a valid JWT in the Authorization header for secured endpoints. The format should be:\n\n```http\nAuthorization: Bearer \u003cyour-jwt-token\u003e\n```\n\n\n🔑 JWT Token Management\n\nLogin: Clients can obtain a JWT by providing valid credentials via the /api/v1/auth/login endpoint.\nRefresh Token: The application supports token refreshing and blacklisting, ensuring a secure token lifecycle.\n\n\n🧩 API Documentation\n\nThe API documentation is generated using OpenAPI (Swagger) and is accessible at:\n\n```bash\nhttp://localhost:8080/swagger/index.html\n```\n\nThis documentation provides detailed information about each endpoint, including request parameters, response formats, and authentication requirements.\n\n\n⚠️ Error Handling\n\nThe application has a custom error handling system that provides detailed and user-friendly error messages. Here are some examples:\n\n\nValidation Error Handling\nWhen a request fails validation, the system returns an error response with details about each invalid field:\n\n```go\n// ErrorResponse represents the structure of the error response\ntype ErrorResponse struct {\n\tErrors map[string]interface{} `json:\"errors\"`\n}\n\n// HandleValidationErrors processes and returns validation errors\nfunc HandleValidationErrors(c *gin.Context, err error) {\n\tvar ve validator.ValidationErrors\n\tvar je *json.UnmarshalTypeError\n\n\tswitch {\n\tcase errors.As(err, \u0026ve):\n\t\terrs := make(map[string]interface{})\n\t\tfor _, e := range ve {\n\t\t\terrs[e.Field()] = formatErrorMessage(e)\n\t\t}\n\t\tc.JSON(400, ErrorResponse{Errors: errs})\n\tcase errors.As(err, \u0026je):\n\t\terrs := map[string]interface{}{\n\t\t\tje.Field: fmt.Sprintf(\"Invalid value type. Expected %s\", je.Type.String()),\n\t\t}\n\t\tc.JSON(400, ErrorResponse{Errors: errs})\n\tdefault:\n\t\tc.JSON(400, ErrorResponse{Errors: map[string]interface{}{\"general\": err.Error()}})\n\t}\n}\n\n// formatErrorMessage formats a single validation error message\nfunc formatErrorMessage(e validator.FieldError) string {\n\tswitch e.Tag() {\n\tcase \"required\":\n\t\treturn \"This field is required\"\n\tcase \"email\":\n\t\treturn \"Invalid email address\"\n\tcase \"min\":\n\t\tif e.Type().Kind() == reflect.String {\n\t\t\treturn fmt.Sprintf(\"This field must be at least %s characters long\", e.Param())\n\t\t}\n\t\treturn fmt.Sprintf(\"This field must be at least %s\", e.Param())\n\tcase \"max\":\n\t\tif e.Type().Kind() == reflect.String {\n\t\t\treturn fmt.Sprintf(\"This field must be at most %s characters long\", e.Param())\n\t\t}\n\t\treturn fmt.Sprintf(\"This field must be at most %s\", e.Param())\n\tcase \"e164\":\n\t\treturn \"Invalid phone number format\"\n\tcase \"oneof\":\n\t\treturn fmt.Sprintf(\"This field must be one of: %s\", strings.Replace(e.Param(), \" \", \", \", -1))\n\tcase \"len\":\n\t\treturn fmt.Sprintf(\"This field must be exactly %s characters long\", e.Param())\n\tcase \"numeric\":\n\t\treturn \"This field must contain only numeric characters\"\n\tcase \"alphanum\":\n\t\treturn \"This field must contain only alphanumeric characters\"\n\tdefault:\n\t\treturn fmt.Sprintf(\"Invalid value for %s\", e.Field())\n\t}\n}\n```\n\nCustom HTTP Error Handling\nYou can use the HTTPError struct to return custom HTTP error responses:\n\n```go\n// HTTPError is a custom error type for HTTP errors\ntype HTTPError struct {\n\tStatusCode int\n\tMessage    string\n}\n\nfunc (e *HTTPError) Error() string {\n\treturn e.Message\n}\n\nfunc CustomErrorResponse(c *gin.Context, err error) {\n\tvar httpErr *HTTPError\n\tif errors.As(err, \u0026httpErr) {\n\t\tc.JSON(httpErr.StatusCode, gin.H{\"error\": httpErr.Message})\n\t}\n\tlog.Println(\"Error --\u003e \", httpErr.StatusCode, err)\n}\n```\nThis allows for a consistent and clear error response structure across the application.\n\n🧪 Testing\nYou can run unit and integration tests for the application using:\n\n```bash\ngo test ./...\n```\n\nMake sure to configure the test database connection in your environment variables before running tests.\n\n🤝 Contributing\nWe welcome contributions! Please fork the repository and submit a pull request with your changes.\n\n📜 License\nThis project is licensed under the MIT License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fomar-aldesi%2Fgo-ecommerce","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fomar-aldesi%2Fgo-ecommerce","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fomar-aldesi%2Fgo-ecommerce/lists"}