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{})

    m1.Module(srv.NewModule("m1", web.Phrase("desc")))
    m2.Module(srv.NewModule("m2", web.Phrase("desc"))

    srv.Serve()
}

// modules/m1/module.go
func Module(m *web.Module) error {
    m.Action("serve").AddRoutes(func(r*web.Router){
        r.Get("/admins", getAdmins).
            Get("/groups", getGroups)
    })
}

// modules/m2/module.go
func Module(m *web.Module) error {
    m.Action("serve").AddRoutes(func(r*web.Router){
        r.Get("/admins", getAdmins).
            Get("/groups", getGroups)
    })
}

字符集和文档类型

文档类型由 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 实现：server.rfc7807。

中间件

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

版权

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

Documentation

Overview

Package web 模块化的 web 框架

NOTE: 所有以 Internal 开头的公开函数，表示这个函数是仅模块可见的。

Index

• Constants
• func Errors(err ...error) error
• func StackError(err error) error
• type CTXSanitizer
• type Context
• type HandlerFunc
• type LocaleStringer
  • func Phrase(key message.Reference, v ...any) LocaleStringer
• type Logger
• type Middleware
• type MiddlewareFunc
• type Module
• type Options
• type QueryUnmarshaler
• type Responser
  • func Created(v any, location string) Responser
  • func NoContent() Responser
  • func OK(v any) Responser
  • func Object(status int, body any, kv ...string) Responser
  • func Redirect(status int, url string) Responser
  • func Status(code int, kv ...string) Responser
• type ResponserFunc
• type Router
• type Rule
  • func NewRule(msg LocaleStringer, v Validator) *Rule
  • func NewRuleFunc(msg LocaleStringer, f func(any) bool) *Rule
• type Server
  • func NewServer(name, version string, o *Options) (*Server, error)
• type ValidateFunc
• type Validation
• type Validator

Constants

const Version = "0.58.2"

Version 当前框架的版本

Functions

func Errors

func Errors(err ...error) error

Errors 合并多个非空错误为一个错误

有关 Is 和 As 均是按顺序找第一个返回 true 的即返回。

func StackError

func StackError(err error) error

StackError 为 err 带上调用信息

位置从调用 StackError 开始。 如果 err 为 nil，则返回 nil，如果 err 本身就为 StackError 返回的类型，则原样返回。

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

Types

type CTXSanitizer

type CTXSanitizer = server.CTXSanitizer

type Context

type Context = server.Context

type HandlerFunc

type HandlerFunc = server.HandlerFunc

type LocaleStringer

type LocaleStringer = localeutil.LocaleStringer

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

部分 error 返回可能也实现了该接口。

func Phrase

func Phrase(key message.Reference, v ...any) LocaleStringer

Phrase 生成本地化的语言片段

type Logger

type Logger = logs.Logger

type Middleware

type Middleware = server.Middleware

type MiddlewareFunc

type MiddlewareFunc = server.MiddlewareFunc

type Module

type Module = server.Module

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 OK

func OK(v any) Responser

OK 返回 200 状态码下的对象

func Object

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

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

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

func Redirect

func Redirect(status int, url string) Responser

Redirect 重定向至新的 URL

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 Rule

type Rule = server.Rule

func NewRule

func NewRule(msg LocaleStringer, v Validator) *Rule

NewRule 新建验证规则

func NewRuleFunc

func NewRuleFunc(msg LocaleStringer, f func(any) bool) *Rule

NewRuleFunc 新建验证规则

type Server

type Server = server.Server

func NewServer

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

NewServer 从 Options 初始化 Server 对象

type ValidateFunc

type ValidateFunc = server.ValidateFunc

type Validation

type Validation = server.Validation

type Validator

type Validator = server.Validator