go-webapp-sample

Preface

This repository is the sample of web application using golang.
This sample uses Echo as web application framework, Gorm as OR mapper and Zap logger as logger.
This sample application provides only several functions as Web APIs.
Please refer to the ‘Service’ section about the detail of those functions.

Also, this application contains the static contents such as html file, css file and javascript file which built vuejs-webapp-sample project to easily check the behavior of those functions.
So, you can check this application without starting a web server for front end.
Please refer to the ‘Starting Server’ section about checking the behavior of this application.

If you would like to develop a web application using golang, please feel free to use this sample.

Install

Perform the following steps:

1. Download and install Visual Studio Code(VS Code).
2. Download and install Golang.
3. Get the source code of this repository by the following command.

    go install github.com/ybkuroki/go-webapp-sample@latest

Starting Server

There are 2 methods for starting server.

Without Web Server

1. Starting this web application by the following command.

    go run main.go

2. When startup is complete, the console shows the following message:

    http server started on [::]:8080

3. Access http://localhost:8080 in your browser.
4. Login with the following username and password.
   • username : test
   • password : test

With Web Server

Starting Application Server

1. Starting this web application by the following command.

    go run main.go

2. When startup is complete, the console shows the following message:

    http server started on [::]:8080

3. Access http://localhost:8080/api/health in your browser and confirm that this application has started.

    healthy

   Starting Web Server

4. Clone vuejs-webapp-sample project and install some tools.
5. Start by the following command.

    npm run dev

6. When startup is complete, the console shows the following message:
   ```

   vuejs-webapp-sample@..* dev
   vite —mode development

VITE v*.*.*  ready in 1362 ms
➜  Local:   http://localhost:3000/
➜  press h to show help
```

1. Access http://localhost:3000 in your browser.
2. Login with the following username and password.
   • username : test
   • password : test

With Docker

building Docker image

1. Run the below following commands:

    docker build -t go-webapp-sample .

2. command to start the container at port 8080

    docker run --name app -p 8080:8080 go-webapp-sample

3. Access http://localhost:8000 in your browser.
4. Login with the following username and password.
   • username : test
   • password : test

Using Swagger

In this sample, Swagger is enabled only when executed this application on the development environment.
Swagger isn’t enabled on the another environments in default.

Accessing to Swagger

1. Start this application according to the ‘Starting Application Server’ section.
2. Access http://localhost:8080/swagger/index.html in your browser.

Updating the existing Swagger document

1. Update some comments of some controllers.
2. Download Swag library. (Only first time)

    go install github.com/swaggo/swag/cmd/swag@latest

3. Update docs/docs.go.

    swag init

Build executable file

Build this source code by the following command.

go build main.go

Project Map

The following figure is the map of this sample project.

- go-webapp-sample
  + config                  … Define configurations of this system.
  + logger                  … Provide loggers.
  + middleware              … Define custom middleware.
  + migration               … Provide database migration service for development.
  + router                  … Define routing.
  + controller              … Define controllers.
  + model                   … Define models.
  + repository              … Provide a service of database access.
  + service                 … Provide a service of book management.
  + session                 … Provide session management.
  + test                    … for unit test
  - main.go                 … Entry Point.

Services

This sample provides 3 services: book management, account management, and master management.
Regarding the detail of the API specification, please refer to the ‘Using Swagger’ section.

Book Management

There are the following services in the book management.

Account Management

There are the following services in the Account management.

Master Management

There are the following services in the Master management.

Tests

Create the unit tests only for the packages such as controller, service, model/dto and util. The test cases is included the regular cases and irregular cases. Please refer to the source code in each packages for more detail.

The command for testing is the following:

go test ./... -v

Libraries

This sample uses the following libraries.

Contribution

Please read CONTRIBUTING.md for proposing new functions, reporting bugs and submitting pull requests before contributing to this repository.

License

The License of this sample is MIT License.