web

package module
v0.34.0 Latest Latest
Warning

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

 Go to latest Published: Dec 1, 2020 License: MIT Imports: 40 Imported by: 69

README

web Test Go version Go Report Card license codecov PkgGoDev

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

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

package main

import "github.com/issue9/web"
import "github.com/issue9/web/config"

// main.go
func main() {
    w, _ := config.Classic("./appconfig/logs.xml", "./appconfig/web.yaml")

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

    w.Serve()
}

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

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

模块

在 web 中项目以模块进行划分。每个模块返回一个 *web.Module 实例， 向项目注册自己的模块信息，在项目进行初始化时，会按照模块的依赖关系进行初始化。

用户可以在模块信息中添加当前模块的路由信息、服务、计划任务等， 这些功能在模块初始化时进行统一的注册初始化。

package m1

import "github.com/issue9/web"

func Init(s *web.Web) {
    m := s.NewModule("test", "测试模块")

    m.AddInit(func() error {
        // TODO 此处可以添加初始化模块的相关代码
        return nil
    }, "初始化函数描述")

    m.AddService(func(ctx context.Context) error {
        // TODO 此处添加服务代码
    }, "服务描述")
}
插件

web 支持以插件的形式分发模块内容，只需要以 -buildmode=plugin 的形式编译每个模块， 之后将编译后的模块文件放至 Config.Plugins 配置项所指定的目录下即可。具体的可参考下 internal/plugintest 下的插件示例。

Go 并不是在所有的平台下都支持插件模式，支持列表可查看：https://golang.org/pkg/plugin/

字符集和文档类型

文档类型由 Config.Marshalers 和 Config.Unmarshalers 两个选项指定，分别对应编码和解码。 字符类型无需用户指定，https://www.iana.org/assignments/character-sets/character-sets.xhtml 中列出的字符集都能自动转换。

conf := &web.Config {
    Marshalers: map[string]content.MarhsalFunc{
        "application/json": json.Marshal,
        "application/xml": xml.Marshal,
    },
    Unmarshalers: map[string]content.UnmarhsalFunc{
        "application/json": json.Unmarshal,
        "application/xml": xml.Unmarshal,
    },
    // 其它设置项
}

srv := web.New(conf)
srv.Serve()

客户端只要在请求时设置 Accept 报头就可返回相应类型的数据，而 Accept-Charset 报头可设置接收的字符集。 Content-Type 则可以有向服务器指定提交内容的文档类型和字符集。

错误处理

框架提供了一种输出错误信息内容的机制，用户只需要实现 Result 接口，即可自定义输出的错误信息格式。 具体实现可参考 context.defaultResult 的实现。

版权

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

Documentation

Overview

Package web 一个微型的 RESTful API 框架

Index

Constants

View Source 
const Version = version.Version

Version 当前框架的版本

Variables

View Source 
var ContextKeyServer contextKey = 0

ContextKeyServer 从 context.Value 中获取 *Server 实例的键名

在某些极端的情况下，用户可能需要用到 Server.Router().Mux().GetFunc() 等比较原始的接口去添加路由，此时无法像 Context.Server() 的方式获取 Server 变量，便可通过 r.Context().Value(ContextKeyServer) 获取。

View Source 
var ErrInited = errors.New("模块已经初始化")

ErrInited 当模块被多次初始化时返回此错误

Functions

func Exit added in v0.34.0 

func Exit(status int)

Exit 以指定的状态码退出当前协程

status 表示输出的状态码，如果为 0，则不会作任何状态码输出。

Exit 最终是以 panic 的形式退出，所以如果你的代码里截获了 panic， 那么 Exit 并不能达到退出当前请求的操作。

与 Error 的不同在于： Error 不会主动退出当前协程，而 Exit 则会触发 panic，退出当前协程。

Types

type Context 

type Context struct {
	Response http.ResponseWriter
	Request  *http.Request

	// 指定输出时所使用的媒体类型，以及名称
	OutputMimetype     content.MarshalFunc
	OutputMimetypeName string

	// 输出到客户端的字符集
	//
	// 若值为 encoding.Nop 或是空，表示为 utf-8
	OutputCharset     encoding.Encoding
	OutputCharsetName string

	// 客户端内容所使用的媒体类型
	InputMimetype content.UnmarshalFunc

	// 客户端内容所使用的字符集
	//
	// 若值为 encoding.Nop 或是空，表示为 utf-8
	InputCharset encoding.Encoding

	// 输出语言的相关设置项
	OutputTag     language.Tag
	LocalePrinter *message.Printer

	// 与当前对话相关的时区
	Location *time.Location

	// 保存 Context 在存续期间的可复用变量
	//
	// 这是比 context.Value 更经济的传递变量方式。
	//
	// 如果仅需要在多个请求中传递参数，可直接使用 Server.Vars。
	Vars map[interface{}]interface{}
	// contains filtered or unexported fields
}

Context 是对当次 HTTP 请求内容的封装

func NewContext 

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

NewContext 构建 *Context 实例

func (*Context) Body added in v0.34.0 

func (ctx *Context) Body() (body []byte, err error)

Body 获取用户提交的内容

相对于 ctx.Request.Body，此函数可多次读取。 不存在 body 时，返回 nil

func (*Context) ClientIP added in v0.34.0 

func (ctx *Context) ClientIP() string

ClientIP 返回客户端的 IP 地址

获取顺序如下：

  • X-Forwarded-For 的第一个元素
  • Remote-Addr 报头
  • X-Read-IP 报头

func (*Context) Created added in v0.34.0 

func (ctx *Context) Created(v interface{}, location string)

Created 201

func (*Context) Critical added in v0.34.0 

func (ctx *Context) Critical(status int, v ...interface{})

Critical 输出日志到 CRITICAL 通道并向用户输出指定状态码的页面

若是输出日志的过程中出错，则 panic 若没有错误信息，则仅向客户端输出一条状态码信息。

输出的内容，会根据 status 的值，在 errorhandler 中查找相应的响应内容， 即使该值小于 400。

func (*Context) Criticalf added in v0.34.0 

func (ctx *Context) Criticalf(status int, format string, v ...interface{})

Criticalf 输出日志到 CRITICAL 通道并向用户输出指定状态码的页面

若是输出日志的过程中出错，则 panic 若没有错误信息，则仅向客户端输出一条状态码信息。

输出的内容，会根据 status 的值，在 errorhandler 中查找相应的响应内容， 即使该值小于 400。

func (*Context) Error added in v0.34.0 

func (ctx *Context) Error(status int, v ...interface{})

Error 输出日志到 ERROR 通道并向用户输出指定状态码的页面

若是输出日志的过程中出错，则 panic 若没有错误信息，则仅向客户端输出一条状态码信息。

输出的内容，会根据 status 的值，在 errorhandler 中查找相应的响应内容， 即使该值小于 400。

func (*Context) Errorf added in v0.34.0 

func (ctx *Context) Errorf(status int, format string, v ...interface{})

Errorf 输出日志到 ERROR 通道并向用户输出指定状态码的页面

若是输出日志的过程中出错，则 panic 若没有错误信息，则仅向客户端输出一条状态码信息。

输出的内容，会根据 status 的值，在 errorhandler 中查找相应的响应内容， 即使该值小于 400。

func (*Context) Exit added in v0.34.0 

func (ctx *Context) Exit(status int)

Exit 以指定的状态码退出当前协程

func (*Context) Fprint added in v0.34.0 

func (ctx *Context) Fprint(w io.Writer, v ...interface{}) (int, error)

Fprint 相当于 ctx.LocalePrinter.Fprint

func (*Context) Fprintf added in v0.34.0 

func (ctx *Context) Fprintf(w io.Writer, key message.Reference, v ...interface{}) (int, error)

Fprintf 相当于 ctx.LocalePrinter.Fprintf

func (*Context) Fprintln added in v0.34.0 

func (ctx *Context) Fprintln(w io.Writer, v ...interface{}) (int, error)

Fprintln 相当于 ctx.LocalePrinter.Fprintln

func (*Context) Marshal added in v0.34.0 

func (ctx *Context) Marshal(status int, v interface{}, headers map[string]string) error

Marshal 将 v 解码并发送给客户端

若 v 是一个 nil 值，则不会向客户端输出任何内容； 若是需要正常输出一个 nil 类型到客户端（JSON 中会输出 null）， 可以使用 content.Nil 变量代替。

NOTE: 如果需要指定一个特定的 Content-Type 和 Content-Language， 可以在 headers 中指定，否则使用当前的编码和语言名称。

通过 Marshal 输出的内容，即使 status 的值大于 399， 依然能正常输出 v 的内容，而不是转向 errorhandler 中的相关内容。

func (*Context) NewResult added in v0.34.0 

func (ctx *Context) NewResult(code int) *Result

NewResult 返回 Result 实例

如果找不到 code 对应的错误信息，则会直接 panic。

func (*Context) NewResultWithFields added in v0.34.0 

func (ctx *Context) NewResultWithFields(code int, fields result.Fields) *Result

NewResultWithFields 返回 Result 实例

如果找不到 code 对应的错误信息，则会直接 panic。

func (*Context) NoContent added in v0.34.0 

func (ctx *Context) NoContent()

NoContent 204

func (*Context) NotFound added in v0.34.0 

func (ctx *Context) NotFound()

NotFound 404

接受统一的 errorhandler 模板支配

func (*Context) NotImplemented added in v0.34.0 

func (ctx *Context) NotImplemented()

NotImplemented 501

接受统一的 errorhandler 模板支配

func (*Context) Now added in v0.34.0 

func (ctx *Context) Now() time.Time

Now 返回当前时间

与 time.Now() 的区别在于 Now() 基于当前时区

func (*Context) ParamID added in v0.34.0 

func (ctx *Context) ParamID(key string) (int64, error)

ParamID 获取地址参数中表示 key 的值并并转换成大于 0 的 int64

相对于 Context.ParamInt64()，该值必须大于 0。

NOTE: 若需要获取多个参数，可以使用 Context.Params 获取会更方便。

func (*Context) ParamInt64 added in v0.34.0 

func (ctx *Context) ParamInt64(key string) (int64, error)

ParamInt64 取地址参数中的 key 表示的值 int64 类型值

NOTE: 若需要获取多个参数，可以使用 Context.Params 获取会更方便。

func (*Context) ParamString added in v0.34.0 

func (ctx *Context) ParamString(key string) (string, error)

ParamString 取地址参数中的 key 表示的 string 类型值

NOTE: 若需要获取多个参数，可以使用 Context.Params 获取会更方便。

func (*Context) Params added in v0.34.0 

func (ctx *Context) Params() *Params

Params 声明一个新的 Params 实例

func (*Context) ParseTime added in v0.34.0 

func (ctx *Context) ParseTime(layout, value string) (time.Time, error)

ParseTime 分析基于当前时区的时间

func (*Context) Print added in v0.34.0 

func (ctx *Context) Print(v ...interface{}) (int, error)

Print 相当于 ctx.LocalePrinter.Print

func (*Context) Printf added in v0.34.0 

func (ctx *Context) Printf(key message.Reference, v ...interface{}) (int, error)

Printf 相当于 ctx.LocalePrinter.Printf

func (*Context) Println added in v0.34.0 

func (ctx *Context) Println(v ...interface{}) (int, error)

Println 相当于 ctx.LocalePrinter.Println

func (*Context) Queries added in v0.34.0 

func (ctx *Context) Queries() (*Queries, error)

Queries 声明一个新的 Queries 实例

func (*Context) QueryObject added in v0.34.0 

func (ctx *Context) QueryObject(v interface{}, code int) (ok bool)

QueryObject 将查询参数解析到一个对象中

功能有点类似于 Context.Read，只不过当前是从查询参数中读取数据到对象。

如果 URL 有问题，导致无法正确解析查询参数的数据，则会直接返回 422 的错误码给用户。

func (*Context) Read added in v0.34.0 

func (ctx *Context) Read(v interface{}, code int) (ok bool)

Read 从客户端读取数据并转换成 v 对象

功能与 Unmarshal() 相同，只不过 Read() 在出错时， 会直接调用 Error() 处理：输出 422 的状态码， 并返回一个 false，告知用户转换失败。 如果是数据类型验证失败，则会输出以 code 作为错误代码的错误信息， 并返回 false，作为执行失败的通知。

func (*Context) Render added in v0.34.0 

func (ctx *Context) Render(status int, v interface{}, headers map[string]string)

Render 将 v 渲染给客户端

功能与 Marshal() 相同，只不过 Render() 在出错时， 会直接调用 Error() 处理，输出 500 的状态码。

如果需要具体控制出错后的处理方式，可以使用 Marshal 函数。

通过 Render 输出的内容，即使 status 的值大于 399， 依然能正常输出 v 的内容，而不是转向 errorhandler 中的相关内容， 但是渲染出错时，依然转换 errorhandler。

func (*Context) ResetContent added in v0.34.0 

func (ctx *Context) ResetContent()

ResetContent 205

func (*Context) ServeContent added in v0.34.0 

func (ctx *Context) ServeContent(buf io.ReadSeeker, name string, headers map[string]string)

ServeContent 将一块内存中的内容转换为文件提供下载

文件可能提供连续的下载功能，其状态码是未定的， 所以提供了一个类似于 Render 的变体专门用于下载功能。

buf 实现 io.ReadSeeker 接口的内存块； name 下载时，显示的文件； headers 文件报头内容。

func (*Context) ServeFile added in v0.34.0 

func (ctx *Context) ServeFile(path string, headers map[string]string)

ServeFile 提供文件下载

文件可能提供连续的下载功能，其状态码是未定的， 所以提供了一个类似于 Render 的变体专门用于下载功能。

path 指向本地文件的地址； headers 额外显示的报头内容。

func (*Context) Server added in v0.34.0 

func (ctx *Context) Server() *Server

Server 获取关联的 context.Server 实例

func (*Context) Sprint added in v0.34.0 

func (ctx *Context) Sprint(v ...interface{}) string

Sprint 相当于 ctx.LocalePrinter.Sprint

func (*Context) Sprintf added in v0.34.0 

func (ctx *Context) Sprintf(key message.Reference, v ...interface{}) string

Sprintf 相当于 ctx.LocalePrinter.Sprintf

func (*Context) Sprintln added in v0.34.0 

func (ctx *Context) Sprintln(v ...interface{}) string

Sprintln 相当于 ctx.LocalePrinter.Sprintln

func (*Context) Unmarshal added in v0.34.0 

func (ctx *Context) Unmarshal(v interface{}) error

Unmarshal 将提交的内容转换成 v 对象

func (*Context) Upload added in v0.34.0 

func (ctx *Context) Upload(field string, u *upload.Upload) ([]string, error)

Upload 执行上传文件的相关操作

返回的是文件列表

type Filter added in v0.33.0 

type Filter func(HandlerFunc) HandlerFunc

Filter 针对 Context 的中间件

Filter 和 github.com/issue9/middleware.Middleware 本质上没有任何区别， 都是作用于 http.Handler 上的中间件，只因参数不同，且两者不能交替出现， 派生出两套类型。

保证针对 middleware.Middleware 的 AddMiddlewares 方法， 可以最大限度地利用现有的通用中间件，而 AddFilter 方便用户编写针对 Context 的中间件，且 Context 提供了 http.Handler 不存在的功能。

type HandlerFunc added in v0.33.0 

type HandlerFunc func(*Context)

HandlerFunc 路由项处理函数原型

func FilterHandler added in v0.34.0 

func FilterHandler(next HandlerFunc, filter ...Filter) HandlerFunc

FilterHandler 将过滤器应用于处理函数 next

type InstallFunc added in v0.33.0 

type InstallFunc func(*Server) error

InstallFunc 安装模块的函数签名

type Module 

type Module interface {
	ID() string
	Description() string
	Deps() []string

	Tags() []string // 与当前模块关联的子标签

	// 添加新的服务
	//
	// f 表示服务的运行函数；
	// title 是对该服务的简要说明。
	AddService(title string, f service.Func)

	// AddCron 添加新的定时任务
	//
	// f 表示服务的运行函数；
	// title 是对该服务的简要说明；
	// spec cron 表达式，支持秒；
	// delay 是否在任务执行完之后，才计算下一次的执行时间点。
	AddCron(title string, f scheduled.JobFunc, spec string, delay bool)

	// AddTicker 添加新的定时任务
	//
	// f 表示服务的运行函数；
	// title 是对该服务的简要说明；
	// imm 是否立即执行一次该任务；
	// delay 是否在任务执行完之后，才计算下一次的执行时间点。
	AddTicker(title string, f scheduled.JobFunc, dur time.Duration, imm, delay bool)

	// AddAt 添加新的定时任务
	//
	// f 表示服务的运行函数；
	// title 是对该服务的简要说明；
	// t 指定的时间点；
	// delay 是否在任务执行完之后，才计算下一次的执行时间点。
	AddAt(title string, f scheduled.JobFunc, t time.Time, delay bool)

	// AddJob 添加新的计划任务
	//
	// f 表示服务的运行函数；
	// title 是对该服务的简要说明；
	// scheduler 计划任务的时间调度算法实现；
	// delay 是否在任务执行完之后，才计算下一次的执行时间点。
	AddJob(title string, f scheduled.JobFunc, scheduler schedulers.Scheduler, delay bool)

	// AddInit 添加一个初始化函数
	//
	// title 该初始化函数的名称。
	AddInit(title string, f func() error)

	// NewTag 为当前模块生成特定名称的子模块
	//
	// 若已经存在，则直接返回该子模块。
	//
	// Tag 是依赖关系与当前模块相同，但是功能完全独立的模块，
	// 一般用于功能更新等操作。
	NewTag(tag string) (Tag, error)

	// AddFilters 添加过滤器
	//
	// 按给定参数的顺序反向依次调用。
	AddFilters(filter ...Filter) Module
	Resource(pattern string, filter ...Filter) *Resource
	Prefix(prefix string, filter ...Filter) *Prefix
	Handle(path string, h HandlerFunc, method ...string) Module
	Get(path string, h HandlerFunc) Module
	Post(path string, h HandlerFunc) Module
	Delete(path string, h HandlerFunc) Module
	Put(path string, h HandlerFunc) Module
	Patch(path string, h HandlerFunc) Module
	Options(path, allow string) Module
	Remove(path string, method ...string) Module
}

Module 表示模块信息

模块仅作为在初始化时在代码上的一种分类，一旦初始化完成， 则不再有模块的概念，修改模块的相关属性，也不会对代码有实质性的改变。

type Options added in v0.34.0 

type Options struct {
	// 服务器的时区
	//
	// 默认值为 time.Local
	Location *time.Location

	// 当前使用的本地化组件
	//
	// 默认情况下会引用 golang.org/x/text/message.DefaultCatalog 对象。
	//
	// golang.org/x/text/message/catalog 提供了 NewBuilder 和 NewFromMap
	// 等方式构建 Catalog 接口实例。
	Catalog catalog.Catalog

	// 指定生成 Result 数据的方法
	//
	// 默认情况下指向  result.DefaultBuilder。
	ResultBuilder result.BuildFunc

	// 缓存系统
	//
	// 默认值为内存类型。
	Cache cache.Cache

	// 初始化 MUX 的参数
	DisableHead    bool
	DisableOptions bool
	SkipCleanPath  bool

	// 可以对 http.Server 的内容进行个性
	//
	// NOTE: 对 http.Server.Handler 的修改不会启作用，该值始终会指向 Server.middlewares
	HTTPServer func(*http.Server)

	// 网站的根目录
	//
	// 可以带上域名：https://example.com/api；或是仅路径部分 /api；
	// 两者的区别在于 Router.URL 返回的内容，前者带域名部分，后者不带。
	Root string
	// contains filtered or unexported fields
}

Options 初始化 Server 的参数

type Params added in v0.34.0 

type Params struct {
	// contains filtered or unexported fields
}

Params 用于处理路径中包含的参数 

p := ctx.Params()
aid := p.Int64("aid")
bid := p.Int64("bid")
if p.HasErrors() {
    // do something
    return
}

func (*Params) Bool added in v0.34.0 

func (p *Params) Bool(key string) bool

Bool 获取参数 key 所代表的值并转换成 bool

最终会调用 strconv.ParseBool 进行转换， 也只有该方法中允许的字符串会被正确转换。

func (*Params) Errors added in v0.34.0 

func (p *Params) Errors() result.Fields

Errors 返回所有的错误信息

func (*Params) Float64 added in v0.34.0 

func (p *Params) Float64(key string) float64

Float64 获取参数 key 所代表的值并转换成 float64

func (*Params) HasErrors added in v0.34.0 

func (p *Params) HasErrors() bool

HasErrors 是否有错误内容存在

func (*Params) ID added in v0.34.0 

func (p *Params) ID(key string) int64

ID 获取参数 key 所代表的值并转换成 int64

值必须大于 0，否则会输出错误信息，并返回零值。

func (*Params) Int64 added in v0.34.0 

func (p *Params) Int64(key string) int64

Int64 获取参数 key 所代表的值，并转换成 int64

func (*Params) MustBool added in v0.34.0 

func (p *Params) MustBool(key string, def bool) bool

MustBool 获取参数 key 所代表的值并转换成 bool

若不存在或是转换出错，则返回 def 作为其默认值。 仅在类型转换出错时，才会向 errors 写入错误信息。

最终会调用 strconv.ParseBool 进行转换， 也只有该方法中允许的字符串会被正确转换。

func (*Params) MustFloat64 added in v0.34.0 

func (p *Params) MustFloat64(key string, def float64) float64

MustFloat64 获取参数 key 所代表的值并转换成 float64

若不存在或是转换出错，则返回 def 作为其默认值。 仅在类型转换出错时，才会向 errors 写入错误信息。

func (*Params) MustID added in v0.34.0 

func (p *Params) MustID(key string, def int64) int64

MustID 获取参数 key 所代表的值并转换成 int64

值必须大于 0，否则会输出错误信息，并返回零值。

若不存在或是转换出错，则返回 def 作为其默认值。 仅在类型转换出错或是小于零时，才会向 errors 写入错误信息。

func (*Params) MustInt64 added in v0.34.0 

func (p *Params) MustInt64(key string, def int64) int64

MustInt64 获取参数 key 所代表的值并转换成 int64

若不存在或是转换出错，则返回 def 作为其默认值。 仅在类型转换出错时，才会向 errors 写入错误信息。

func (*Params) MustString added in v0.34.0 

func (p *Params) MustString(key, def string) string

MustString 获取参数 key 所代表的值并转换成 string

若不存在或是转换出错，则返回 def 作为其默认值。

func (*Params) Result added in v0.34.0 

func (p *Params) Result(code int) *Result

Result 转换成 Result 对象

code 是作为 Result.Code 从错误消息中查找，如果不存在，则 panic。 Params.errors 将会作为 Result.Fields 的内容。

func (*Params) String added in v0.34.0 

func (p *Params) String(key string) string

String 获取参数 key 所代表的值并转换成 string

type Prefix added in v0.33.0 

type Prefix struct {
	// contains filtered or unexported fields
}

Prefix 带有统一前缀的路由管理

func (*Prefix) Delete added in v0.33.0 

func (p *Prefix) Delete(path string, h HandlerFunc) *Prefix

Delete 添加 DELETE 请求处理项

func (*Prefix) Get added in v0.33.0 

func (p *Prefix) Get(path string, h HandlerFunc) *Prefix

Get 添加 GET 请求处理项

func (*Prefix) Handle added in v0.33.0 

func (p *Prefix) Handle(path string, h HandlerFunc, method ...string) error

Handle 添加路由项

func (*Prefix) Options added in v0.33.0 

func (p *Prefix) Options(path, allow string) *Prefix

Options 指定 OPTIONS 请求的返回内容

func (*Prefix) Patch added in v0.33.0 

func (p *Prefix) Patch(path string, h HandlerFunc) *Prefix

Patch 添加 Patch 请求处理

func (*Prefix) Post added in v0.33.0 

func (p *Prefix) Post(path string, h HandlerFunc) *Prefix

Post 添加 POST 请求处理项

func (*Prefix) Put added in v0.33.0 

func (p *Prefix) Put(path string, h HandlerFunc) *Prefix

Put 添加 PUT 请求处理项

func (*Prefix) Remove added in v0.34.0 

func (p *Prefix) Remove(path string, method ...string)

Remove 删除路由项

func (*Prefix) Resource added in v0.33.0 

func (p *Prefix) Resource(pattern string, filter ...Filter) *Resource

Resource 生成 Resource 对象

type Queries added in v0.34.0 

type Queries struct {
	// contains filtered or unexported fields
}

Queries 用于处理路径中的查询参数 

q,_ := ctx.Queries()
page := q.Int64("page", 1)
size := q.Int64("size", 20)
if q.HasErrors() {
    // do something
    return
}

func (*Queries) Bool added in v0.34.0 

func (q *Queries) Bool(key string, def bool) bool

Bool 从查询参数中获取指定名称的值

若不存在则返回 def 作为其默认值。

func (*Queries) Errors added in v0.34.0 

func (q *Queries) Errors() result.Fields

Errors 所有的错误信息

func (*Queries) Float64 added in v0.34.0 

func (q *Queries) Float64(key string, def float64) float64

Float64 从查询参数中获取指定名称的值

若不存在则返回 def 作为其默认值。

func (*Queries) HasErrors added in v0.34.0 

func (q *Queries) HasErrors() bool

HasErrors 是否存在错误内容

func (*Queries) Int added in v0.34.0 

func (q *Queries) Int(key string, def int) int

Int 从查询参数中获取指定名称的值

若不存在则返回 def 作为其默认值。 若是无法转换，则会保存错误信息

func (*Queries) Int64 added in v0.34.0 

func (q *Queries) Int64(key string, def int64) int64

Int64 从查询参数中获取指定名称的值

若不存在则返回 def 作为其默认值。

func (*Queries) Object added in v0.34.0 

func (q *Queries) Object(v interface{})

Object 将查询参数解析到一个对象中

具体的文档信息可以参考 https://github.com/issue9/query

func (*Queries) Result added in v0.34.0 

func (q *Queries) Result(code int) *Result

Result 转换成 Result 对象

code 是作为 Result.Code 从错误消息中查找，如果不存在，则 panic。 Queries.errors 将会作为 Result.Fields 的内容。

func (*Queries) String added in v0.34.0 

func (q *Queries) String(key, def string) string

String 从查询参数中获取指定名称的值

若不存在则返回 def 作为其默认值。

type Resource added in v0.33.0 

type Resource struct {
	// contains filtered or unexported fields
}

Resource 同一资源的不同请求方法的管理

func (*Resource) Delete added in v0.33.0 

func (r *Resource) Delete(h HandlerFunc) *Resource

Delete 添加 DELETE 请求处理项

func (*Resource) Get added in v0.33.0 

func (r *Resource) Get(h HandlerFunc) *Resource

Get 添加 GET 请求处理项

func (*Resource) Handle added in v0.33.0 

func (r *Resource) Handle(h HandlerFunc, method ...string) error

Handle 添加路由项

func (*Resource) Options added in v0.33.0 

func (r *Resource) Options(allow string) *Resource

Options 指定 OPTIONS 请求的返回内容

func (*Resource) Patch added in v0.33.0 

func (r *Resource) Patch(h HandlerFunc) *Resource

Patch 添加 PATCH 请求处理项

func (*Resource) Post added in v0.33.0 

func (r *Resource) Post(h HandlerFunc) *Resource

Post 添加 POST 请求处理项

func (*Resource) Put added in v0.33.0 

func (r *Resource) Put(h HandlerFunc) *Resource

Put 添加 PUT 请求处理项

func (*Resource) Remove added in v0.34.0 

func (r *Resource) Remove(method ...string)

Remove 删除路由项

type Result 

type Result struct {
	result.Result
	// contains filtered or unexported fields
}

Result result.Result 与 Context 相结合的实现

func (*Result) Render added in v0.34.0 

func (rslt *Result) Render()

Render 渲染内容

func (*Result) RenderAndExit added in v0.34.0 

func (rslt *Result) RenderAndExit()

RenderAndExit 渲染内容并退出当前的请求处理

type Router added in v0.34.0 

type Router struct {
	// contains filtered or unexported fields
}

Router 路由管理

func (*Router) Delete added in v0.34.0 

func (router *Router) Delete(path string, h HandlerFunc) *Router

Delete 添加 DELETE 请求处理项

func (*Router) Get added in v0.34.0 

func (router *Router) Get(path string, h HandlerFunc) *Router

Get 添加 GET 请求处理项

func (*Router) Handle added in v0.34.0 

func (router *Router) Handle(path string, h HandlerFunc, method ...string) error

Handle 添加路由请求项

func (*Router) Mux added in v0.34.0 

func (router *Router) Mux() *mux.Mux

Mux 返回 mux.Mux 实例

func (*Router) NewRouter added in v0.34.0 

func (router *Router) NewRouter(name string, url *url.URL, matcher mux.Matcher, filter ...Filter) (*Router, bool)

NewRouter 构建基于 matcher 匹配的路由操作实例

不会应用通过 Server.AddFilters 添加的中间件，但是会应用 Server.AddMiddlewares 添加的中间件。

func (*Router) Options added in v0.34.0 

func (router *Router) Options(path, allow string) *Router

Options 添加 OPTIONS 请求处理项

忽略 Filter 类型的是间件，如果有需要，可以采用 Handle 处理 Options 请求。

func (*Router) Patch added in v0.34.0 

func (router *Router) Patch(path string, h HandlerFunc) *Router

Patch 添加 PATCH 请求处理项

func (*Router) Path added in v0.34.0 

func (router *Router) Path(pattern string, params map[string]string) (string, error)

Path 返回相对于域名的绝对路由地址

功能与 mux.URL 相似，但是加上了关联的域名地址的根路径。比如根地址是 https://example.com/blog pattern 为 /posts/{id}，则返回为 /blog/posts/1。 如果 params 为空的话，则会直接将 pattern 作为从 mux 转换之后的内容与 router.root 合并返回。

func (*Router) Post added in v0.34.0 

func (router *Router) Post(path string, h HandlerFunc) *Router

Post 添加 POST 请求处理项

func (*Router) Prefix added in v0.34.0 

func (router *Router) Prefix(prefix string, filter ...Filter) *Prefix

Prefix 返回特定前缀的路由设置对象

func (*Router) Put added in v0.34.0 

func (router *Router) Put(path string, h HandlerFunc) *Router

Put 添加 PUT 请求处理项

func (*Router) Remove added in v0.34.0 

func (router *Router) Remove(path string, method ...string)

Remove 删除指定的路由项

func (*Router) Resource added in v0.34.0 

func (router *Router) Resource(pattern string, filter ...Filter) *Resource

Resource 生成资源项

func (*Router) Static added in v0.34.0 

func (router *Router) Static(p, dir string) error

Static 添加静态路由

path 为路由地址，必须以命名参数结尾，比如 /assets/{path}，之后可以通过此值删除路由项； dir 为指向静态文件的路径；

如果要删除该静态路由，则可以将 path 传递给 Remove 进行删除。

比如在 Root 的值为 example.com/blog 时， 将参数指定为 /admin/{path} 和 ~/data/assets/admin 表示将 example.com/blog/admin/* 解析到 ~/data/assets/admin 目录之下。

func (*Router) URL added in v0.34.0 

func (router *Router) URL(pattern string, params map[string]string) (string, error)

URL 构建完整的 URL

功能与 mux.URL 相似，但是加上了关联的域名地址。比如根地址是 https://example.com/blog pattern 为 /posts/{id}，则返回为 https://example.com/blog/posts/1。 如果 params 为空的话，则会直接将 pattern 作为从 mux 转换之后的内容与 router.root 合并返回。

type Server added in v0.25.0 

type Server struct {
	// contains filtered or unexported fields
}

Server 提供了用于构建 Context 对象的基本数据

func GetServer added in v0.34.0 

func GetServer(r *http.Request) *Server

GetServer 从请求中获取 *Server 实例

r 必须得是由 Server 生成的，否则会 panic。

func NewServer added in v0.34.0 

func NewServer(logs *logs.Logs, o *Options) (*Server, error)

NewServer 返回 *Server 实例

func (*Server) AddCompressTypes added in v0.34.0 

func (srv *Server) AddCompressTypes(types ...string)

AddCompressTypes 指定哪些内容可以进行压缩传输

默认情况下是所有内容都将进行压缩传输， * 表示所有； text/* 表示以 text/ 开头的类型； text/plain 表示具体类型 text/plain；

func (*Server) AddFilters added in v0.34.0 

func (srv *Server) AddFilters(filter ...Filter)

AddFilters 添加过滤器

func (*Server) AddMiddlewares added in v0.34.0 

func (srv *Server) AddMiddlewares(middleware ...middleware.Middleware)

AddMiddlewares 添加中间件

func (*Server) AddResultMessage added in v0.34.0 

func (srv *Server) AddResultMessage(status, code int, key message.Reference, v ...interface{})

AddResultMessage 添加一条错误信息

status 指定了该错误代码反馈给客户端的 HTTP 状态码； code 错误代码； key 和 v 表示错误信息的翻译项内容，最终会传递给 message.Printer.Sprintf 进行翻译；

func (*Server) Cache added in v0.34.0 

func (srv *Server) Cache() cache.Cache

Cache 返回缓存的相关接口

func (*Server) Close added in v0.34.0 

func (srv *Server) Close(shutdownTimeout time.Duration) error

Close 关闭服务

func (*Server) DeleteCompressTypes added in v0.34.0 

func (srv *Server) DeleteCompressTypes(types ...string)

DeleteCompressTypes 删除指定内容的压缩支持

仅用于删除通过 AddType 添加的内容。

NOTE: 如果指定 * 之后的所有内容都将不支持。

func (*Server) Get added in v0.34.0 

func (srv *Server) Get(key interface{}) interface{}

Get 返回指定键名的值

func (*Server) InitTag added in v0.34.0 

func (srv *Server) InitTag(tag string) error

InitTag 初始化模块下的子标签

func (*Server) LoadPlugin added in v0.34.0 

func (srv *Server) LoadPlugin(path string) error

LoadPlugin 将指定的插件当作模块进行加载

func (*Server) LoadPlugins added in v0.34.0 

func (srv *Server) LoadPlugins(glob string) error

LoadPlugins 加载所有的插件

如果 glob 为空，则不会加载任何内容，返回空值

func (*Server) Location added in v0.34.0 

func (srv *Server) Location() *time.Location

Location 指定服务器的时区信息

func (*Server) Logs added in v0.34.0 

func (srv *Server) Logs() *logs.Logs

Logs 返回关联的 logs.Logs 实例

func (*Server) Mimetypes added in v0.34.0 

func (srv *Server) Mimetypes() *content.Mimetypes

Mimetypes 返回内容编解码的管理接口

func (*Server) Modules added in v0.34.0 

func (srv *Server) Modules() []dep.Module

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

func (*Server) NewContext added in v0.34.0 

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

NewContext 构建 *Context 实例

如果 Accept 的内容与当前配置无法匹配， 则退出(panic)并输出 NotAcceptable 状态码。

func (*Server) NewLocalePrinter added in v0.34.0 

func (srv *Server) NewLocalePrinter(tag language.Tag) *message.Printer

NewLocalePrinter 返回指定语言的 message.Printer

func (*Server) NewModule added in v0.34.0 

func (srv *Server) NewModule(id, desc string, deps ...string) (Module, error)

NewModule 声明一个新的模块

name 模块名称，需要全局唯一； desc 模块的详细信息； deps 表示当前模块的依赖模块名称，可以是插件中的模块名称。

可以在运行过程中添加模块，该模块会在加载时直接初始化，前提是模块的依赖模块都已经初始化。

func (*Server) Now added in v0.34.0 

func (srv *Server) Now() time.Time

Now 返回当前时间

与 time.Now() 的区别在于 Now() 基于当前时区

func (*Server) ParseTime added in v0.34.0 

func (srv *Server) ParseTime(layout, value string) (time.Time, error)

ParseTime 分析基于当前时区的时间

func (*Server) ResultMessages added in v0.34.0 

func (srv *Server) ResultMessages(p *message.Printer) map[int]string

ResultMessages 错误信息列表

p 用于返回特定语言的内容。

func (*Server) Router added in v0.34.0 

func (srv *Server) Router() *Router

Router 返回操作路由项的实例

路由地址基于 root 的值， 且所有的路由都会自动应用通过 Server.AddFilters 和 Server.AddMiddlewares 添加的中间件。

func (*Server) Serve added in v0.34.0 

func (srv *Server) Serve() (err error)

Serve 启动服务

func (*Server) Services added in v0.34.0 

func (srv *Server) Services() *service.Manager

Services 返回服务内容的管理接口

func (*Server) Set added in v0.34.0 

func (srv *Server) Set(key, val interface{})

Set 保存指定键名的值

func (*Server) SetCompressAlgorithm added in v0.34.0 

func (srv *Server) SetCompressAlgorithm(name string, w compress.WriterFunc)

SetCompressAlgorithm 设置压缩的算法

默认情况下，支持 gzip、deflate 和 br 三种。 如果 w 为 nil，表示删除对该算法的支持。

func (*Server) SetDebugger added in v0.34.0 

func (srv *Server) SetDebugger(pprof, vars string) (err error)

SetDebugger 设置调试地址

func (*Server) SetErrorHandle added in v0.34.0 

func (srv *Server) SetErrorHandle(h errorhandler.HandleFunc, status ...int)

SetErrorHandle 设置指定状态码页面的处理函数

如果状态码已经存在处理函数，则修改，否则就添加。 仅对状态码 >= 400 的有效果。 如果 status 为零表示所有未设置的状态码都采用该函数处理。

func (*Server) Tags added in v0.34.0 

func (srv *Server) Tags() map[string][]string

Tags 返回所有的子模块名称

键名为模块名称，键值为该模块下的标签列表。

func (*Server) Uptime added in v0.34.0 

func (srv *Server) Uptime() time.Time

Uptime 当前服务的运行时间

type Tag added in v0.28.0 

type Tag interface {
	AddInit(string, func() error)
}

Tag 表示与特定标签相关联的初始化函数列表

依附于模块，共享模块的依赖关系。 一般是各个模块下的安装脚本使用。

type Validator added in v0.34.0 

type Validator interface {
	CTXValidate(*Context) result.Fields
}

Validator 数据验证接口

但凡对象实现了该接口，那么在 Context.Read 和 Queries.Object 中会在解析数据成功之后，调用该接口进行数据验证。

Source Files

View all Source files

Directories

Path Synopsis
cmd
web
简单的辅助功能命令行工具
 简单的辅助功能命令行工具
Package config 提供了加载配置项内容的各类方法
 Package config 提供了加载配置项内容的各类方法
Package content 提供对各类媒体数据的处理
 Package content 提供对各类媒体数据的处理
form
Package form 用于处理 www-form-urlencoded 编码 func read(ctx *web.Context) { vals := urls.Values{} ctx.Read(vals) } func write(ctx *web.Context) { vals := urls.Values{} vals.Add("name", "caixw") ctx.Render(http.StatusOK, vals, nil) } form 用户可以通过定义 form 标签自定义输出的名称，比如： type Username struct { Name string `form:"name"` Age int } 转换成 form-data 可能是以下样式： name=jjj&age=18 该方式对数据类型有一定限制： 1.
 Package form 用于处理 www-form-urlencoded 编码 func read(ctx *web.Context) { vals := urls.Values{} ctx.Read(vals) } func write(ctx *web.Context) { vals := urls.Values{} vals.Add("name", "caixw") ctx.Render(http.StatusOK, vals, nil) } form 用户可以通过定义 form 标签自定义输出的名称，比如： type Username struct { Name string `form:"name"` Age int } 转换成 form-data 可能是以下样式： name=jjj&age=18 该方式对数据类型有一定限制： 1.
gob
Package gob 提供 GOB 格式的编解码
 Package gob 提供 GOB 格式的编解码
html
Package html 提供输出 HTML 内容的 content.MarshalFunc 函数 tpl := template.ParseFiles(...) mgr := html.New(tpl) content.AddMarshal("text/html", mgr.Marshal) func handle(ctx *web.Context) { ctx.Render(200, html.Tpl("index", map[string]interface{}{...}), nil) }
 Package html 提供输出 HTML 内容的 content.MarshalFunc 函数 tpl := template.ParseFiles(...) mgr := html.New(tpl) content.AddMarshal("text/html", mgr.Marshal) func handle(ctx *web.Context) { ctx.Render(200, html.Tpl("index", map[string]interface{}{...}), nil) }
mimetypetest
Package mimetypetest 针对文本内容的编解码实现，仅作为测试用例。
 Package mimetypetest 针对文本内容的编解码实现，仅作为测试用例。
internal
cmd
Package cmd 命令行相关操作
 Package cmd 命令行相关操作
cmd/build
Package build 提供编译相关的功能
 Package build 提供编译相关的功能
cmd/release
Package release 发布版本号管理
 Package release 发布版本号管理
cmd/version
Package version 显示版本号信息
 Package version 显示版本号信息
cmd/watch
Package watch 提供热编译功能 功能与 github.com/caixw/gobuild 相同。
 Package watch 提供热编译功能 功能与 github.com/caixw/gobuild 相同。
dep
Package dep 依赖管理
 Package dep 依赖管理
filesystem
Package filesystem 提供与文件系统相关的操作
 Package filesystem 提供与文件系统相关的操作
plugintest
Package plugintest 作为插件的功能测试包 NOTE: 该测试如果直接写在功能所在的包，目前版本会报错。
 Package plugintest 作为插件的功能测试包 NOTE: 该测试如果直接写在功能所在的包，目前版本会报错。
version
Package version 版本定义
 Package version 版本定义
versioninfo
Package versioninfo 提供对版本信息的一些操作
 Package versioninfo 提供对版本信息的一些操作
Package result 提供对自定义错误代码的支持
 Package result 提供对自定义错误代码的支持
Package service 服务管理
 Package service 服务管理

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.