web

README

web

web 是一个比较完整的 API 开发框架，相对于简单的路由，提供了更多的便利功能。 如果你只是需要一个简单的路由工具，那么你可以移步到 mux。

package main

import "github.com/issue9/web"

// main.go
func main() {
    srv := web.NewServer("web", "1.0.0", &web.Options{})
    router := srv.Routers().NewRouter()
    router.Get("/admins", getAdmins).
        Get("/groups", getGroups)

    srv.Serve()
}

func getAdmins(ctx* web.Context) web.Responser {
    return ctx.NotImplemented();
}

func getGroups(ctx* web.Context) web.Responser {
    return ctx.NotImplemented();
}

字符集和文档类型

文档类型由 Server.Mimetypes 指定。 字符类型无需用户指定，https://www.iana.org/assignments/character-sets/character-sets.xhtml 中列出的字符集都能自动转换。

import "github.com/issue9/web"

srv := web.NewServer("app", "1.0.0", &web.Options{})

srv.Mimetypes().Add("application/json", json.Marshal, json.Unmarshal)
srv.Mimetypes().Add("application/xml", xml.Marshal, xml.Unmarshal)

srv.Serve()

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

错误处理

框架提供了一种输出错误信息内容的机制，用户只需要实现 Problem 接口，即可自定义输出的错误信息格式。 可参考内置的 RFC7807 实现：internal/problems.rfc7807。

中间件

• https://github.com/issue9/middleware 提供了部分中间件。
• https://github.com/issue9/validator 提供了部分验证方法。

工具

https://github.com/issue9/web/releases 提供了一个简易的辅助工具。可以帮助用户完成以下工作：

• 提取和更新本地化信息；
• 生成 openapi 文档。需要在注释中写一定的注解；

版权

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

Documentation

Overview

Package web 通用的 web 开发框架

Index

• Constants
• func NewLocaleError(format string, v ...any) error
• func NewStackError(err error) error
• type CTXFilter
• type Cache
• type Context
• type FieldError
  • func NewFieldError(field string, msg any) *FieldError
• type FilterProblem
• type HandlerFunc
• type LocaleStringer
  • func Phrase(key string, v ...any) LocaleStringer
• type Logger
• type Logs
• type Middleware
• type MiddlewareFunc
• type Options
• type QueryUnmarshaler
• type Responser
  • func Created(v any, location string) Responser
  • func NoContent() Responser
  • func NotModified(etag func() (string, bool), body func() (any, error)) Responser
  • func OK(v any) Responser
  • func Redirect(status int, url string) Responser
  • func Response(status int, body any, kv ...string) Responser
  • func Status(code int, kv ...string) Responser
• type ResponserFunc
• type Router
• type Server
  • func NewServer(name, version string, o *Options) (*Server, error)
• type StringPhrase

Constants

const (
	// 特殊的值，当不想向用户展示 type 值时，该对象的 type 会被设置为该值。
	ProblemAboutBlank = problems.ProblemAboutBlank

	// 400
	ProblemBadRequest                   = problems.ProblemBadRequest
	ProblemUnauthorized                 = problems.ProblemUnauthorized
	ProblemPaymentRequired              = problems.ProblemPaymentRequired
	ProblemForbidden                    = problems.ProblemForbidden
	ProblemNotFound                     = problems.ProblemNotFound
	ProblemMethodNotAllowed             = problems.ProblemMethodNotAllowed
	ProblemNotAcceptable                = problems.ProblemNotAcceptable
	ProblemProxyAuthRequired            = problems.ProblemProxyAuthRequired
	ProblemRequestTimeout               = problems.ProblemRequestTimeout
	ProblemConflict                     = problems.ProblemConflict
	ProblemGone                         = problems.ProblemGone
	ProblemLengthRequired               = problems.ProblemLengthRequired
	ProblemPreconditionFailed           = problems.ProblemPreconditionFailed
	ProblemRequestEntityTooLarge        = problems.ProblemRequestEntityTooLarge
	ProblemRequestURITooLong            = problems.ProblemRequestURITooLong
	ProblemUnsupportedMediaType         = problems.ProblemUnsupportedMediaType
	ProblemRequestedRangeNotSatisfiable = problems.ProblemRequestedRangeNotSatisfiable
	ProblemExpectationFailed            = problems.ProblemExpectationFailed
	ProblemTeapot                       = problems.ProblemTeapot
	ProblemMisdirectedRequest           = problems.ProblemMisdirectedRequest
	ProblemUnprocessableEntity          = problems.ProblemUnprocessableEntity
	ProblemLocked                       = problems.ProblemLocked
	ProblemFailedDependency             = problems.ProblemFailedDependency
	ProblemTooEarly                     = problems.ProblemTooEarly
	ProblemUpgradeRequired              = problems.ProblemUpgradeRequired
	ProblemPreconditionRequired         = problems.ProblemPreconditionRequired
	ProblemTooManyRequests              = problems.ProblemTooManyRequests
	ProblemRequestHeaderFieldsTooLarge  = problems.ProblemRequestHeaderFieldsTooLarge
	ProblemUnavailableForLegalReasons   = problems.ProblemUnavailableForLegalReasons

	// 500
	ProblemInternalServerError           = problems.ProblemInternalServerError
	ProblemNotImplemented                = problems.ProblemNotImplemented
	ProblemBadGateway                    = problems.ProblemBadGateway
	ProblemServiceUnavailable            = problems.ProblemServiceUnavailable
	ProblemGatewayTimeout                = problems.ProblemGatewayTimeout
	ProblemHTTPVersionNotSupported       = problems.ProblemHTTPVersionNotSupported
	ProblemVariantAlsoNegotiates         = problems.ProblemVariantAlsoNegotiates
	ProblemInsufficientStorage           = problems.ProblemInsufficientStorage
	ProblemLoopDetected                  = problems.ProblemLoopDetected
	ProblemNotExtended                   = problems.ProblemNotExtended
	ProblemNetworkAuthenticationRequired = problems.ProblemNetworkAuthenticationRequired
)

预定义的 Problem ID 值

const Version = "0.79.4"

Version 当前框架的版本

Functions

func NewLocaleError

func NewLocaleError(format string, v ...any) error

NewLocaleError 本地化的错误信息

func NewStackError

func NewStackError(err error) error

NewStackError 为 err 带上调用信息

位置从调用 NewStackError 开始。如果 err 为 nil，则返回 nil。 多次调用 NewStackError 包装，则返回第一次包装的返回值。

如果需要输出调用堆栈信息，需要指定 %+v 标记。

Types

type CTXFilter

type CTXFilter = server.CTXFilter

type Cache

type Cache = cache.Cache

type Context

type Context = server.Context

type FieldError

type FieldError = config.FieldError

FieldError 表示配置文件中的字段错误

func NewFieldError

func NewFieldError(field string, msg any) *FieldError

NewFieldError 返回表示配置文件错误的对象

field 表示错误的字段名； msg 表示错误信息，可以是任意类型，如果 msg 是 FieldError 类型， 那么此操作相当于调用了 [FieldError.AddFieldParent]；

type FilterProblem

type FilterProblem = server.FilterProblem

type HandlerFunc

type HandlerFunc = server.HandlerFunc

type LocaleStringer

type LocaleStringer = localeutil.LocaleStringer

LocaleStringer 本地化字符串需要实在的接口

func Phrase

func Phrase(key string, v ...any) LocaleStringer

Phrase 生成本地化的语言片段

type Logger

type Logger = logs.Logger

type Logs

type Logs = logs.Logs

type Middleware

type Middleware = server.Middleware

type MiddlewareFunc

type MiddlewareFunc = server.MiddlewareFunc

type Options

type Options = server.Options

type QueryUnmarshaler

type QueryUnmarshaler = query.Unmarshaler

QueryUnmarshaler 对查询参数的解析接口

type Responser

type Responser = server.Responser

func Created

func Created(v any, location string) Responser

func NoContent

func NoContent() Responser

func NotModified

func NotModified(etag func() (string, bool), body func() (any, error)) Responser

NotModified 决定何时可返回 304 状态码

etag 返回当前内容关联的 ETag 报头内容，其原型为：

func()(etag string, weak bool)

etag 表示对应的 etag 报头，需要包含双绰号，但是不需要 W/ 前缀，weak 是否为弱验证。

body 获取返回给客户端的报文主体对象， 如果返回的是 []byte 类型，会原样输出， 其它类型则按照 [Context.Marshal] 进行转换成 []byte 之后输出。

func OK

func OK(v any) Responser

OK 返回 200 状态码下的对象

func Redirect

func Redirect(status int, url string) Responser

Redirect 重定向至新的 URL

func Response

func Response(status int, body any, kv ...string) Responser

Response 输出状态和对象至客户端

body 表示需要输出的对象，该对象最终会被转换成相应的编码； kv 为报头，必须以偶数数量出现，奇数位为报头名，偶数位为对应的报头值；

func Status

func Status(code int, kv ...string) Responser

Status 仅向客户端输出状态码和报头

kv 为报头，必须以偶数数量出现，奇数位为报头名，偶数位为对应的报头值；

NOTE: 即使 code 为 400 等错误代码，当前函数也不会返回 [Problem] 对象。

type ResponserFunc

type ResponserFunc = server.ResponserFunc

type Router

type Router = server.Router

type Server

type Server = server.Server

func NewServer

func NewServer(name, version string, o *Options) (*Server, error)

type StringPhrase

type StringPhrase = localeutil.StringPhrase