web

package module
v0.24.0 Latest Latest
Warning

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

 Go to latest Published: Jan 12, 2019 License: MIT Imports: 15 Imported by: 69

README

web Build Status Build status Go version Go Report Card license codecov

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

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

// main.go
func main() {
    web.Init("./appconfig", nil)

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

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

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

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

    web.Fatal(2, web.Serve())
}

// 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)
}
项目结构

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

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

通过 web.Init() 函数，可以在初始化时指定配置文件所在的目录，目前 web 包本身需要一个配置文件 web.yaml 以及日志配置文件 logs.xml

web.yaml

以下是该文件的所有配置项：

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

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

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

logs.xml

logs.xml 采用 logs 包的功能，具体的配置可参考其文档。

字符集

字符集用户无须任何操作，会自动根据 Content-Type 中的 charset 属性自动解析其字符集， 输出时，也会根据 Accept-Charset 报头内容，作自动转换之后再输出。以下字符集都被支持： https://www.iana.org/assignments/character-sets/character-sets.xhtml

媒体类型

默认情况下，框架不会处理任何的 mimetype 类型的数据。需要用户通过 Mimetypes().AddMarshals() 和 Mimetypes().AddUnmarshals() 添加相关的处理函数。 添加方式如下：

Mimetypes().AddMarshals(map[string]mimetype.MarshalFunc{
    "application/json": json.Marshal,
})
Mimetypes().AddUnmarshals(map[string]mimetype.UnmarshalFunc{
    "application/json": json.Unmarshal,
})

之后，通过 web.NewContext() 获得的 Context 对象，会根据用户的 Accept 和 Content-Type 自动使用相应的解析和输出格式。

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

错误处理

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

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

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

安装
go get github.com/issue9/web

同时还提供了一个辅助工具 web，可通过调用 ./build/web.sh 进行编译。

文档

Go Walker GoDoc

版权

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

Documentation

Overview

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

配置文件

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

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

字符集

字符集用户无须任何操作，会自动根据 `Content-Type` 中的 charset 属性自动解析其字符集， 输出时，也会根据 `Accept-Charset` 报头内容，作自动转换之后再输出。 以下字符集都被支持： https://www.iana.org/assignments/character-sets/character-sets.xhtml

字符集和媒体类型

默认情况下，框架不会处理任何的 mimetype 类型的数据。需要用户通过 Mimetypes().AddMarshals() 和 Mimetypes().AddUnmarshals() 添加相关的处理函数。 添加方式如下： 

Mimetypes().AddMarshals(map[string]mimetype.MarshalFunc{
    "application/json": json.Marshal,
})
Mimetypes().AddUnmarshals(map[string]mimetype.UnmarshalFunc{
    "application/json": json.Unmarshal,
})

之后，通过 web.NewContext() 获得的 context 对象，会根据用户的 Accept 和 Content-Type 自动使用相应的解析和输出格式。

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

返回结果

context 包下的 Result 表示在出错时的输出内容。在使用前，用户需要调用 web.NewMessages() 添加各类错误代码。

模块

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

Index

Constants

View Source 
const (
	// Version 当前框架的版本
	Version = "0.23.0"

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

Variables

This section is empty.

Functions

func AddMiddlewares added in v0.18.0 

func AddMiddlewares(m ...middleware.Middleware)

AddMiddlewares 设置全局的中间件，可多次调用。

func App added in v0.18.0 

func App() *app.App

App 返回 defaultApp 实例

func CRITICAL added in v0.18.0 

func CRITICAL() *log.Logger

CRITICAL 获取 CRITICAL 级别的 log.Logger 实例，在未指定 critical 级别的日志时，该实例返回一个 nil。

func Close 

func Close() error

Close 关闭服务。

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

func Critical added in v0.18.0 

func Critical(v ...interface{})

Critical 相当于 CRITICAL().Println(v...)的简写方式

func Criticalf added in v0.18.0 

func Criticalf(format string, v ...interface{})

Criticalf 相当于 CRITICAL().Printf(format, v...) 的简写方式

func DEBUG added in v0.18.0 

func DEBUG() *log.Logger

DEBUG 获取 DEBUG 级别的 log.Logger 实例，在未指定 debug 级别的日志时，该实例返回一个 nil。

func Debug added in v0.18.0 

func Debug(v ...interface{})

Debug 相当于 DEBUG().Println(v...) 的简写方式

func Debugf added in v0.18.0 

func Debugf(format string, v ...interface{})

Debugf 相当于 DEBUG().Printf(format, v...) 的简写方式

func ERROR added in v0.18.0 

func ERROR() *log.Logger

ERROR 获取 ERROR 级别的 log.Logger 实例，在未指定 error 级别的日志时，该实例返回一个 nil。

func Error added in v0.18.0 

func Error(v ...interface{})

Error 相当于 ERROR().Println(v...) 的简写方式

func Errorf added in v0.18.0 

func Errorf(format string, v ...interface{})

Errorf 相当于 ERROR().Printf(format, v...) 的简写方式

func Fatal added in v0.18.0 

func Fatal(code int, v ...interface{})

Fatal 输出错误信息，然后退出程序。

func Fatalf added in v0.18.0 

func Fatalf(code int, format string, v ...interface{})

Fatalf 输出错误信息，然后退出程序。

func File 

func File(path string) string

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

func FlushLogs added in v0.18.0 

func FlushLogs()

FlushLogs 立即输出所有的日志信息。

func Grace 

func Grace(sig ...os.Signal)

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

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

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

func INFO added in v0.18.0 

func INFO() *log.Logger

INFO 获取 INFO 级别的 log.Logger 实例，在未指定 info 级别的日志时，该实例返回一个 nil。

func Info added in v0.18.0 

func Info(v ...interface{})

Info 相当于 INFO().Println(v...) 的简写方式 Info 函数默认是带换行符的，若需要不带换行符的，请使用 DEBUG().Print() 函数代替。 其它相似函数也有类型功能。

func Infof added in v0.18.0 

func Infof(format string, v ...interface{})

Infof 相当于 INFO().Printf(format, v...) 的简写方式

func Init 

func Init(dir string) (err error)

Init 初始化整个应用环境

重复调用会直接 panic

func InitModules added in v0.23.0 

func InitModules(tag string) error

InitModules 初始化指定标签的模块

func IsDebug 

func IsDebug() bool

IsDebug 是否处在调试模式

func Load added in v0.18.0 

func Load(r io.Reader, typ string, v interface{}) error

Load 加载指定的配置文件内容到 v 中

func LoadFile added in v0.18.0 

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

LoadFile 加载指定的配置文件内容到 v 中

func Messages added in v0.21.0 

func Messages(p *message.Printer) map[int]string

Messages 获取所有的错误消息代码

如果指定 p 的值，则返回本地化的消息内容。

func Mimetypes added in v0.20.0 

func Mimetypes() *mimetype.Mimetypes

Mimetypes 返回 mimetype.Mimetypes

func Modules 

func Modules() []*module.Module

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

func Mux added in v0.16.1 

func Mux() *mux.Mux

Mux 返回 mux.Mux 实例。

func NewMessages added in v0.21.0 

func NewMessages(status int, messages map[int]string)

NewMessages 添加新的错误消息代码

func Panic added in v0.18.0 

func Panic(v ...interface{})

Panic 输出错误信息，然后触发 panic。

func Panicf added in v0.18.0 

func Panicf(format string, v ...interface{})

Panicf 输出错误信息，然后触发 panic。

func Path added in v0.22.0 

func Path(path string) string

Path 构建 URL 的 Path 部分

func RegisterOnShutdown added in v0.16.1 

func RegisterOnShutdown(f func())

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

func Serve 

func Serve() error

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

func Shutdown 

func Shutdown() error

Shutdown 关闭所有服务。

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

func TRACE added in v0.18.0 

func TRACE() *log.Logger

TRACE 获取 TRACE 级别的 log.Logger 实例，在未指定 trace 级别的日志时，该实例返回一个 nil。

func Tags added in v0.20.0 

func Tags() []string

Tags 获取所有的子模块名称

func Trace added in v0.18.0 

func Trace(v ...interface{})

Trace 相当于 TRACE().Println(v...) 的简写方式

func Tracef added in v0.18.0 

func Tracef(format string, v ...interface{})

Tracef 相当于 TRACE().Printf(format, v...) 的简写方式

func URL 

func URL(path string) string

URL 构建一条完整 URL

func WARN added in v0.18.0 

func WARN() *log.Logger

WARN 获取 WARN 级别的 log.Logger 实例，在未指定 warn 级别的日志时，该实例返回一个 nil。

func Warn added in v0.18.0 

func Warn(v ...interface{})

Warn 相当于 WARN().Println(v...) 的简写方式

func Warnf added in v0.18.0 

func Warnf(format string, v ...interface{})

Warnf 相当于 WARN().Printf(format, v...) 的简写方式

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 注册一个模块

Source Files

View all Source files

Directories

Path Synopsis
Package app 核心功能的实现
 Package app 核心功能的实现
cmd
web
简单的辅助功能命令行工具。
 简单的辅助功能命令行工具。
Package config 提供了对多种格式配置文件的支持
 Package config 提供了对多种格式配置文件的支持
Package context 用于处理单个请求的上下文关系。
 Package context 用于处理单个请求的上下文关系。
internal
cmd/create
Package create 用于创建新项目的子命令
 Package create 用于创建新项目的子命令
cmd/help
Package help 管理 web help xx 的显示信息
 Package help 管理 web help xx 的显示信息
cmd/version
Package version 显示版本号信息
 Package version 显示版本号信息
cmd/watch
Package watch 提供热编译功能。
 Package watch 提供热编译功能。
messages
Package messages 管理错误状态码与其对应的消息内容
 Package messages 管理错误状态码与其对应的消息内容
modules
Package modules 处理模块信息
 Package modules 处理模块信息
modules/dep
Package dep 管理模块的依赖信息，并按照依赖顺序进行初始化。
 Package dep 管理模块的依赖信息，并按照依赖顺序进行初始化。
webconfig
Package webconfig web.yaml 配置文件对应的内容。
 Package webconfig web.yaml 配置文件对应的内容。
Package mimetype 提供了对编码的支持。
 Package mimetype 提供了对编码的支持。
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 函数。
mimetypetest
Package mimetypetest 针对文本内容的编解码实现，仅作为测试用例。
 Package mimetypetest 针对文本内容的编解码实现，仅作为测试用例。
Package module 提供模块的的相关功能。
 Package module 提供模块的的相关功能。

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.