web 是一个比较完整的 API 开发框架,相对于简单的路由,提供了更多的便利功能。 如果你只是需要一个简单的路由工具,那么你可以移步到 mux。
项目要求 Go 1.27 或更高版本,可通过 Go Modules 添加依赖:
go get github.com/issue9/webpackage main
import (
"errors"
"log"
"net/http"
"github.com/issue9/web"
"github.com/issue9/web/server"
)
func main() {
srv, err := server.NewHTTP("web", "1.0.0", &server.Options{
Startup: web.NewHTTPServerStartup(&http.Server{Addr: ":8080"}),
})
if err != nil {
log.Fatal(err)
}
router := srv.Routers().New("default", nil)
router.Get("/admins", getAdmins).
Get("/groups", getGroups)
if err := srv.Serve(); err != nil && !errors.Is(err, http.ErrServerClosed) {
log.Fatal(err)
}
}
func getAdmins(ctx *web.Context) web.Responser {
return ctx.NotImplemented()
}
func getGroups(ctx *web.Context) web.Responser {
return ctx.NotImplemented()
}编码相关的功能由 Codec 结构体管理,总体上分为以下几个类型:
并没有像其它框架一样为不同的媒体类型输出提供各自不同的方法,而返回统一的对象, 再由客户端的 Accept 等报头协商返回给客户端需要的类型。比如要向用户返回一个 400 的错误, 只需要以下代码:
func handler(ctx *web.Context) web.Responser {
return ctx.Problem(problems.BadRequest).WithParam("username", "不能为空")
}以上代码会向客户端返回 400 的错误,且带一个 username 不能为空的错误信息。
但是具体是渲染成 JSON 还是 XML 亦或是 HTML,无须 handler 函数操心,
可以根据客户端的 Accept 报头提供客户端最需要的格式,
比如客户端的 Accept 为 application/json;q=1 那么会返回 JSON 格式,
如果 Accept 为 application/json;q=0.5,application/xml;q=1 那么会返回 XML 格式。
服务端只需要在初始化服务时配置对应的 web.Codec 对象就可以了。
字符集也是如此,甚至不需要服务端做配置,本身就支持在 https://www.iana.org/assignments/character-sets/character-sets.xhtml 中列出的所有字符集。
import (
"github.com/issue9/web"
"github.com/issue9/web/server"
"github.com/issue9/web/codec"
)
func newServer() (*web.Server, error) {
c := web.NewCodec().
AddMediaType(codec.NewJSON(), true, true).
AddMediaType(codec.NewXML(), true, true)
return server.NewHTTP("app", "1.0.0", &server.Options{Codec: c})
}客户端只要在请求时设置 Accept 报头就可返回相应类型的数据,而 Accept-Charset 报头可设置接收的字符集。 Content-Type 则可以有向服务器指定提交内容的文档类型和字符集。
通过 web.Codec.AddCompressor 可以添加需要支持压缩算法。codec 提供大部分目前浏览器支持的压缩算法。
使用方法也同媒体类型,通过客户端的 Accept-Encoding 自动匹配压缩算法。
框架根据 RFC7807 和 RFC9457 提供了一种输出错误信息内容的机制。
在处理出错时,调用 Context.Problem 即可:
import (
"github.com/issue9/web"
"github.com/issue9/web/problems"
)
func getAdmins(ctx *web.Context) web.Responser {
return ctx.Problem(problems.BadRequest).WithParam("param", "invalid format")
}实现 web.ContextFilter 接口即可在请求数据解码后验证或修正数据。下面的例子会先去掉用户名首尾空格,再检查用户名非空和年龄范围:
import (
"github.com/issue9/web"
"github.com/issue9/web/filter"
"github.com/issue9/web/filter/sanitizers"
"github.com/issue9/web/filter/validators"
"github.com/issue9/web/problems"
)
type CreateUser struct {
Name string `json:"name"`
Age int `json:"age"`
}
func (u *CreateUser) FilterContext(f *filter.Filter, _ *web.Context) {
f.Sanitize(&u.Name, sanitizers.Trim)
f.Valid("name", u.Name, validators.Not(validators.Empty), web.Phrase("不能为空"))
f.Valid("age", u.Age, validators.BetweenEqual(18, 120), web.Phrase("年龄必须在 18 到 120 之间"))
}
func createUser(ctx *web.Context) web.Responser {
var input CreateUser
if resp := ctx.Read(false, &input, problems.BadRequest); resp != nil {
return resp
}
// input 已通过验证,可以继续处理。
return web.NoContent()
}ctx.Read 在请求体解码成功后调用 FilterContext;查询参数对象也会在 ctx.QueryObject 解码后执行该方法。exitAtError 为 false 时会收集所有验证错误,为 true 时遇到首个错误即停止。
filter/validators 和 filter/sanitizers 提供常用的验证器与修正函数,也可以在 FilterContext 中组合自定义逻辑。
可直接在添加 API 的中间件上指定文档内容:
import (
"github.com/issue9/web"
"github.com/issue9/web/openapi"
)
func registerRoutes(srv *web.Server) {
router := srv.Routers().New("default", nil)
doc := openapi.New(srv, web.Phrase("title"))
router.Get("/admins", getAdmins, doc.API(func(o *openapi.Operation) {
o.Desc(web.Phrase("desc of API"))
}))
router.Get("/openapi", doc.Handler())
}提供了多种初始化项目的方式,最简单的方式是直接使用 web.NewServer 创建 Server 对象,但是这个需要提供多个参数,
且要自己保证数据的正确性,一般不推荐。
在 server 下提供了几种常用的初始化方式:
server通过一个可选的Options对象初始化Server;server/config提供了从配置文件加载server.Options的功能,配置项详见 配置文档;server/app则提供了直接创建命令行的工具,可以实现对Server的重启以及注册成系统服务等功能;
- https://github.com/issue9/webuse 提供了中间件、插件、过滤器等常用的功能。
欢迎通过 Issue 和 Pull Request 参与项目。提交前请阅读贡献指南,并遵守行为准则。 尚未修复的安全问题请按照安全政策私下报告,不要在公开 Issue 中披露。