1 Star 0 Fork 80

skykainls / faygo

forked from andeyalee / faygo 
加入 Gitee
与超过 1200万 开发者一起发现、参与优秀开源项目,私有仓库也完全免费 :)
免费加入
克隆/下载
贡献代码
同步代码
取消
提示: 由于 Git 不支持空文件夾,创建文件夹后会生成空的 .keep 文件
Loading...
README
Apache-2.0

Faygo report card github issues github closed issues GitHub release GoDoc

Faygo Favicon

概述

Faygo 是一款快速、简洁的Go Web框架,可用极少的代码开发出高性能的Web应用程序(尤其是API接口)。只需定义 struct Handler,Faygo 就能自动绑定、验证请求参数并生成在线API文档。

官方QQ群:Go-Web 编程 42730308 Go-Web 编程群

查看《用户手册》

faygo index

faygo apidoc

faygo server

最新版本

版本号

v1.1

安装要求

Go Version ≥1.8

快速使用

  • 方式一 源码下载
go get -u -v github.com/henrylee2cn/faygo
go get -u -v github.com/henrylee2cn/fay
        fay command [arguments]

The commands are:
        new        创建、编译和运行(监控文件变化)一个新的faygo项目
        run        编译和运行(监控文件变化)任意一个已存在的golang项目

fay new appname [apptpl]
        appname    指定新faygo项目的创建目录
        apptpl     指定一个faygo项目模板(可选)

fay run [appname]
        appname    指定待运行的golang项目路径(可选)

框架特性

  • 一个 struct Handler 搞定多件事:
  • 定义 Handler/Middleware
  • 绑定与验证请求参数
  • 生成 Swagger2.0 API 在线文档
  • 数据库 ORM 映射
  • Handler与Middleware完全相同,都是实现Handler接口(funcstruct类型),共同构成路由操作链,只是概念层面的说法不同
  • 支持多种网络类型:
网络类型 配置net_types
HTTP http
HTTPS/HTTP2(TLS) https
HTTPS/HTTP2(Let's Encrypt TLS) letsencrypt
HTTPS/HTTP2(Let's Encrypt TLS on UNIX socket) unix_letsencrypt
HTTP(UNIX socket) unix_http
HTTPS/HTTP2(TLS on UNIX socket) unix_https
  • 支持单服务单监听、单服务多监听、多服务多监听等,多个服务的配置信息相互独立
  • 基于 httprouter 开发高性能路由,支持链式与树形两种注册风格,支持灵活的静态文件路由(如DirFS、RenderFS、MarkdownFS等)
  • 支持平滑关闭、平滑升级,提供fay工具进行新建项目、热编译、元编程
  • 采用最强大的 pongo2 作为HTML渲染引擎
  • 提供近似LRU的文件缓存功能,主要用途是静态文件缓存
  • 跨平台的彩色日志系统,且同时支持console和file两种输出形式(可以同时使用)
  • 提供Session管理功能
  • 支持Gzip全局配置
  • 提供XSRF跨站请求伪造安全过滤
  • 大多数功能尽量使用简洁的ini进行配置来避免不必要的重新编译,并且这些配置文件支持自动补填默认值
  • 提供 gormxormsqlxdirectSQLWebsocketinihttp client 等很多常用扩展包

faygo struct handler 多重用途合一

简单示例

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"
    }
*/

示例库

操作和中间件

操作和中间件是相同的,都是实现了Handler接口!

  • 函数类型
// 不含API文档描述
func Page() faygo.HandlerFunc {
    return func(ctx *faygo.Context) error {
        return ctx.String(200, "faygo")
    }
}

// 含API文档描述
var Page2 = faygo.WrapDoc(Page(), "测试页2的注意事项", "文本")
  • 结构体类型
// Param操作通过Tag绑定并验证请求参数
type Param struct {
    Id    int    `param:"<in:path> <required> <desc:ID> <range: 0:10>"`
    Title string `param:"<in:query>"`
}

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

// Doc实现API文档接口(可选)
func (p *Param) Doc() faygo.Doc {
    return faygo.Doc{
        // 向API文档声明接口注意事项
        Note: "param desc",
        // 向API文档声明响应内容格式
        Return: faygo.JSONMsg{
            Code: 1,
            Info: "success",
        },
        // 向API文档增加额外的请求参数声明(可选)
        Params: []faygo.ParamInfo{
            {
                Name:  "additional",
                In:    "path",
                Model: "a",
                Desc:  "defined by the `Doc()` method",
            },
        },
    }
}

过滤函数

过滤函数必须是HandlerFunc类型!

func Root2Index(ctx *faygo.Context) error {
    // 不允许直接访问`/index`
    if ctx.Path() == "/index" {
        ctx.Stop()
        return nil
    }
    if ctx.Path() == "/" {
        ctx.ModifyPath("/index")
    }
    return nil
}

路由注册

  • 树状
// 新建应用服务,参数:名称、版本
var app1 = faygo.New("myapp1", "1.0")

// 路由
app1.Filter(Root2Index).
    Route(
        app1.NewNamedGET("测试页1", "/page", Page()),
        app1.NewNamedGET("测试页2", "/page2", Page2),
        app1.NewGroup("home",
            app1.NewNamedGET("test param", "/param", &Param{
                // 为绑定的参数设定API文档中缺省值(可选)
                Id:    1,
                Title: "test param",
            }),
        ),
    )
  • 链状
// 新建应用服务,参数:名称、版本
var app2 = faygo.New("myapp2", "1.0")

// 路由
app2.Filter(Root2Index)
app2.NamedGET("test page", "/page", Page())
app2.NamedGET("test page2", "/page2", Page2)
app2.Group("home")
{
    app2.NamedGET("test param", "/param", &Param{
        // 为绑定的参数设定API文档中缺省值(可选)
        Id:    1,
        Title: "test param",
    })
}

平滑关闭与重启

  • 平滑关闭
kill [pid]
  • 平滑重启
kill -USR2 [pid]

配置文件说明

  • 应用的各服务均有单独一份配置,其文件名格式 config/{appname}[_{version}].ini,配置详情:
net_types              = http|https              # 多种网络类型列表,支持 http | https | unix_http | unix_https | letsencrypt | unix_letsencrypt
addrs                  = 0.0.0.0:80|0.0.0.0:443  # 多个监听地址列表
tls_certfile           =                         # TLS证书文件路径
tls_keyfile            =                         # TLS密钥文件路径
letsencrypt_dir        =                         # Let's Encrypt TLS证书缓存目录
unix_filemode          = 0666                    # UNIX listener的文件权限,要求使用八进制
read_timeout           = 0s                      # 读取请求数据超时;ns|µs|ms|s|m|h
write_timeout          = 0s                      # 写入响应数据超时;ns|µs|ms|s|m|h
multipart_maxmemory_mb = 32                      # 接收上传文件时允许使用的最大内存
slow_response_threshold= 0s                      # 当响应时长 > slow_response_threshold时, 日志级别调整为 'WARNING';0 表示不限;ns|µs|ms|s|m|h
print_body             = false                   # 以JSON格式打印表单请求的body,其它类型请求原样打印body

[router]                                         # 路由配置区
redirect_trailing_slash   = true                 # 当前请求的URL含`/`后缀如`/foo/`且相应路由不存在时,如存在`/foo`,则自动跳转至`/foo`
redirect_fixed_path       = true                 # 自动修复URL,如`/FOO` `/..//Foo`均被跳转至`/foo`(依赖redirect_trailing_slash=true)
handle_method_not_allowed = true                 # 若开启,当前请求方法不存在时返回405,否则返回404
handle_options            = true                 # 若开启,自动应答OPTIONS类请求,可在Faygo中设置默认Handler
default_upload            = true                 # 自动注册默认静态路由: /upload/*filepath
default_static            = true                 # 自动注册默认静态路由: /static/*filepath

[xsrf]                                           # XSRF跨站请求伪造过滤配置区
enable        = false                            # 是否开启
key           = faygoxsrf                        # 加密key
expire_second = 3600                             # xsrf防伪token有效时长

[session]                                        # Session配置区(详情参考beego session模块)
enable                 = false                   # 是否开启
provider               = memory                  # 数据存储方式
name                   = faygosessionID        # 客户端存储cookie的名字
provider_config        =                         # 配置信息,根据不同的引擎设置不同的配置信息
cookie_life_second     = 0                       # 客户端存储的cookie的时间,默认值是0,即浏览器生命周期
gc_life_second         = 300                     # 触发GC的时间
max_life_second        = 3600                    # 会话的最大生命周期
auto_setcookie         = true                    # 是否自动设置关于session的cookie值,一般默认true
domain                 =                         # 可以访问此cookie的域名
enable_sid_in_header   = false                   # 是否将session ID写入Header
name_in_header         = Faygosessionid        # 将session ID写入Header时的头名称
enable_sid_in_urlquery = false                   # 是否将session ID写入url的query部分

[apidoc]                                         # API文档
enable      = true                               # 是否启用
path        = /apidoc                            # 访问的URL路径
nolimit     = false                              # 是否不限访问IP
real_ip     = false                              # 使用真实客户端的IP进行过滤
whitelist   = 192.*|202.122.246.170              # 表示允许带有`192.`前缀或等于`202.122.246.170`的IP访问
desc        =                                    # 项目描述
email       =                                    # 联系人邮箱
terms_url   =                                    # 服务条款URL
license     =                                    # 协议类型
license_url =                                    # 协议内容URL
  • 应用只有一份全局配置,文件名为 config/__global__.ini,配置详情:
[cache]                                          # 文件内存缓存配置区
enable         = false                           # 是否开启
size_mb        = 32                              # 允许缓存使用的最大内存(单位MB),为0时系统自动设置为512KB
expire_second  = 60                              # 缓存最大时长

[gzip]                                           # gzip压缩配置区
enable         = false                           # 是否开启
min_length     = 20                              # 进行压缩的最小内容长度
compress_level = 1                               # 非文件类响应Body的压缩水平(0-9),注意文件压缩始终为最优压缩比(9)
methods        = GET                             # 允许压缩的请求方法,为空时默认为GET

[log]                                            # 日志配置区
console_enable = true                            # 是否启用控制台日志
console_level  = debug                           # 控制台日志打印水平:critical | error | warning | notice | info | debug
file_enable    = true                            # 是否启用文件日志
file_level     = debug                           # 文件日志打印水平:critical | error | warning | notice | info | debug
async_len      = 0                               # 0表示同步打印,大于0表示异步缓存长度

Handler结构体字段标签说明

tag key required value desc
param in 有且只有一个 path (参数位置)为空时自动补全,如URL http://www.abc.com/a/{path}
param in 有且只有一个 query (参数位置)如URL http://www.abc.com/a?b={query}
param in 有且只有一个 formData (参数位置)请求表单,如 a=123&b={formData}
param in 有且只有一个 body (参数位置)请求Body
param in 有且只有一个 header (参数位置)请求头
param in 有且只有一个 cookie (参数位置)请求cookie,支持:*http.Cookiehttp.Cookiestring[]byte
param name (如id) 自定义参数名
param required required 参数是否必须
param desc (如id) 参数描述
param len (如3:6``3) 字符串类型参数的长度范围
param range (如0:10) 数字类型参数的数值范围
param nonzero nonzero 是否能为零值
param maxmb (如32) 当前Content-Typemultipart/form-data时,允许使用的最大内存,当设置了多个时使用较大值
param regexp (如^\w+$) 使用正则验证参数值
param err (如密码格式错误) 自定义参数绑定或验证的错误信息

NOTES:

  • 绑定的对象必须为结构体指针类型
  • *multipart.FileHeader外,绑定的结构体字段类型不能为指针类型
  • param标签不存在,将尝试解析匿名字段
  • 当结构体标签informData且字段类型为*multipart.FileHeadermultipart.FileHeader[]*multipart.FileHeader[]multipart.FileHeader时,该参数接收文件类型
  • 当结构体标签incookie,字段类型必须为*http.Cookiehttp.Cookie
  • 标签in(formData)in(body)不能同时出现在同一结构体
  • 不能存在多个in(body)标签

Handler结构体字段类型说明

base slice special
string []string [][]byte
byte []byte [][]uint8
uint8 []uint8 *multipart.FileHeader (仅formData参数使用)
bool []bool []*multipart.FileHeader (仅formData参数使用)
int []int *http.Cookie (仅net/http下的cookie参数使用)
int8 []int8 http.Cookie (仅net/http下的cookie参数使用)
int16 []int16 struct (body参数使用或用于匿名字段扩展参数)
int32 []int32
int64 []int64
uint8 []uint8
uint16 []uint16
uint32 []uint32
uint64 []uint64
float32 []float32
float64 []float64

扩展包

扩展包 导入路径
各种条码 github.com/henrylee2cn/faygo/ext/barcode
比特单位 github.com/henrylee2cn/faygo/ext/bitconv
gorm数据库引擎 github.com/henrylee2cn/faygo/ext/db/gorm
sqlx数据库引擎 github.com/henrylee2cn/faygo/ext/db/sqlx
xorm数据库引擎 github.com/henrylee2cn/faygo/ext/db/xorm
directSQL(配置化SQL引擎) github.com/henrylee2cn/faygo/ext/db/directsql
口令算法 github.com/henrylee2cn/faygo/ext/otp
UUID github.com/henrylee2cn/faygo/ext/uuid
Websocket github.com/henrylee2cn/faygo/ext/websocket
ini配置 github.com/henrylee2cn/faygo/ini
定时器 github.com/henrylee2cn/faygo/ext/cron
任务工具 github.com/henrylee2cn/faygo/ext/task
HTTP客户端 github.com/henrylee2cn/faygo/ext/surfer

已知案例

产品名称 Web/App 服务器 主页
盯房 App https://www.df-house.com
e交易 App https://fir.im/ejy
Seven A Jewelry Web http://sevenajewelry.com
玩付 App https://fir.im/eqb
杰运好车 App https://www.jieyunhaoche.com/appdown

注:按拼音字母排序

开源协议

Faygo 项目采用商业应用友好的 Apache2.0 协议发布

Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 1. Definitions. "License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document. "Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License. "Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity. "You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License. "Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files. "Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types. "Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below). "Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof. "Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution." "Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work. 2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form. 3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed. 4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions: (a) You must give any other recipients of the Work or Derivative Works a copy of this License; and (b) You must cause any modified files to carry prominent notices stating that You changed the files; and (c) You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and (d) If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License. You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License. 5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions. 6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file. 7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License. 8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages. 9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability. END OF TERMS AND CONDITIONS APPENDIX: How to apply the Apache License to your work. To apply the Apache License to your work, attach the following boilerplate notice, with the fields enclosed by brackets "{}" replaced with your own identifying information. (Don't include the brackets!) The text should be enclosed in the appropriate comment syntax for the file format. We also recommend that a file or class name and description of purpose be included on the same "printed page" as the copyright notice for easier identification within third-party archives. Copyright 2016 HenryLee Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

简介

Faygo 是一款快速、简洁的Go Web框架,可用极少的代码开发出高性能的Web应用程序(尤其是API接口)。只需定义 struct Handler,Faygo 就能自动绑定、验证请求参数并生成在线API文档。 展开 收起
Go
Apache-2.0
取消

发行版

暂无发行版

贡献者

全部

近期动态

加载更多
不能加载更多了
Go
1
https://gitee.com/skykain/faygo.git
git@gitee.com:skykain/faygo.git
skykain
faygo
faygo
master

搜索帮助

14c37bed 8189591 565d56ea 8189591