rest

by 夏泽民 Jan 5, 2020

https://github.com/emicklei/go-restful-swagger12
https://github.com/emicklei/go-restful-openapi
https://github.com/emicklei/go-restful
https://github.com/ant0ine/go-json-rest/
go-restful库：https://github.com/emicklei/go-restful

go-restful项目是一个开源的、基于Golang开发的、用于构建REST风格的Web服务的库。

REST
REST要求开发者显式地使用HTTP方法，并与HTTP协议的定义保持一致。REST的基本设计原则是再创建、读取、更新和删除（CRUD）操作和HTTP方法之间建立起一对一的映射。根据该映射：

GET = 检索资源的表示
POST = 创建，使用某种服务器端的算法将内容发送到服务器以创建指定资源或资源的集合
PUT = 创建，如果发送指定URI的完整内容
PUT = 更新，如果要更新指定URI的完整内容
DELETE = 删除，如果要请求服务器删除指定的资源
PATCH = 更新，更新某个资源的部分内容
OPTIONS = 获取请求URI相关的通信选项的信息

go-restful库的特征
路由请求：支持函数映射到路径参数（例如{id}）
路由可配置
（默认）快速路由算法，允许URL路径上出现静态元素、正则表达式、动态参数。比如 /meetings/{id} 或者 /static/{subpath:*}
JSR311规范实现的路由算法
提供了Request API用于从JSON/XML读取结构和访问各种参数（路径参数、查询参数、头部参数）
提供了Response API用于将结构（struct）写入到JSON/XML以及设置头部
支持使用EntityReaderWriter注册的自定义编码
支持在服务级或路由级对请求到响应流的过滤和拦截
支持使用属性来定义请求范围的变量
容器Container支持不同HTTP端点上的WebService
请求和响应的有效负载上的内容编码(gzip,deflate)
（使用过滤器）自动响应OPTIONS请求
（使用过滤器）自动处理CORS请求
支持Swagger UI编写的API文档声明（阅读go-restful-openapi和go-restful-swagger12）
针对HTTP 500状态码的恐慌恢复，使用RecoverHandler(…)自定义处理
路由错误产生HTTP 404/405/406/415等错误，使用ServiceErrorHandler(…)自定义处理
可配置的日志跟踪
使用CompressorProvider注册自定义gzip/deflate的读入器和输出器
二、详解
1、WebServices and Routes
WebService拥有一个Route对象的集合，这些Route对象负责分发即将到来的HTTP请求到相应的函数调用。一般来说，WebService有一个root根路径（例如：/users），还为路由定义了常见的MIME类型。WebService必须添加到某个容器以便能从服务器处理HTTP请求。

Route是根据HTTP分发、URL路径和MIME类型所定义的。

正则表达式匹配路由
路由参数可以使用格式“uri/{var[:regexp]}”或指定版本的“uri/{var:*}”匹配路径尾部进行指定。例如，/persons/{name:[A-Z][A-Z]} 可用来限制name参数的值只能包含大写字母。正则表达式必须使用regexp包中的标准Go语法进行描述。https://code.google.com/p/re2/wiki/Syntax，此功能需要使用CurlyRouter。

2、容器（Container）
容器可以hold住一套WebService的集合、过滤器、一个用于http请求多路复用的http.ServeMux。使用语句“restful.Add(…)”和“restful.Filter(…)”，前者可以在容器注册一个WebService，后者可以过滤。go-restful默认的容器使用http.DefaultServeMux。用户可以创建自己的容器，以及为指定的容器创建一个新的http.Server。

container := restful.NewContainer()
server := &http.Server{Addr: “:8081”, Handler: container}
1
2
3、过滤器（Filter）
过滤器可以动态拦截请求和响应，以及转换或使用请求和响应中包含的信息。用户可以使用过滤器来执行常规的日志记录、测量、验证、重定向、设置响应头部Header等。restful包中有三个针对请求、响应流的钩子，还可以添加过滤器。每个过滤器必须定义一个FilterFunction：

func(req *restful.Request, resp *restful.Response, chain *restful.FilterChain)
1
使用如下语句传递请求/响应对到下一个过滤器或RouteFunction：

chain.ProcessFilter(req, resp)
1
4、容器过滤器（Container Filter）
在注册WebService之前处理：

// 安装一个（全局的）过滤器到默认的容器
restful.Filter(globalLogging)
1
2
5、WebService过滤器（WebService Filter）
在路由WebService之前处理：

// 安装一个WebService过滤器
ws.Filter(webserviceLogging).Filter(measureTime)
1
2
6、路由过滤器（Route Filter）
在调用路由Route相关的函数之前处理：

// 安装2个链式的路由过滤器
ws.Route(ws.GET(“/{user-id}”).Filter(routeLogging).Filter(NewCountFilter().routeCounter))
1
2
例子可见：https://github.com/emicklei/go-restful/blob/master/examples/restful-filters.go

7、响应编码（Response Encoding）
支持两种响应编码：gzip和deflate。要为所有的响应启用它们：

restful.DefaultContainer.EnableContentEncoding(true)
1
如果某个Http请求包含了Accept-Encoding头部，那么响应内容必须使用指定的编码进行压缩。或者，可以创建一个过滤器执行编码并安装它到每一个WebService和Route。

见例子：https://github.com/emicklei/go-restful/blob/master/examples/restful-encoding-filter.go

8、OPTIONS支持
通过安装预定义的容器过滤器，你的WebService可以响应HTTP OPTIONS请求。

Filter(OPTIONSFilter())
1
9、CORS
通过安装CrossOriginResourceSharing过滤器，你的WebService可以处理CORS请求。

cors := CrossOriginResourceSharing{ExposeHeaders: []string{“X-My-Header”}, CookiesAllowed: false, Container: DefaultContainer}
Filter(cors.Filter)
1
2
10、异常处理
意想不到的事情发生。如果因为故障而不能处理请求，服务端需要通过响应告诉客户端发生了什么和为什么。因此使用HTTP状态码，更重要的是要正确的使用状态码。

400: Bad Request
如果路径或查询参数无效（内容或类型），那么使用http.StatusBadRequest。

404: Not Found
尽管URI有效，但请求的资源可能不可用。

500: Internal Server Error
如果应用程序逻辑无法处理请求（或编写响应），则使用http.StatusInternalServerError。

405: Method Not Allowed
请求的URL是有效的，但请求使用的HTTP方法（GET，PUT，POST，…）是不允许的。

406: Not Acceptable
请求的头部没有或设置了未知Accept Header。

415: Unsupported Media Type
请求的头部没有或设置了未知的Content-Type报头。

11、ServiceError
除了设置HTTP状态码，还应该为响应选择写适当的ServiceError消息。

12、性能选项（Performance Options）
这个包有几个选项，它们可能会影响服务的性能。重要的是要理解这些选项，正确地设置它们。

restful.DefaultContainer.DoNotRecover(false)
DoNotRecover控制是否因返回HTTP 500状态码而（恐慌）停止服务。如果设置为false，那么容器Container会恢复服务。默认值为true。

restful.SetCompressorProvider(NewBoundedCachedCompressors(20, 20))
如果启用了内容编码，那么获得新gzip/zlib输出器（writer）和读入器（reader）的默认策略是使用sync.Pool。由于输出器writer是昂贵的结构，当使用预加载缓存时性能提高非常明显。你也可以注入自己的实现。

13、故障排除（Trouble shooting）
这个包可以对完整的Http请求的匹配过程和过滤器调用产生详细的日志记录。启用此功能需要你设置restful.StdLogger的实现，例如log.Logger：

restful.TraceLogger(log.New(os.Stdout, “[restful] “, log.LstdFlags|logs.Lshortfile))
1
使用案例
https://github.com/emicklei/mora
https://github.com/emicklei/landskape

REST（Representational State Transfer，表现层状态转化）是近几年使用较广泛的分布式结点间同步通信的实现方式。REST原则描述网络中client-server的一种交互形式，即用URL定位资源，用HTTP方法描述操作的交互形式。如果CS之间交互的网络接口满足REST风格，则称为RESTful API。以下是理解RESTful架构总结的REST原则：

网络上的资源通过URI统一标示。
客户端和服务器之间传递，这种资源的某种表现层。表现层可以是json，文本，二进制或者图片等。
客户端通过HTTP的四个动词，对服务端资源进行操作，实现表现层状态转化。
为什么要设计RESTful的API，个人理解原因在于：用HTTP的操作统一数据操作接口，限制URL为资源，即每次请求对应某种资源的某种操作，这种无状态的设计可以实现client-server的解耦分离，保证系统两端都有横向扩展能力。

go-restful

go-restful is a package for building REST-style Web Services using Google Go。go-restful定义了Container WebService和Route三个重要数据结构。

Route 表示一条路由，包含 URL/HTTP method/输入输出类型/回调处理函数RouteFunction
WebService 表示一个服务，由多个Route组成，他们共享同一个Root Path
Container 表示一个服务器，由多个WebService和一个 http.ServerMux 组成，使用RouteSelector进行分发
最简单的使用实例，向WebService注册路由，将WebService添加到Container中，由Container负责分发。
func main() {
ws := new(restful.WebService)
ws.Path(“/users”)
ws.Route(ws.GET(“/”).To(u.findAllUsers).
Doc(“get all users”).
Metadata(restfulspec.KeyOpenAPITags, tags).
Writes([]User{}).
Returns(200, “OK”, []User{}))

container := restful.NewContainer().Add(ws)
http.ListenAndServe(“:8080”, container)
}
container

container是根据标准库http的路由器ServeMux写的，并且它通过ServeMux的路由表实现了Handler接口，可参考以前的这篇 HTTP协议与Go的实现。
type Container struct {
webServicesLock sync.RWMutex
webServices []WebService
ServeMux *http.ServeMux
isRegisteredOnRoot bool
containerFilters []FilterFunction
doNotRecover bool // default is true
recoverHandleFunc RecoverHandleFunction
serviceErrorHandleFunc ServiceErrorHandleFunction
router RouteSelector // default is a CurlyRouter
contentEncodingEnabled bool // default is false
}
func (c *Container)ServeHTTP(httpwriter http.ResponseWriter, httpRequest *http.Request) {
c.ServeMux.ServeHTTP(httpwriter, httpRequest)
}
往Container内添加WebService，内部维护的webServices不能有重复的RootPath，
func (c *Container)Add(service *WebService)Container {
c.webServicesLock.Lock()
defer c.webServicesLock.Unlock()
if !c.isRegisteredOnRoot {
c.isRegisteredOnRoot = c.addHandler(service, c.ServeMux)
}
c.webServices = append(c.webServices, service)
return c
}
添加到container并注册到mux的是dispatch这个函数，它负责根据不同WebService的rootPath进行分发。
func (c *Container)addHandler(service *WebService, serveMux *http.ServeMux)bool {
pattern := fixedPrefixPath(service.RootPath())
serveMux.HandleFunc(pattern, c.dispatch)
}
webservice

每组webservice表示一个共享rootPath的服务，其中rootPath通过 ws.Path() 设置。
type WebService struct {
rootPath string
pathExpr pathExpression
routes []Route
produces []string
consumes []string
pathParameters []Parameter
filters []FilterFunction
documentation string
apiVersion string

typeNameHandleFunc TypeNameHandleFunction
dynamicRoutes bool
routesLock sync.RWMutex
}
通过Route注册的路由最终构成Route结构体，添加到WebService的routes中。
func (w WebService)Route(builder *RouteBuilder)WebService {
w.routesLock.Lock()
defer w.routesLock.Unlock()
builder.copyDefaults(w.produces, w.consumes)
w.routes = append(w.routes, builder.Build())
return w
}
route

通过RouteBuilder构造Route信息，Path结合了rootPath和subPath。Function是路由Handler，即处理函数，它通过 ws.Get(subPath).To(function) 的方式加入。Filters实现了个类似gRPC拦截器的东西，也类似go-chassis的chain。
type Route struct {
Method string
Produces []string
Consumes []string
Path string // webservice root path + described path
Function RouteFunction
Filters []FilterFunction
If []RouteSelectionConditionFunction
// cached values for dispatching
relativePath string
pathParts []string
pathExpr pathExpression
// documentation
Doc string
Notes string
Operation string
ParameterDocs []Parameter
ResponseErrors map[int]ResponseError
ReadSample, WriteSample interface{}
Metadata map[string]interface{}
Deprecated bool
}
dispatch

server侧的主要功能就是路由选择和分发。http包实现了一个 ServeMux ，go-restful在这个基础上封装了多个服务，如何在从container开始将路由分发给webservice，再由webservice分发给具体处理函数。这些都在 dispatch 中实现。

SelectRoute根据Req在注册的WebService中选择匹配的WebService和匹配的Route。其中路由选择器默认是 CurlyRouter 。
解析pathParams，将wrap的请求和相应交给路由的处理函数处理。如果有filters定义，则链式处理。
func (c *Container)dispatch(httpWriter http.ResponseWriter, httpRequest *http.Request) {
func() {
c.webServicesLock.RLock()
defer c.webServicesLock.RUnlock()
webService, route, err = c.router.SelectRoute(
c.webServices,
httpRequest)
}()

pathProcessor, routerProcessesPath := c.router.(PathProcessor)
pathParams := pathProcessor.ExtractParameters(route, webService, httpRequest.URL.Path)
wrappedRequest, wrappedResponse := route.wrapRequestResponse(writer,
httpRequest, pathParams)

if len(c.containerFilters)+len(webService.filters)+len(route.Filters) > 0 {
chain := FilterChain{Filters: allFilters, Target: func(req *Request, resp *Response) {
// handle request by route after passing all filters
route.Function(wrappedRequest, wrappedResponse)
}}
chain.ProcessFilter(wrappedRequest, wrappedResponse)
} else {
route.Function(wrappedRequest, wrappedResponse)
}
}
go-chassis

go-chassis实现的rest-server是在go-restful上的一层封装。Register时只要将注册的schema解析成routes，并注册到webService中，Start启动server时 container.Add(r.ws) ，同时将container作为handler交给 http.Server , 最后开始ListenAndServe即可。
type restfulServer struct {
microServiceName string
container *restful.Container
ws *restful.WebService
opts server.Options
mux sync.RWMutex
exit chan chan error
server *http.Server
}
根据Method不同，向WebService注册不同方法的handle，从schema读取的routes信息包含Method，Func以及PathPattern。
func (r *restfulServer)Register(schemainterface{}, options …server.RegisterOption)(string, error) {
schemaType := reflect.TypeOf(schema)
schemaValue := reflect.ValueOf(schema)
var schemaName string
tokens := strings.Split(schemaType.String(), “.”)
if len(tokens) >= 1 {
schemaName = tokens[len(tokens)-1]
}

routes, err := GetRoutes(schema)
for _, route := range routes {
lager.Logger.Infof(“Add route path: [%s] Method: [%s] Func: [%s]. “,
route.Path, route.Method, route.ResourceFuncName)
method, exist := schemaType.MethodByName(route.ResourceFuncName)
…
handle := func(req *restful.Request, rep *restful.Response) {
c, err := handler.GetChain(common.Provider, r.opts.ChainName)
inv := invocation.Invocation{
MicroServiceName: config.SelfServiceName,
SourceMicroService: req.HeaderParameter(common.HeaderSourceName),
Args: req,
Protocol: common.ProtocolRest,
SchemaID: schemaName,
OperationID: method.Name,
}
bs := NewBaseServer(context.TODO())
bs.req = req
bs.resp = rep
c.Next(&inv, func(ir *invocation.InvocationResponse)error {
if ir.Err != nil {
return ir.Err
}
method.Func.Call([]reflect.Value{schemaValue, reflect.ValueOf(bs)})
if bs.resp.StatusCode() >= http.StatusBadRequest {
return …
}
return nil
})
}

switch route.Method {

case http.MethodGet:

  r.ws.Route(r.ws.GET(route.Path).To(handle).

   Doc(route.ResourceFuncName).

   Operation(route.ResourceFuncName))

...

}   }   return reflect.TypeOf(schema).String(), nil }

一、go-json-rest框架介绍
go-json-rest（https://github.com/ant0ine/go-json-rest/）是基于net/http的一个小封装，可帮助轻松构建RESTful JSON API。它使用基于Trie的实现提供快速和可拓展的请求路由，帮助处理JSON请求和响应。它拥有丰富的中间件，比如CORS，Auth，Gzip，Status等，可帮助实现和拓展功能。此外，还有一些与go-json-rest兼容的第三方中间件，比如JWT，AuthToken等

二、go-json-rest的简单实用
使用命令进行安装：

go get github.com/ant0ine/go-json-rest/rest
新建一个main.go，导入go-json-rest，这里以一个简单例子进行说明：

package main

import (
“github.com/ant0ine/go-json-rest/rest”
“log”
“net/http”
)

func main() {
api := rest.NewApi()
api.Use(rest.DefaultDevStack…)
router, err := rest.MakeRouter(
rest.Get(“/message”, func(w rest.ResponseWriter, req *rest.Request) {
w.WriteJson(map[string]string{“Body”: “Hello World!”})
}),
)
if err != nil {
log.Fatal(err)
}
api.SetApp(router)
http.Handle(“/api/”, http.StripPrefix(“/api”, api.MakeHandler()))
log.Fatal(http.ListenAndServe(“:8080”, nil))
}
在浏览器端输入http://localhost:8080/api/message
三、go-json-rest在项目中开发
可以按照设计模型、连接数据库、设计控制器、配置路由流程进行开发。

项目场景：需要实现一个用户管理系统，该系统主要是对用户的基本信息进行管理。

设计模型
该系统最核心的是用户模块，模型设计时需要考虑的是用户的属性信息，比如邮箱、联系方式等等。模型构建如下，左边表示golang实现的结构体，右边表示数据表设计。

连接数据库
这里使用的gorm来操作数据库，它是golang语言写的ORM库。

源码地址：https://github.com/jinzhu/gorm

中文文档：http://gorm.book.jasperxu.com/

这一步骤主要是对数据库连接相关进行设置，使用时需要先下载安装gorm源码，然后导入gorm及驱动，下面展示gorm连接数据库示例：

package db

import (
“github.com/jinzhu/gorm”
_ “github.com/jinzhu/gorm/dialects/mysql”
“time”
“log”
)

type BaseGorm struct {
DB *gorm.DB
}

var baseDB *gorm.DB

func (this BaseGorm) InitDB() {
var err error
this.DB, err = gorm.Open(“mysql”, “root:@tcp(localhost:3306)/userdb?charset=utf8&parseTime=true&loc=Local”)
if err != nil {
log.Fatal(err)
return
}
this.DB.SingularTable(true)
this.DB.DB().SetMaxIdleConns(10)
this.DB.DB().SetMaxOpenConns(100)
this.DB.DB().SetConnMaxLifetime(300time.Second)
this.DB.LogMode(true)
baseDB = this.DB
}
func (this *BaseGorm) GetDB() (DB *gorm.DB) {
if baseDB != nil {
DB = baseDB
} else {
log.Fatal(“DB not initial.”)
return
}
return
}

设计控制器
设计控制器，其实就是接口的设计。因为这个系统主要是对用户的基本信息进行管理，大致可设计为：登陆、注册、退出、新增用户、修改用户、删除用户、查看用户（获取所有用户信息、获取指定id的用户信息）接口。

要实现接口，可按照三步走策略进行：第一步：解析获取数据（比如需要新增新用户，会post一些json类型数据；删除用户，需要delete到具体的id值等）；第二步：通过gorm来操作数据库；第三步：返回结果，作出响应。下面展示的是查询指定id的用户信息接口实现：

func (userController *UserController) QueryUserById(w rest.ResponseWriter, r *rest.Request) {
returnJson := make(map[string]interface{})

//解析获取数据

id := r.PathParam("id")

userId, _ := strconv.Atoi(id)

//通过gorm操作数据库

baseGorm:=db.BaseGorm{}

userInfo, err := baseGorm.QueryUserInfoById(userId)

if err != nil {

	log.Fatal(err)

	//操作失败返回结果

	returnJson["code"] = 1

	returnJson["msg"] = err.Error()

	panic(w.WriteJson(returnJson))

	return

}

//操作成功返回结果

returnJson["code"] = 0

returnJson["msg"] = "query userInfo success!"

returnJson["user"] = userInfo

w.WriteJson(returnJson) }

配置路由
这一步骤需要将URI与接口进行对接，当客户端访问URI时，可以访问到对应的接口，获取期望的结果。当然，可以在这里使用中间件，比如AuthTokenMiddleware等。

package main

import (
“github.com/ant0ine/go-json-rest/rest”
“log”
“net/http”
“userMgmtDemo/controller”
“userMgmtDemo/db”
“userMgmtDemo/common”
)

func main() {
new(db.BaseGorm).InitDB()
api := rest.NewApi()
api.Use(rest.DefaultDevStack…)

// 使用第三方中间件AuthTokenMiddleware，对token进行验证

tokenAuthMiddleware := &common.AuthTokenMiddleware{

	Realm: "jwt auth",

	Authenticator: func(token string) string {

		var baseGorm *db.BaseGorm

		userInfo, count, err := baseGorm.QueryUseInfoByToken(token)

		if err != nil || count == 0 {

			return ""

		} else {

			return userInfo.Deadline

		}

	},//返回为空，则说明token验证不通过，不能继续访问接口；返回有值，再将其与数据库中的失效时间字段进行对比，判断是否失效，失效则不能继续访问接口

	Authorizer: nil,

}

//使用go-json-rest自带的中间件IfMiddleware筛选判断

//因为login、register接口在使用时没有token，不能经过AuthTokenMiddleware中间件验证，因此需要将其过滤

api.Use(&rest.IfMiddleware{

	Condition: func(request *rest.Request) bool {

		var arr = []string{

			"/login","/register",

		}

		for _, item := range arr {

			if item == request.URL.Path {

				return false

			}

		}

		return true

	},

	IfTrue: tokenAuthMiddleware,

})

router, err := rest.MakeRouter(

	rest.Post("/login",new (controller.WebController).Login),

	rest.Post("/register",new (controller.WebController).Register),

	rest.Put("/loginout/:id",new (controller.WebController).Loginout),

	rest.Get("/users/:id", new (controller.UserController).QueryUserById),

	rest.Get("/users",new (controller.UserController).QueryAllUser),

	rest.Delete("/users/:id", new (controller.UserController).DeleteUser),

	rest.Put("/users",new (controller.UserController).UpdateUser),

)

if err != nil {

	log.Fatal(err)

}

api.SetApp(router)

http.Handle("/api/", http.StripPrefix("/api", api.MakeHandler()))

log.Fatal(http.ListenAndServe(":8080", nil)) }

至此，使用go-json-rest框架就开发完成了。如若需要测试接口是够运行正确，可以使用Postman工具进行测试，非常方便。

Category golang