Golang — RESTful框架 go-restful

go-restful

go-restful 是一个 Golang 第三方库，是一个轻量的 RESTful API 框架，基于 Golang Build-in 的 http/net 库。适用于构建灵活多变的 Web Application，Kubernetes 的 ApiServer 也使用了 go-restful。

特性

• 支持使用路径参数进行请求→函数映射的路由
• 可配置的路由器：默认使用 CurlyRouter 快速路由算法，也支持 RouterJSR311。
• 提供 Request API 用于从 JSON、XML 读取路径参数、查询参数、头部参数，并转换为 Struct。
• 提供 Response API 用于将 Struct 写入到 JSON、XML 以及 Header。
• 支持在服务级、或路由级对请求、响应流进行过滤和拦截。
• 不同HTTP端点上的WebServices容器
• 支持使用过滤器自动响应 OPTIONS 请求和 CORS（跨域）请求。
• 支持使用 RecoverHandler 自定义处理 HTTP 500 错误。
• 支持使用 ServiceErrorHandler 自定义处理路由错误产生 HTTP 404/405/406/415 等错误。
• 支持对请求、响应的有效负载进行编码（例如：gzip、deflate）。
• 支持使用 CompressorProvider 注册自定义的 gzip、deflate 的读入器和输出器。
• 支持使用 EntityReaderWriter 注册的自定义编码实现。
• 支持 Swagger UI 编写的 API 文档。
• 支持可配置的日志跟踪

概念

Routes

Route是由HTTP方法、URL路径和使用的MIME类型(Content-Type)和生成的MIME类型(Accept)定义的。这个包有查找最佳匹配Route的逻辑，如果找到了，就调用它的Function。

WebServices

WebService有一个Route对象集合，这些对象将流入的Http请求分派给一个函数调用。通常，WebService有一个根路径(例如/users)，并为它的路由定义了常见的MIME类型。为了处理来自服务器的Http请求，必须将WebServices添加到容器中。

Containers

容器包含WebServices、Filters和用于复用http请求的http.ServeMux的集合。使用restful.add(…)和restful.filter(…)将WebServices和Filters注册到默认容器中。go-rest的默认容器使用http.DefaultServeMux。您可以创建自己的Container并为特定容器创建一个新的http.Server。

Filters

过滤器动态地拦截请求和响应，以转换或使用包含在请求或响应中的信息。您可以使用过滤器来执行通用的日志记录、测量、身份验证、重定向、设置响应头等。在restfull包中，有三个hook进入请求、响应流，可以在其中添加过滤器。

Container Filters

在任意已注册的WebService之前处理这些服务。

// 为默认容器安装一个(全局)过滤器(在任意webservice之前处理)
restful.Filter(globalLogging)

WebService Filters

在WebService的任意路由之前处理。

// 安装webservice过滤器(在任意路由之前处理)
ws.Filter(webserviceLogging).Filter(measureTime)

Route Filters

在调用与路由相关的函数之前被处理。

// 安装2个链式路由过滤器(在调用findUser之前处理)
ws.Route(ws.GET("/{user-id}").Filter(routeLogging).Filter(NewCountFilter().routeCounter).To(findUser))

自定义Filters

每个 Filter 必须实现一个 FilterFunction

func(req *restful.Request, resp *restful.Response, chain *restful.FilterChain)

并使用如下语句传递请求、响应对到下一个 Filter 或 RouteFunction：

chain.ProcessFilter(req, resp)

示例

package main

import (
	"io"
	"log"
	"net/http"

	"github.com/emicklei/go-restful"
	swagger "github.com/emicklei/go-restful-swagger12"
)

type UserResource struct{}

func (u UserResource) result(request *restful.Request, response *restful.Response) {
	io.WriteString(response.ResponseWriter, "this would be a normal response")
}

func (UserResource) SwaggerDoc() map[string]string {
	return map[string]string{
		"":         "Address doc",
		"country":  "Country doc",
		"postcode": "PostCode doc",
	}
}

func (u UserResource) RegisterTo(container *restful.Container) {
	ws := new(restful.WebService)
	ws.Path("/user").Consumes("*/*").Produces("*/*")

	ws.Route(ws.GET("/{id}").
		To(u.result).
		Doc("方法描述：获取用户").
		Param(ws.PathParameter("id", "参数描述:用户ID").DataType("string")).
		Param(ws.QueryParameter("name", "用户名称").DataType("string")).
		Param(ws.HeaderParameter("token", "访问令牌").DataType("string")).
		Do(returns200, returns500))
	ws.Route(ws.POST("").To(u.result))
	ws.Route(ws.PUT("/{id}").To(u.result))
	ws.Route(ws.DELETE("/{id}").To(u.result))

	container.Add(ws)
}

func returns200(b *restful.RouteBuilder) {
	b.Returns(http.StatusOK, "OK", "success")
}

func returns500(b *restful.RouteBuilder) {
	b.Returns(http.StatusInternalServerError, "Bummer, something went wrong", nil)
}

func main() {
	wsContainer := restful.NewContainer()

	// 跨域过滤器
	cors := restful.CrossOriginResourceSharing{
		ExposeHeaders:  []string{"X-My-Header"},
		AllowedHeaders: []string{"Content-Type", "Accept"},
		AllowedMethods: []string{"GET", "POST"},
		CookiesAllowed: false,
		Container:      wsContainer}
	wsContainer.Filter(cors.Filter)

	// Add container filter to respond to OPTIONS
	wsContainer.Filter(wsContainer.OPTIONSFilter)

	config := swagger.Config{
		WebServices:    restful.DefaultContainer.RegisteredWebServices(), // you control what services are visible
		WebServicesUrl: "http://localhost:8080",
		ApiPath:        "/apidocs.json",
		ApiVersion:     "V1.0",
		// Optionally, specify where the UI is located
		SwaggerPath:     "/apidocs/",
		SwaggerFilePath: "D:/gowork/src/doublegao/experiment/restful/dist"}
	swagger.RegisterSwaggerService(config, wsContainer)
	swagger.InstallSwaggerService(config)

	u := UserResource{}
	u.RegisterTo(wsContainer)

	log.Print("start listening on localhost:8080")
	server := &http.Server{Addr: ":8080", Handler: wsContainer}
	defer server.Close()
	log.Fatal(server.ListenAndServe())

}