bean

README

BEAN (豆)

A web framework written in GO on-top of echo to ease your application development. Our main goal is not to compete with other Go framework instead we are mainly focusing on tooling and structuring a project to make developers life a bit easier and less stressful to maintain their project more in a lean way.

We are heavily working on a separate documentation page. Please stay tune and we will keep you updated here.

• BEAN (豆)
  • How to use
    • Initialize a project
  • Service-Repository Pattern
  • How To Create Repository File(s)
  • One Liner To Create Service And Repositories
  • How To Create Handler
  • Two Build Commands
  • Built-In Logging
  • Secret Key
  • Code Styling
    • Comment
  • Do’s and Don’ts
    • Context
    • Pointer

How to use

Initialize a project

1. Install the package by

go install github.com/retail-ai-inc/bean/cmd/bean@latest

1. Create a project directory

mkdir myproject && cd myproject

1. Initialize the project using bean by

bean init myproject

or

bean init github.com/me/myproject

The above command will produce a nice directory structure with all necessary configuration files and code to start your project quickly. Now, let's build your project and start:

make build
./myproject start

https://user-images.githubusercontent.com/61860255/155534942-b9ee6b70-ccf3-4cd6-a7c3-bc8bd5089626.mp4

Service-Repository Pattern

Bean is using service repository pattern for any database, file or external transaction. The repository provides a collection of interfaces to access data stored in a database, file system or external service. Data is returned in the form of structs or interface. The main idea to use Repository Pattern is to create a bridge between models and handlers. Here is a simple pictorial map to understand the service-repository pattern in a simple manner:

How To Create Repository File(s)

bean create repo login
bean create repo logout

Above two commands will create 2 repository files under repositories folder as login.go and logout.go.

Now let's associate the above repository files with a service called auth:

bean create service auth --repo login --repo logout

Above command will create a pre-defined sample service file under services folder as auth.go and automatically set the type authService struct and func NewAuthService.

Now you can run make build or make build-slim to compile your newly created service with repositories.

One Liner To Create Service And Repositories

bean create service auth --repo login --repo profile,logout

OR

bean create service auth -r login -r profile,logout

Above command will create both service repository files if it doesn't exist and automatically set the association.

How To Create Handler

bean create handler auth

Above command will create a pre-defined sample handler file under handlers folder as auth.go. Furthermore, if you already create an auth service with same name as auth then bean will automatically associate your handler with the auth service in route.go.

Two Build Commands

Bean supporting 2 build commands:

• make build - This is usual go build command.
• make build-slim - This will create a slim down version of your binary by turning off the DWARF debugging information and Go symbol table. Furthemore, this will exclude file system paths from the resulting binary using -trimpath.

Built-In Logging

Bean has a pre-builtin logging system. If you open the env.json file from your project directory then you should see some configuration like below:

"accessLog": {
  "on": true,
  "bodyDump": true,
  "path": "",
  "bodyDumpMaskParam": []
}

• on - Turn on/off the logging system. Default is true.
• bodyDump - Log the request-response body in the log file. This is helpful for debugging purpose. Default true
• path - Set the log file path. You can set like logs/console.log. Empty log path allow bean to log into stdout
• bodyDumpMaskParam - For security purpose if you don't wanna bodyDump some sensetive request parameter then you can add those as a string into the slice like ["password", "secret"]. Default is empty.

Secret Key

In env.json file bean is maintaining a key called secret. This is a 32 character long random alphanumeric string. It's a multi purpose hash key or salt which you can use in your project to generate JWT, one way hash password, encrypt some private data or session. By default, bean is providing a secret however, you can generate a new one by entering the following command from your terminal:

./myproject gen secret

Code Styling

Comment

Please use // for any comment:

// This is a single line comment.

// This is a
// multiline comment.

For some special message, please add appropiate TAG at the beginning of the comment.

// IMPORTANT: This is super important comment.
// WARN:
// TODO:
// FIX:
// ISSUE:

Do’s and Don’ts

Context

Do not use c.Get and c.Set in Service and Repository layer to avoid confusion, because c.Get and c.Set is using hardcoded variable name for storing the data. Instead of storing the variable inside the echo.Context, just pass it explicitly through function parameters.

Pointer

As in all languages in the C family, everything in Go is passed by value. That is, a function
always gets a copy of the thing being passed, as if there were an assignment statement assigning
the value to the parameter. For instance, passing an int value to a function makes a copy of the
int, and passing a pointer value makes a copy of the pointer, but not the data it points to.

For complicated object, pointer should be used as parameter instead of values to reduce the usage of copying the whole object. ref: https://go.dev/doc/faq#pass_by_value

Documentation

Overview

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Index

• func NewEcho(config Config) *echo.Echo
• type Bean
  • func New(config Config) (b *Bean)
  • func (b *Bean) DefaultHTTPErrorHandler() echo.HTTPErrorHandler
  • func (b *Bean) InitDB()
  • func (b *Bean) ServeAt(host, port string)
  • func (b *Bean) UseErrorHandlerFuncs(errHdlrFuncs ...berror.ErrorHandlerFunc)
  • func (b *Bean) UseMiddlewares(middlewares ...echo.MiddlewareFunc)
  • func (b *Bean) UseValidation(validateFuncs ...validator.ValidatorFunc)
• type Config
• type DBDeps

Functions

func NewEcho

func NewEcho(config Config) *echo.Echo

Types

type Bean

type Bean struct {
	DBConn      *DBDeps
	Echo        *echo.Echo
	BeforeServe func()

	Config Config
	// contains filtered or unexported fields
}

func New

func New(config Config) (b *Bean)

func (*Bean) DefaultHTTPErrorHandler

func (b *Bean) DefaultHTTPErrorHandler() echo.HTTPErrorHandler

func (*Bean) InitDB

func (b *Bean) InitDB()

InitDB initialize all the database dependencies and store it in global variable `global.DBConn`.

func (*Bean) ServeAt

func (b *Bean) ServeAt(host, port string)

func (*Bean) UseErrorHandlerFuncs

func (b *Bean) UseErrorHandlerFuncs(errHdlrFuncs ...berror.ErrorHandlerFunc)

func (*Bean) UseMiddlewares

func (b *Bean) UseMiddlewares(middlewares ...echo.MiddlewareFunc)

func (*Bean) UseValidation

func (b *Bean) UseValidation(validateFuncs ...validator.ValidatorFunc)

type Config

type Config struct {
	ProjectName  string
	Environment  string
	DebugLogPath string
	Secret       string
	AccessLog    struct {
		On                bool
		BodyDump          bool
		Path              string
		BodyDumpMaskParam []string
	}
	Prometheus struct {
		On            bool
		SkipEndpoints []string
	}
	HTTP struct {
		Port            string
		Host            string
		BodyLimit       string
		IsHttpsRedirect bool
		Timeout         time.Duration
		KeepAlive       bool
		AllowedMethod   []string
		SSL             struct {
			On            bool
			CertFile      string
			PrivFile      string
			MinTLSVersion uint16
		}
	}
	HTML struct {
		ViewsTemplateCache bool
	}
	Database struct {
		Tenant struct {
			On bool
		}
		MySQL  dbdrivers.SQLConfig
		Mongo  dbdrivers.MongoConfig
		Redis  dbdrivers.RedisConfig
		Badger dbdrivers.BadgerConfig
	}
	Sentry   options.SentryConfig
	Security struct {
		HTTP struct {
			Header struct {
				XssProtection         string
				ContentTypeNosniff    string
				XFrameOptions         string
				HstsMaxAge            int
				ContentSecurityPolicy string
			}
		}
	}
}

type DBDeps

type DBDeps struct {
	MasterMySQLDB      *gorm.DB
	MasterMySQLDBName  string
	TenantMySQLDBs     map[uint64]*gorm.DB
	TenantMySQLDBNames map[uint64]string
	MasterMongoDB      *mongo.Client
	MasterMongoDBName  string
	TenantMongoDBs     map[uint64]*mongo.Client
	TenantMongoDBNames map[uint64]string
	MasterRedisDB      *redis.Client
	MasterRedisDBName  int
	TenantRedisDBs     map[uint64]*redis.Client
	TenantRedisDBNames map[uint64]int
	BadgerDB           *badger.DB
}

All database connections are initialized using `DBDeps` structure.