When building applications in Golang, adhering to the principles of Hexagonal Architecture can ensure clean, modular, and maintainable code. With Torpedo, you can easily implement this architecture while speeding up your development process. In this guide, we’ll walk through how to create your first project with Torpedo, from installation to generating entities and use cases.
This post is a summary of the documented quick start guide
1. Getting Started with Torpedo
Before we dive into creating a project, make sure you have Go installed on your system. Then, install Torpedo following the instructions at installation guide
This CLI tool will handle project generation, entity creation, and use case scaffolding for you. Once installed, you’re ready to create your first project.
2. Setting Up Your First Project
Lets begging with our first application built with Torpedo!. We will be building a fly reservation app called Booking Fly.
With Torpedo installed, creating a new project is as simple as running:
mkdir booking-fly && cd booking-fly
torpedo init
This command will generate the folder .torpedo
where you should defines your entities and use cases. More info about this folder can be found at .torpedo dir struct
3. Defining Your First Entity
Next, you’ll want to define your domain entities. Entities are the core objects in your application’s business logic, representing things like User
, Product
, or Order
.
To define your first entity, create a YAML file under the .torpedo/entities
directory. For example, let’s create a simple User
entity:
.torpedo/entities/user.yaml
version: torpedo.darksub.io/v1.0
kind: entity
spec:
name: "user"
plural: "users"
description: "The frequent flyer user"
doc: |
The user entity represents a system user but also a frequent flyer.
This entity is only for the example purpose.
schema:
reserved:
id:
type: ulid
fields:
- name: name
type: string
description: "The user full name"
- name: email
type: string
description: "The user contact email"
- name: password # it is not recommended to save passwords, this is an example only
type: string
encrypted: true
description: "The user system password"
- name: plan
type: string
description: "The user membership plan"
validate:
list:
values:
- GOLD
- SILVER
- BRONZE
- name: miles
type: integer
description: "The accumulated flyer miles"
relationships:
- name: trips
type: $rel
ref: ".torpedo/entities/trip.yaml"
cardinality: hasMany
load:
type: nested
metadata:
maxItems: 100
adapters:
input:
- type: http
output:
- type: memory
Additionally the Trip
entity is required, so, let’s create a Trip
entity:
.torpedo/entities/trip.yaml
version: torpedo.darksub.io/v1.0
kind: entity
spec:
name: trip
plural: trips
description: "The user fly trip reservations"
doc: |
The trip entity handles all data related with the frequent flyer trip
schema:
reserved:
id:
type: ulid
fields:
- name: departure
type: string
description: "The trip departure airport"
- name: arrival
type: string
description: "The trip arrival airport"
- name: miles
type: integer
description: "The trip miles"
- name: from
type: date
description: "The trip from date"
- name: to
type: date
description: "The trip to date"
adapters:
input:
- type: http
output:
- type: memory
Torpedo will generate the Go code for the User
and Trip
entities along with its corresponding CRUD operations, including the repository interfaces and any necessary database handling code.
4. Creating Use Cases
Once your entities are in place, it’s time to define how they’ll interact with the application’s workflows using use cases. Use cases encapsulate the business rules and processes that act upon your entities.
Create a YAML file under the .torpedo/use_cases
directory to define your use case. Here’s an example of a simple use case for booking a fly:
.torpedo/use_cases/booking_fly.yaml
version: torpedo.darksub.io/v1.0
kind: useCase
spec:
name: "BookingFly"
description: "Fly reservation use case"
doc: |
Given a frequent flyer user should be able to do a booking fly from our well known fly routes, selecting the
departure airport and the arrival airport, also setting up the from-to fly dates. If the booking is successful, so the
system should calculate the user awards and upgrade it.
domain:
entities:
- user.yaml
- trip.yaml
This definition tells Torpedo to create the skeleton code to put your custom logic for processing a fly reservation given a Trip
and a User
.
Torpedo will scaffold the complete use case, including interactions with your entities.
After complete the next step (#5) please read the quick start guide to learn about how to code your logic within the generated skeleton use case at Use Cases
5. Wiring It All Together
Once you’ve defined your entities and use cases, Torpedo ensures that the wiring between these components follows Hexagonal Architecture principles. The use cases will interact with the entities through the service interfaces, while your adapters (such as databases or APIs) handle persistence and external communication.
Now it's time to write your app specification to put all together!. The application definition is the most important file because here is described your app. The following example shows how to define the Booking Fly app:
.torpedo/app.yaml
version: torpedo.darksub.io/v1.0
kind: app
spec:
name: "Booking Fly System"
description: "Application example"
stack:
lang: go
package: "github.com/darksubmarine/booking-fly"
domain:
entities:
- user.yaml
- trip.yaml
useCases:
- booking_fly.yaml
To generate the application code (entities, use cases and more) run the command:
torpedo fire
This command will generate a project scaffold, setting up the directory structure based on the Hexagonal Architecture. The project will include core folders for entities, use cases, and adapters. It ensures that your business logic and infrastructure remain decoupled from the get-go.
You can now extend your project by adding more entities, use cases, and even custom adapters. Torpedo’s structure allows you to keep your code clean and modular, making it easy to scale your application as it grows.
Also take a look at how to code your own logic withing generated Use Case code.
6. Running Your Application
After setting up entities and use cases, you’re ready to run your application. Torpedo includes a lightweight server, based on Gin Gonic project, that you can run for testing and development. Simply use:
Don't forget to run
go mod tidy
before to update dependencies!
go run main.go
You can now interact with your application’s API, running the CRUD operations and use cases you’ve defined.
7. What’s Next?
Torpedo makes it easy to generate clean, structured Go code with Hexagonal Architecture. But this is just the beginning! You can continue to explore Torpedo’s features by adding more complex workflows, integrating external services, and customizing the framework to suit your needs.
Stay tuned for more advanced features coming soon to Torpedo, and feel free to share your feedback as you explore what’s possible!
Conclusion
Creating your first project with Torpedo is simple and fast. By leveraging the power of entity schemas and use case definitions in YAML, you can quickly scaffold a robust Golang application while maintaining clean architectural principles. Now it's time to dive in and start building! Let us know what you think and how Torpedo can help your future projects.
Top comments (0)