web

package module
v0.16.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 9, 2018 License: MIT Imports: 20 Imported by: 69

README

web Build Status Go version Go Report Card license codecov

web 是一个比较完整的 API 开发框架，相对于简单的路由，提供了更多的便利功能。

如果你只是需要一个简单的路由工具，那么你可以移步到 mux。

// main.go
func main() {
    encoding.AddMarshals(map[string]encoding.MarshaleFunc {
        "application/json": json.Marshal,
        "application/xml": xml.Marshal,
    })

    encoding.AddUnmarshals(map[string]encoding.UnmarshaleFunc {
        "application/json": json.Unmarshal,
        "application/xml": xml.Unmarshal,
    })

    result.NewMessages(map[int]string{...})

    web.Init("./appconfig", nil)

    // 注册模块信息
    m1.Init()
    m2.Init()

    logs.Fatal(web.Run())
}

// modules/m1/module.go
func Init() {
    web.NewModule("m1", "模块描述信息").
        GetFunc("/admins", getAdmins).
        GetFunc("/groups", getGroups)
}

// modules/m2/module.go
func Init() {
    web.NewModule("m2", "模块描述信息", "m1").
        GetFunc("/admins", getAdmins).
        GetFunc("/groups", getGroups)
}
项目结构

这只是推荐的目录结构，但不是必须按照此来。

|----- appconfig 配置文存放路径
|         |
|         +----- web.yaml 框架本身的配置文件
|         |
|         +----- logs.xml 日志配置文件
|
+----- common 一些公用的包
|
+----- modules 各个模块的代码
|         |
|         +----- module1
|         |
|         +----- module2
|
+----- main.go
配置文件

通过 web.Init() 函数，可以在初始化时指定配置文件所在的目录，目前 web 包本身需要一个配置文件 web.yaml 以下是该文件的所有配置项：

名称 类型 描述
debug bool 是否启用调试模式
domain string 项目的域名，若存在 allowedDomains 同时会加入到 allowedDomains 字段中
root string 项目的根路径，比如 /blog
plugins string 指定需要加载的插件，可以使用 glob 模式
https bool 是否启用 HTTPS
certFile string 当启用 HTTPS 时的 cert 文件
keyFile string 当启用 HTTPS 时的 key 文件
port int 监听的端口号
headers object 输出的报头，键名为报头名称，键值为对应的值
static object 静态内容，键名为 URL 地址，键值为对应的文件夹
disableOptions bool 是否禁用 OPTIONS 请求方法
allowedDomains array 限定访问域名，可以是多个，若不指定，表示不限定
readTimeout string 与 http.Server.ReadTimeout 相同
writeTimeout string 与 http.Server.WriteTimeout 相同
idleTimeout string 与 http.Server.IdleTimeout 相同
readHeaderTimeout string 与 http.Server.ReadHeaderTimeout 相同
compress.types array 指定可以使用 accept-encoding 输出的 mimetype 值
compress.size int 指定可以使用 accept-encoding 输出的最小内容大小
shutdownTimeout string 关闭服务的等待时间
url string 网站首页地址，一般可以不写，由 domain、root 和 port 自动拼成

详细的介绍可以参考 /internal/app/webconfig/webconfig.go 文件中的描述

在 debug 模式下，会添加两个调试用的地址：/debug/pprof/ 和 /debug/vars

日志处理

日志处理，采用 logs 包，一旦 web.Init() 调用，logs 包即是处于可用状态。 logs 的配置文件与 web.json 一样放在同一目录下，可根据需求自行修改。

web.Context 提供了一套与 logs 相同接口的日志处理方法，相对于直接调用 logs，这些方法可以输出更多的调试信息，但其底层还是调用 logs 完成相应功能。

字符集和媒体类型

输出的媒体类型与字符集由用户在配置文件中指定，而输入的媒体类型与字符集， 由客户端在请求时，通过 Content-Type 报头指定。 当然如果需要框架支持用户提交的类型，需要在框架初始化时，添加相关的编友支持： 由用户在开始前通过 AddMarshal() 和 AddUnmarshal() 来指定一个列表，在此列表内的编码和字符集，均可用。

错误处理

框架中提供了一个统一的错误返回类型：Result，其输出格式是固定的，类似以下：

{
    "code": 400001,
    "message": "error message",
    "detail": [
        {"field": "username", "message": "不能为空"},
        {"field": "password", "message": "不能为空"},
    ]
}

具体可参考代码文档中的有关 Result 的定义。

安装
go get github.com/issue9/web
文档

Go Walker GoDoc

版权

本项目采用 MIT 开源授权许可证，完整的授权说明可在 LICENSE 文件中找到。

Documentation

Overview

Package web 一个微型的 RESTful API 框架。

配置文件

配置文件的映射对象在 internal/config 包中，其中有各个字段的详细说明。 用户如果需要添加一些自定义的配置项，需要自行再添加其它名称的配置文件， 文件地址最好通过 web.File 来获取，这样可以和框架本身的配置文件存在同一目录下。

框架了除了本身的 web.yaml 配置文件之外，还有 logs.xml，用于定制日志的相关内容。 具体的日志相关信息，可以访问 https://github.com/issue9/logs 包。

字符集和媒体类型

encoding 包通过 AddMarshal 和 AddUnmarshal 给用户提供相关功能。

当然用户也可以直接构建一个 context.Context 对象来生成一个一次性的对象。

返回结果

框架内置了一个 result 包，用以统一向用户返回的错误信息，这是一个可选的包， 如果要使用，需要在 web.Run() 之前调用 result.NewMessages() 注册相关的错误代码。

模块

用户可以把功能相对独立的内容当作一个模块进行封装。框架本身提供了 web.NewModule() 对模块进行了依赖管理。用户可以在 web.NewModule() 返回对象中， 对模块进行初始化和路由项的添加。所有模块会在 web.Run() 中进行初始化。

Index

Constants

View Source 
const (
	// Version 当前框架的版本
	Version = "0.16.1+20180905"

	// MinimumGoVersion 需求的最低 Go 版本
	// 修改此值，记得同时修改 .travis.yml 文件中的版本依赖。
	MinimumGoVersion = "1.10"
)

Variables

This section is empty.

Functions

func AddCompress 

func AddCompress(name string, f compress.WriterFunc) error

AddCompress 添加压缩方法。框架本身已经指定了 gzip 和 deflate 两种方法。

NOTE: 只有在 web.Init() 之前调用才能启作用。

func AddErrorHandler 

func AddErrorHandler(f func(http.ResponseWriter, int), status ...int) error

AddErrorHandler 添加对错误状态码的处理方式。

status 表示状态码，如果为 0，则表示所有未指定的状态码。

func Close 

func Close() error

Close 关闭服务。

无论配置文件如果设置，此函数都是直接关闭服务，不会等待。

func File 

func File(path ...string) string

File 获取配置目录下的文件。

func Grace 

func Grace(sig ...os.Signal)

Grace 指定触发 Shutdown() 的信号，若为空，则任意信号都触发。

多次调用，则每次指定的信号都会起作用，如果由传递了相同的值， 则有可能多次触发 Shutdown()。

NOTE: 传递空值，与不调用，其结果是不同的。 若是不调用，则不会处理任何信号；若是传递空值调用，则是处理任何要信号。

func Handler 

func Handler() (http.Handler, error)

Handler 将当前实例当作一个 http.Handler 返回。一般用于测试。 比如在 httptest.NewServer 中使用。

func Init 

func Init(dir string) (err error)

Init 初始化整个应用环境

dir 表示配置文件的目录；

func Install 

func Install(version string) error

Install 执行指定版本的安装功能

func IsDebug 

func IsDebug() bool

IsDebug 是否处在调试模式

func LoadConfig 

func LoadConfig(path string, v interface{}) error

LoadConfig 从配置目录中加载数据到对象 v 中。

func Modules 

func Modules() []*module.Module

Modules 当前系统使用的所有模块信息

func Mux added in v0.16.1 

func Mux() *mux.Mux

Mux 返回 mux.Mux 实例。

func RegisterOnShutdown added in v0.16.1 

func RegisterOnShutdown(f func())

RegisterOnShutdown 注册在关闭服务时需要执行的操作。

func Run deprecated 

func Run() error

Run 运行路由，执行监听程序。

Deprecated: 由 Serve 代替

func Serve 

func Serve() error

Serve 运行路由，执行监听程序。

func SetCompress 

func SetCompress(name string, f compress.WriterFunc)

SetCompress 修改或是添加压缩方法。

NOTE: 只有在 web.Init() 之前调用才能启作用。

func SetErrorHandler 

func SetErrorHandler(f func(http.ResponseWriter, int), status ...int)

SetErrorHandler 设置指定状态码对应的处理函数

有则修改，没有则添加

status 表示状态码，如果为 0，则表示所有未指定的状态码。

func SetMiddleware 

func SetMiddleware(m middleware.Middleware)

SetMiddleware 设置一个全局的中间件，多次设置，只有最后一次会启作用。

func Shutdown 

func Shutdown() error

Shutdown 关闭所有服务。

根据配置文件中的配置项，决定当前是直接关闭还是延时之后关闭。

func URL 

func URL(path string) string

URL 构建一条完整 URL

Types

type Context 

type Context = context.Context

Context 等同于 context.Context，方便调用者使用

func NewContext 

func NewContext(w http.ResponseWriter, r *http.Request) *Context

NewContext 根据当前配置，生成 context.Context 对象，若是出错则 panic

type Module 

type Module = module.Module

Module 等同于 module.Module，方便调用者使用

func NewModule 

func NewModule(name, desc string, deps ...string) *Module

NewModule 注册一个模块

type Result 

type Result = result.Result

Result 等同于 result.Result，方便调用者使用

func NewResult 

func NewResult(code int) *Result

NewResult 生成一个 *result.Result 对象

Source Files

View all Source files

Directories

Path Synopsis
cmd
web Module
Package config 提供了对多种格式配置文件的支持
 Package config 提供了对多种格式配置文件的支持
Package context 用于处理单个请求的上下文关系。
 Package context 用于处理单个请求的上下文关系。
Package encoding 提供了框架内对编码和字符集功能的支持。
 Package encoding 提供了框架内对编码和字符集功能的支持。
encodingtest
Package encodingtest 针对文本内容的编解码实现，仅作为测试用例。
 Package encodingtest 针对文本内容的编解码实现，仅作为测试用例。
form
Package form 用于处理 www-form-urlencoded 编码 func read(w http.ResponseWriter, r *http.Request) { ctx := web.New(w, r) vals := urls.Values{} !ctx.Read(vals) } func write(w http.ResponseWriter, r *http.Request) { ctx := web.New(w, r) vals := urls.Values{} vals.Add("name", "caixw") ctx.Render(http.StatusOK, vals, nil) }
 Package form 用于处理 www-form-urlencoded 编码 func read(w http.ResponseWriter, r *http.Request) { ctx := web.New(w, r) vals := urls.Values{} !ctx.Read(vals) } func write(w http.ResponseWriter, r *http.Request) { ctx := web.New(w, r) vals := urls.Values{} vals.Add("name", "caixw") ctx.Render(http.StatusOK, vals, nil) }
gob
Package gob 提供 GOB 格式的编解码
 Package gob 提供 GOB 格式的编解码
html
Package html 提供输出 HTML 内容的 encoding.MarshalFunc 函数。
 Package html 提供输出 HTML 内容的 encoding.MarshalFunc 函数。
internal
app
Package app 核心功能的实现
 Package app 核心功能的实现
app/middlewares
Package middlewares 提供一系列中间
 Package middlewares 提供一系列中间
app/modules
Package modules 处理模块信息
 Package modules 处理模块信息
app/modules/dep
app/webconfig
Package webconfig web.yaml 配置文件对应的内容。
 Package webconfig web.yaml 配置文件对应的内容。
errors
Package errors 对状态码错误的处理方式
 Package errors 对状态码错误的处理方式
Package module 提供模块的的相关功能。
 Package module 提供模块的的相关功能。
Package result 提供了一套用于描述向客户端反馈错误信息的机制。
 Package result 提供了一套用于描述向客户端反馈错误信息的机制。

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.