diff --git a/README.md b/README.md index a05bd4d..4ea39bb 100644 --- a/README.md +++ b/README.md @@ -4,9 +4,10 @@ [![Build Status](https://github.com/vicanso/elton/workflows/Test/badge.svg)](https://github.com/vicanso/elton/actions) -Elton的实现参考了[koa](https://github.com/koajs/koa)以及[echo](https://github.com/labstack/echo),统一中间件的形式,方便定制各类中间件,所有中间件的处理方式都非常简单,如果需要转给下一中间件,则调用`Context.Next()`,如果当前中间件出错,则返回`Error`结束调用,如果无需要转至下一中间件,则无需要调用`Context.Next()`。 -对于成功返回只需将响应数据赋值`Context.Body = 响应数据`,由响应中间件将Body转换为相应的响应数据,如JSON等。 +Elton的实现参考了[koa](https://github.com/koajs/koa)以及[echo](https://github.com/labstack/echo),中间件的调整均为洋葱模型:请求由外至内,响应由内至外。主要特性如下: +- 处理函数(中间件)均以返回error的形式响应出错,方便使用统一的出错处理中间件将出错统一转换为对应的输出(JSON),并根据出错的类型等生成各类统计分析 +- 成功响应数据直接赋值至Context.Body(interface{}),由统一的响应中间件将其转换为对应的输出(JSON,XML) ## Hello, World! diff --git a/SUMMARY.md b/SUMMARY.md index 3502341..0422781 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -1,5 +1,7 @@ # Summary +* [Introduction](./docs/introduction.md) + * [Application](./docs/application.md) * [Context](./docs/context.md) @@ -10,8 +12,6 @@ ## More -* [Introduction](./docs/introduction.md) - * [Body parse and validate](./docs/body_parse_validate.md) * [HTTP2 and HTTP3](./docs/http2_http3.md) diff --git a/docs/application.md b/docs/application.md index 9fbe553..9da9c2d 100644 --- a/docs/application.md +++ b/docs/application.md @@ -59,7 +59,7 @@ func main() { 自定义的Error处理,若路由处理过程中返回Error,则会触发此调用,若未指定此处理函数,则使用默认的处理,简单的输出`err.Error()`。 -注意若在处理过程中返回的Error已被处理(如Error Handler),则并不会触发此出错调用,尽量使用中间件将Error转换为相应的输出,如JSON。 +注意若在处理过程中返回的Error已被处理(如Error Handler),则并不会触发此出错调用,尽量使用中间件将Error转换为相应的输出(如JSON),而此处理仅用于针对未处理出错响应。 **Example** ```go @@ -138,7 +138,7 @@ func main() { ## MethodNotAllowedHandler -该HTTP请求方式不允许,路由匹配正确但是method不匹配时,则会调用此函数(此时所有的中间件也不会被调用)。如果有相关统计需要或者自定义的404页面,则可调整此函数,否则可不设置使用默认处理(返回405 Method Not Allowed)。 +该HTTP请求方式不允许,路由匹配正确但是method不匹配时,则会调用此函数(此时所有的中间件也不会被调用)。如果有相关统计需要或者自定义的405页面,则可调整此函数,否则可不设置使用默认处理(返回405 Method Not Allowed)。 ***Example*** ```go @@ -155,7 +155,7 @@ import ( func main() { e := elton.New() - e.NotFoundHandler = func(resp http.ResponseWriter, req *http.Request) { + e.MethodNotAllowedHandler = func(resp http.ResponseWriter, req *http.Request) { // 可增加统计,方便分析405的处理是被攻击还是接口调用错误 log.Printf("405, method: %s, url:%s", req.Method, req.RequestURI) resp.WriteHeader(http.StatusMethodNotAllowed) diff --git a/docs/context.md b/docs/context.md index dc9d878..39ad428 100644 --- a/docs/context.md +++ b/docs/context.md @@ -42,7 +42,7 @@ HTTP响应数据,此属性为interface{},因此可以设置不同的数据 ## BodyBuffer -HTTP的响应数据缓冲(字节),此数据为真正返回的响应体,不建议直接赋值此属性,而应该则responder中间件将Body转换为字节(BodyBuffer),并写入相应的`Content-Type`。 +HTTP的响应数据(字节),此数据为真正返回的响应体,大部分应用场景使用responder中间件将Body转换为字节赋值(BodyBuffer),并写入相应的`Content-Type`则可,少量应用场景需要可以直接将响应数据赋值而不通过中间件处理。 ## RequestBody @@ -176,7 +176,7 @@ func main() { ## QueryParam -获取query的参数值,此函数返回的并非字符串数组,只取数组的第一个,如果query中的相同的key的使用,请直接使用`Request.URL.Query()`来获取。 +获取query的参数值,此函数返回的并非字符串数组,只取数组的第一个,如果query中相同key的使用,请直接使用`Request.URL.Query()`来获取。 **Example** ```go @@ -534,7 +534,7 @@ func main() { ## MergeHeader -合并HTTP头 +合并HTTP响应头 **Example** ```go @@ -870,7 +870,7 @@ func main() { ## Created -设置HTTP请求的响应码为201,并设置响应体。 +设置HTTP请求的响应码为201,并设置响应体,等价于调用c.StatusCode = 201; c.Body = x; **Example** ```go diff --git a/docs/introduction.md b/docs/introduction.md index ece8332..82e6823 100644 --- a/docs/introduction.md +++ b/docs/introduction.md @@ -8,7 +8,7 @@ description: elton简述 # 概述 -造一个新的轮子的时候,首先考虑的是满足自己的需求,弱水三千只取一瓢饮,对我来说,新轮子的满足我所需要的一瓢:无论成功还是失败的响应都应该由框架最后处理,而不是各中间件或路由处理函数直接将响应至http.ResponseWriter。具体框架主要实现以下要点: +造一个新的轮子的时候,首先考虑的是满足自己的需求,弱水三千只取一瓢饮,新轮子的满足我所需要的一瓢:无论成功还是失败的响应都应该由框架统一处理,而不是各中间件或路由处理函数直接将响应至http.ResponseWriter。为什么有这样的考虑呢?在实际开发过程中,开发人员的能力高低不一,希望可以简单的插入统一的响应处理,便于生成统计报告。具体框架主要实现以下要点: - 请求经过中间件的处理方式为由外至内,响应时再由内至外 - 所有的处理函数都一致(参数、类型等),每个处理函数都可以是其它处理函数的前置中间件 diff --git a/docs/middlewares.md b/docs/middlewares.md index 0a250e3..8b241ff 100644 --- a/docs/middlewares.md +++ b/docs/middlewares.md @@ -8,7 +8,7 @@ description: 各类常用的中间件 - [body parser](#body-parser) 请求数据的解析中间件,支持`application/json`以及`application/x-www-form-urlencoded`两种数据类型 - [compress](#compress) 数据压缩中间件,默认仅支持gzip。如果需要支持更多的压缩方式,如brotli、snappy、zstd以及lz4,可以使用[elton-compress](https://github.com/vicanso/elton-compress),也可根据需要增加相应的压缩处理 - [concurrent limiter](#concurrent-limiter) 根据指定参数限制并发请求,可用于订单提交等防止重复提交或限制提交频率的场景 -- [error handler](#error-handler) 用于将处理函数的Error转换为对应的响应数据,如HTTP响应中的状态码(40x, 50x),对应的出错类别等,建议在实际使用中根据项目自定义的Error对象生成相应的响应数据 +- [error handler](#error-handler) 用于将处理函数的Error转换为对应的响应数据,如HTTP响应中的状态码(4xx, 5xx),对应的出错类别等,建议在实际使用中根据项目自定义的Error对象生成相应的响应数据 - [etag](#etag) 用于生成HTTP响应数据的ETag - [fresh](#fresh) 判断HTTP请求是否未修改(Not Modified) - [json picker](https://github.com/vicanso/elton-json-picker) 用于从响应的JSON中筛选指定字段 @@ -18,7 +18,7 @@ description: 各类常用的中间件 - [recover](#recover) 捕获程序的panic异常,避免程序崩溃 - [responder](#responder) 响应处理中间件,用于将`Context.Body`(interface{})转换为对应的JSON数据并输出。如果系统使用xml等输出响应数据,可参考此中间件实现interface{}至xml的转换 - [router-concurrent-limiter](#router-concurrent-limiter) 路由并发限制中间件,可以针对路由限制并发请求量。 -- [session](https://github.com/vicanso/elton-session) Session中间件,默认支持保存至redis或内存中,也可自定义相应的存储 +- [session](https://github.com/vicanso/elton-session) Session中间件,默认支持保存内存中,可自定义相应的存储实现保存至redis等数据库。 - [stats](#stats) 请求处理的统计中间件,包括处理时长、状态码、响应数据长度、连接数等信息 - [static serve](#static-serve) 静态文件处理中间件,默认支持从目录中读取静态文件或实现StaticFile的相关接口,从[packr](github.com/gobuffalo/packr/v2)或者数据库(mongodb)等读取文件 - [tracker](#tracker) 可以用于在POST、PUT等提交类的接口中增加跟踪日志,此中间件将输出QueryString,Params以及RequestBody部分,并能将指定的字段做"***"的处理,避免输出敏感信息 diff --git a/hooks/pre-commit b/hooks/pre-commit index 46e1d63..9bf7a35 100755 --- a/hooks/pre-commit +++ b/hooks/pre-commit @@ -1,3 +1,3 @@ #!/bin/sh # -make lint \ No newline at end of file +make lint && make test \ No newline at end of file