1
0
Fork 0
forked from goffee/cup
cup/README.md

99 lines
4.7 KiB
Markdown
Raw Normal View History

2024-09-12 19:15:08 -04:00
![gocondor logo](https://gocondor.github.io/img/logo_x168.png)
# Cup of Goffee
![Build Status](https://github.com/gocondor/gocondor/actions/workflows/build-main.yml/badge.svg)
![Test Status](https://github.com/gocondor/gocondor/actions/workflows/test-main.yml/badge.svg)
[![GoDoc](https://godoc.org/github.com/gocondor/gocondor?status.svg)](https://godoc.org/github.com/gocondor/gocondor)
[![Go Report Card](https://goreportcard.com/badge/github.com/gocondor/gocondor)](https://goreportcard.com/report/github.com/gocondor/gocondor)
## What is GoCondor?
GoCondor is a [Go](https://go.dev) web framework made for building web APIs, suitable for small, medium size and microservices projects. With it's simple structure, and developer friendly experience it helps with increasing the productivity.
## Main Features
- Routing
- Middlewares
- Data Validation
- Databases ORM ([GORM](https://gorm.io/) integrated)
- Emails
- JWT tokens
- Cache (Redis)
- HTTPS (TLS)
## Installation
To create a new `GoCondor` project you need to install the `GoCondor's cli` first
##### Install Gaffer [GoCondor's cli] tool
To install the `gaffer` globally open up your terminal and run the following command:
```bash
go install github.com/gocondor/gaffer@latest
```
![installing](https://gocondor.github.io/img/installing.gif)
##### Create new project using a Cup of Goffee
Here is how you can create new `goCondor` projects using `gaffer`
```bash
gaffer new [project-name] [project-remote-repository]
```
Example
```bash
gaffer new myapp github.com/gocondor/myapp
```
where:
`project-name` is the name of your project
`remote-repository` is the remote repository that will host the project, usually `github.com` is used.
## Getting started
First make sure you have [Gaffer](https://gocondor.github.io/docs/gaffer) installed, then use it to create a new project, [here is how](https://gocondor.github.io/docs/gaffer#create-new-project-using-gaffer)
Let's create a route that returns `hello world`
Open up the file `routes.go` in the root directory of your project and add the following code:
```go "defining a route"
router.Get("/greeting", func(c *core.Context) *core.Response {
JsonString := `{"message": "hello world"}`
return c.Response.Json(JsonString)
})
```
Next, in your terminal navigate to the project dir and run the following command to start the `live reloading`:
```go
gocondor run:dev
```
Finally, open up your browser and navigate to `http://localhost/greeting`
To learn more check the [routing docs section](https://gocondor.github.io/docs/routing)
## Architecture
The architecture is similar to `MVC`, where there is a routes file `./routes.go` in which you can map all your app routes to their controllers which resides in the directory `./controllers`. Controllers are simply methods that handles requests (GET, POST, ... etch) to the given routes.
## The request journey:
The first component that receive's the request in `Cup` is the `Router`,
then `Goffee` locates the matching [handler](https://gocondor.github.io/docs/handlers) of the request and it check's if there are any [middlewares](https://gocondor.github.io/docs/middlewares) to be executed either before or after the [handler](https://gocondor.github.io/docs/handlers), if so, it executes them in the right order, then at the final stage it returns the response to the user.
`Request -> Router -> Optional Middlewares -> Handler -> Optional Middlewares -> Response`
## Folder structure
```bash
├── cup
│ ├── config/ --------------------------> main configs
│ ├── events/ --------------------------> contains events
│ │ ├── jobs/ ------------------------> contains the event jobs
│ ├── controllers/ ------------------------> route's controllers
│ ├── logs/ ----------------------------> app log files
│ ├── hooks/ ---------------------> app hooks
│ ├── models/ --------------------------> database models
│ ├── storage/ -------------------------> a place to store files
│ ├── tls/ -----------------------------> tls certificates
│ ├── .env -----------------------------> environment variables
│ ├── .gitignore -----------------------> .gitignore
│ ├── go.mod ---------------------------> Go modules
│ ├── LICENSE --------------------------> license
│ ├── main.go --------------------------> go main file
│ ├── README.md ------------------------> readme file
│ ├── register-events.go ---------------> register events and jobs
│ ├── register-global-hooks.go ---> register global middlewares
│ ├── routes.go ------------------------> app routes
│ ├── run-auto-migrations.go -----------> database migrations
```