Faygo

Faygo is a fast and concise Go Web framework that can be used to develop high-performance web app(especially API) with fewer codes. Just define a struct Handler, Faygo will automatically bind/verify the request parameters and generate the online API doc. Go to <User Manual>

简体中文

Latest version

Version

v1.2.0

Requirements

Go Version ≥ 1.8

Quick Start

• Way 1: download source

go get -u -v github.com/henrylee2cn/faygo

• Way 2: deployment tools (Go to fay)

go get -u -v github.com/henrylee2cn/fay

        fay command [arguments]

The commands are:
        new        create, compile and run (monitor changes) a new faygo project
        run        compile and run (monitor changes) an any existing go project

fay new appname [apptpl]
        appname    specifies the path of the new faygo project
        apptpl     optionally, specifies the faygo project template type

fay run [appname]
        appname    optionally, specifies the path of the new project

Features

• One struct Handler can get more things:

• Define Handler/Middleware
• Bind and verify request parameters
• Generate an online document for the Swagger 2.0 API
• Database ORM mapping

• Handler and Middleware are exactly the same, both implement the Handler interface (func or struct), which together constitute the handler chain of the router.
• Supports multiple network types:

• Support single-service & single-listener, single-service & multi-listener, multi-service & multi-listener and so on. The config of multiple services is independent of each other
• The high-performance router based on httprouter supports both chain and tree registration styles; supports flexible static file router (such as DirFS, RenderFS, MarkdownFS, etc.)
• Support graceful shutdown and rebooting, provide fay tools which has new projects, hot compilation , meta programming function
• Use the most powerful pongo2 as the HTML rendering engine
• Support near-LRU memory caching (mainly used for static file cache)
• Support cross-platform color log system, and has two output interface(console and file)
• Support session management (If you use a persistent storage engine, you must use gob.Register() to register the relevant custom type before starting the service)
• Support global gzip compression config
• Support XSRF security filtering
• Most features try to use simple ini configs to avoid unnecessary recompilation, and these profiles can be automatically assigned default values
• Provide gorm, xorm, sqlx, directSQL, Websocket, ini, http client and many other commonly used expansion packages

Simple example

package main

import (
    // "mime/multipart"
    "time"
    "github.com/henrylee2cn/faygo"
)

type Index struct {
    Id        int      `param:"<in:path> <required> <desc:ID> <range: 0:10>"`
    Title     string   `param:"<in:query> <nonzero>"`
    Paragraph []string `param:"<in:query> <name:p> <len: 1:10> <regexp: ^[\\w]*$>"`
    Cookie    string   `param:"<in:cookie> <name:faygoID>"`
    // Picture         *multipart.FileHeader `param:"<in:formData> <name:pic> <maxmb:30>"`
}

func (i *Index) Serve(ctx *faygo.Context) error {
    if ctx.CookieParam("faygoID") == "" {
        ctx.SetCookie("faygoID", time.Now().String())
    }
    return ctx.JSON(200, i)
}

func main() {
    app := faygo.New("myapp", "0.1")

    // Register the route in a chain style
    app.GET("/index/:id", new(Index))

    // Register the route in a tree style
    // app.Route(
    //     app.NewGET("/index/:id", new(Index)),
    // )

    // Start the service
    faygo.Run()
}

/*
http GET:
    http://localhost:8080/index/1?title=test&p=abc&p=xyz
response:
    {
        "Id": 1,
        "Title": "test",
        "Paragraph": [
            "abc",
            "xyz"
        ],
        "Cookie": "2016-11-13 01:14:40.9038005 +0800 CST"
    }
*/

All samples

Handler and middleware

Handler and middleware are the same, both implemente Handler interface!

• function type

// Page handler doesn't contains API doc description
func Page() faygo.HandlerFunc {
    return func(ctx *faygo.Context) error {
        return ctx.String(200, "faygo")
    }
}

// Page2 handler contains API doc description
var Page2 = faygo.WrapDoc(Page(), "test page2 notes", "test")

• struct type

// Param binds and validates the request parameters by Tags
type Param struct {
    Id    int    `param:"<in:path> <required> <desc:ID> <range: 0:10>"`
    Title string `param:"<in:query>"`
}

// Serve implemente Handler interface
func (p *Param) Serve(ctx *faygo.Context) error {
    return ctx.JSON(200,
        faygo.Map{
            "Struct Params":    p,
            "Additional Param": ctx.PathParam("additional"),
        }, true)
}

// Doc implemente API Doc interface (optional)
func (p *Param) Doc() faygo.Doc {
    return faygo.Doc{
        // Add the API notes to the API doc
        Note: "param desc",
        // declare the response content format to the API doc
        Return: faygo.JSONMsg{
            Code: 1,
            Info: "success",
        },
        // additional request parameter declarations to the API doc (optional)
        Params: []faygo.ParamInfo{
            {
                Name:  "additional",
                In:    "path",
                Model: "a",
                Desc:  "defined by the `Doc()` method",
            },
        },
    }
}

Filter function

The filter function must be HandleFunc type!

func Root2Index(ctx *faygo.Context) error {
    // Direct access to `/index` is not allowed
    if ctx.Path() == "/index" {
        ctx.Stop()
        return nil
    }
    if ctx.Path() == "/" {
        ctx.ModifyPath("/index")
    }
    return nil
}

Route registration

• tree style

// New application object, params: name, version
var app1 = faygo.New("myapp1", "1.0")

// router
app1.Filter(Root2Index).
    Route(
        app1.NewNamedGET("test page", "/page", Page()),
        app1.NewNamedGET("test page2", "/page2", Page2),
        app1.NewGroup("home",
            app1.NewNamedGET("test param", "/param", &Param{
                // sets the default value in the API documentation for the request parameters (optional)
                Id:    1,
                Title: "test param",
            }),
        ),
    )

• chain style

// New application object, params: name, version
var app2 = faygo.New("myapp2", "1.0")

// router
app2.Filter(Root2Index)
app2.NamedGET("test page", "/page", Page())
app2.NamedGET("test page2", "/page2", Page2)
app2.Group("home")
{
    app2.NamedGET("test param", "/param", &Param{
        // sets the default value in the API documentation for the request parameters(optional)
        Id:    1,
        Title: "test param",
    })
}

Shutdown and reboot

• shutdown gracefully

kill [pid]

• reboot gracefully

kill -USR2 [pid]

Configuration

• Each instance of the application has a single config (file name format config/{appname}[_{version}].ini). Refer to the following:

net_types              = http|https              # List of network type: http | https | unix_http | unix_https | letsencrypt | unix_letsencrypt
addrs                  = 0.0.0.0:80|0.0.0.0:443  # List of multiple listening addresses
tls_certfile           =                         # TLS certificate file path
tls_keyfile            =                         # TLS key file path
letsencrypt_dir        =                         # Let's Encrypt TLS certificate cache directory
unix_filemode          = 0666                    # File permissions for UNIX listener, requires octal number
http_redirect_https    = false                   # Redirect from 'http://hostname:port1' to 'https://hostname:port2'
read_timeout           = 0s                      # Maximum duration for reading the full; ns|µs|ms|s|m|h request (including body)
write_timeout          = 0s                      # Maximum duration for writing the full; ns|µs|ms|s|m|h response (including body)
multipart_maxmemory_mb = 32                      # Maximum size of memory that can be used when receiving uploaded files
slow_response_threshold= 0s                      # When response time > slow_response_threshold, log level   = 'WARNING'; 0 means not limited; ns|µs|ms|s|m|h
print_body             = false                   # Form requests are printed in JSON format, but other types are printed as-is

[router]                                         # Routing config section
redirect_trailing_slash   = true                 # Automatic redirection (for example, `/foo/` -> `/foo`)
redirect_fixed_path       = true                 # Tries to fix the current request path, if no handle is registered for it
handle_method_not_allowed = true                 # Returns 405 if the requested method does not exist, otherwise returns 404
handle_options            = true                 # Automatic response OPTIONS request, you can set the default Handler in Faygo
no_default_params         = false                # If true, don't assign default request parameter values based on initial parameter values of the routing handler
default_upload            = true                 # Automatically register the default router: /upload/*filepath
default_static            = true                 # Automatically register the default router: /static/*filepath

[xsrf]                                           # XSRF security section
enable        = false                            # Whether enabled or not
key           = faygoxsrf                        # Encryption key
expire_second = 3600                             # Expire of XSRF token

[session]                                        # Session section
enable                 = false                   # Whether enabled or not
provider               = memory                  # Data storage
name                   = faygosessionID          # The client stores the name of the cookie
provider_config        =                         # According to the different engine settings different config information
cookie_life_second     = 0                       # The default value is 0, which is the lifetime of the browser
gc_life_second         = 300                     # The interval between triggering the GC
max_life_second        = 3600                    # The session max lefetime
auto_setcookie         = true                    # Automatically set on the session cookie value, the general default true
domain                 =                         # The domain name that is allowed to access this cookie
enable_sid_in_header   = false                   # Whether to write a session ID to the header
name_in_header         = Faygosessionid          # The name of the header when the session ID is written to the header
enable_sid_in_urlquery = false                   # Whether to write the session ID to the URL Query params

[apidoc]                                         # API documentation section
enable      = true                               # Whether enabled or not
path        = /apidoc                            # The URL path
nolimit     = false                              # If true, access is not restricted
real_ip     = false                              # If true, means verifying the real IP of the visitor
whitelist   = 192.*|202.122.246.170              # `whitelist=192.*|202.122.246.170` means: only IP addresses that are prefixed with `192.` or equal to `202.122.246.170` are allowed
desc        =                                    # Description of the application
email       =                                    # Technician's Email
terms_url   =                                    # Terms of service
license     =                                    # The license used by the API
license_url =                                    # The URL of the protocol content page

• Only one global config is applied (config/__global__.ini). Refer to the following:

[cache]                                          # Cache section
enable         = false                           # Whether enabled or not
size_mb        = 32                              # Max size by MB for file cache, the cache size will be set to 512KB at minimum.
expire_second  = 60                              # Maximum duration for caching

[gzip]                                           # compression section
enable         = false                           # Whether enabled or not
min_length     = 20                              # The minimum length of content to be compressed
compress_level = 1                               # Non-file response Body's compression level is 0-9, but the files' always 9
methods        = GET                             # List of HTTP methods to compress. If not set, only GET requests are compressed.

[log]                                            # Log section
console_enable = true                            # Whether enabled or not console logger
console_level  = debug                           # Console logger level: critical | error | warning | notice | info | debug
file_enable    = true                            # Whether enabled or not file logger
file_level     = debug                           # File logger level: critical | error | warning | notice | info | debug
async_len      = 0                               # The length of asynchronous buffer, 0 means synchronization

Handler struct tags

NOTES:

• the binding object must be a struct pointer
• in addition to *multipart.FileHeader, the binding struct's field can not be a pointer
• if the param tag is not exist, anonymous field will be parsed
• when the param's position(in) is formData and the field's type is *multipart.FileHeader, multipart.FileHeader, []*multipart.FileHeader or []multipart.FileHeader, the param receives file uploaded
• if param's position(in) is cookie, field's type must be *http.Cookie or http.Cookie
• param tags in(formData) and in(body) can not exist at the same time
• there should not be more than one in(body) param tag

Handler struct fields type

Expansion package

Know Cases

Note: Sorted in alphabetical order

Business Users

License

Faygo is under Apache v2 License. See the LICENSE file for the full license text