安装

go get -u github.com/kataras/iris
若遇到下面这种情况：
image.png
可删除保存路径中的kataras目录，并执行go get github.com/kataras/iris/v12@master

快速开始

创建一个空文件，假设它的名字是example.go，然后打开它并复制粘贴下面的代码。

  1. package main
  3. import "github.com/kataras/iris/v12"
  5. func main() {
  6.     app := iris.Default()
  7.     app.Use(myMiddleware)  // 使用自定义的中间件，这里和gin很相似
  9.     app.Handle("GET", "/ping", func(ctx iris.Context) {
  10.         ctx.JSON(iris.Map{"message": "pong"})
  11.     })
  13.     // 监听8080端口
  14.     app.Listen(":8080")
  15. }
  17. func myMiddleware(ctx iris.Context) {
  18.     ctx.Application().Logger().Infof("Runs before %s", ctx.Path())
  19.     ctx.Next()
  20. }

Show me more

  1. package main
  3. import "github.com/kataras/iris/v12"
  5. func main() {
  6.     app := iris.New()
  7.     // 加载./view文件夹下所有的模板文件，如果它们的后缀是./html，则解析它们
  8.     // 使用标准的' html/template '包
  9.     app.RegisterView(iris.HTML("./views", ".html"))
  11.     // Method:    GET
  12.     // Resource:  http://localhost:8080
  13.     app.Get("/", func(ctx iris.Context) {
  14.            // 绑定kv
  15.         ctx.ViewData("message", "Hello world!")
  16.         // 渲染模板文件./views.hello.html
  17.         ctx.View("hello.html")
  18.     })
  20.     // Method:    GET
  21.     // Resource:  http://localhost:8080/user/42
  23.     // 获取GET路径上的param
  24.     app.Get("/user/{id:uint64}", func(ctx iris.Context) {
  25.         userID, _ := ctx.Params().GetUint64("id")
  26.         ctx.Writef("User ID: %d", userID)
  27.     })
  29.     // 监听端口
  30.     app.Listen(":8080")
  31. }
  1. <!-- file: ./views/hello.html -->
  2. <html>
  3. <head>
  4.     <title>Hello Page</title>
  5. </head>
  6. <body>
  7.     <h1>{{.message}}</h1>  
  8. </body>
  9. </html>

路由

Handler

一个Handler，正如其名，用于处理请求。
一个处理程序用于响应 HTTP 请求。它把响应头和数据写入 Context.ResponseWriter() 然后返回请求完成的的信号。
在请求完成之后是不能使用上下文的。
取决于 HTTP 客户端软件，HTTP 协议版本，以及任何客户端和服务器之间的中间件，在写入 context.ResponseWriter() 之后可能无法从 Context.Request().Body 读取内容。严谨的处理程序应该首先读取 Context.Request().Body ，然后再响应。除了读取请求体，处理程序不应该更改修改提供的上下文。如果处理程序崩溃掉，服务器任务崩溃只是影响了当前的请求。恢复之后，记录错误日志中然后挂断连接。

  1. type Handler func(Context)

API

所有的 HTTP 方法都支持，开发者可以为相同路径的处理程序注册不同的方法。
第一个参数是 HTTP 方法，第二个参数是路由路径，第三个可变参数应该包含一个或者多个 iris.Handler，当获取某个资源的请求从服务器到来时，处理器按照注册顺序被调用执行。
示例代码：

  1. app := iris.New()
  3. app.Handle("GET","/contact",func(ctx iris.Context){
  4.     ctx.HTML("<h1>Hello from /contact </h1>")
  5. })

为了让开发者更容易开发处理程序，iris 提供了所有的 HTTP 方法。第一个参数是路由路径，第二个可变参数是一个或者多个 iris.Handler。
示例代码:

  1. app := iris.New()
  3. // 方法: "GET"
  4. app.Get("/", handler)
  6. // 方法: "POST"
  7. app.Post("/", handler)
  9. // 方法: "PUT"
  10. app.Put("/", handler)
  12. // 方法: "DELETE"
  13. app.Delete("/", handler)
  15. // 方法: "OPTIONS"
  16. app.Options("/", handler)
  18. // 方法: "TRACE"
  19. app.Trace("/", handler)
  21. // 方法: "CONNECT"
  22. app.Connect("/", handler)
  24. // 方法: "HEAD"
  25. app.Head("/", handler)
  27. // 方法: "PATCH"
  28. app.Patch("/", handler)
  30. // 用于所有 HTTP 方法
  31. app.Any("/", handler)
  33. func handler(ctx iris.Context){
  34.     ctx.Writef("Hello from method: %s and path: %s", ctx.Method(), ctx.Path())
  35. }

路由分组

一组路由可以用前缀路径分组，组之间共享相同的中间件和模板布局，组内可以嵌套组。
.Party 被用于分组路由，开发者可以声明不限数量的分组。
示例代码：

  1. func main() {
  2.     app := iris.New()
  4.     users := app.Party("/user",MyMiddleware)
  7.     users.Get("/{id:int}/profile",userProfileHandler)
  9.     users.Get("/messages/{id:int}",userMessageHandler)
  12.     app.Run(iris.Addr(":8080"))
  13. }
  15. // 处理器函数
  16. func userProfileHandler(ctx iris.Context){
  17.     p,_ := ctx.Params().GetInt("id")
  19.     ctx.Writef("userProfileHandler p = %d",p)
  20. }
  22. // 处理器函数
  23. func userMessageHandler(ctx iris.Context){
  24.     p, _ := ctx.Params().GetInt("id")
  25.     ctx.Writef("userMessageHandler p = %d",p)
  26. }
  28. // 中间件
  29. func MyMiddleware(ctx iris.Context){
  30.     ctx.Application().Logger().Infof("Runs before %s",ctx.Path())
  31.     ctx.Next()
  32. }

同样也可以这样写，使用一个接收子路由的函数:

  1. app := iris.New()
  3. app.PartyFunc("/users",func(users iris.Party){
  5.     users.Use(MyMiddleware)
  7.     users.Get("/{id:int}/profile",userProfileHandler)
  9.     users.Get("/messages/{id:int}",userMessageHandler)
  10. })
  12. app.Run(iris.Addr(":8080"))

Context机制

上下文是服务器用于所有客户端的中间人“对象”，对于每一个新的链接，都会从sync.Pool中获取一个新上下文对象。
上下文是iris的http流中最重要的部分。
开发者发送响应到客户端的请求通过一个上下文，开发者获取请求信息从客户端的请求上下文中。
context是context.Context子包的实现，context.Context是很好的扩展，所以开发者可以按照实际所需重写它的方法。

  1. type Context interface{
  2.     // ResponseWriter 如期返回一个兼容 http.ResponseWriter 的 响应writer。
  3.     ResponseWriter() ResponseWriter
  4.     // ResetResponseWriter 应该改变或者升级上下文的 ResponseWriter。
  5.     ResetResponseWriter(ResponseWriter)
  7.     // Request 方法如期返回原始的 *http.Request。
  8.     Request() *http.Request
  10.     // SetCurrentRouteName 方法设置内部路由名称，为了当开发者调用
  11.     // `GetCurrentRoute()` 方法的时候能够正确返回当前 「只读」 路由。
  12.     // 它使用 Router 初始化，如果你手动更改了名称，除了当你是使用`GetCurrentRoute()` 
  13.     // 的时候将获取到其他路由，其它没啥变化。
  14.     // 为了从上下文中执行一个不同的路径，你应该使用 `Exec` 函数，
  15.     // 或者通过 `SetHandlers/AddHandler` 函数改变处理方法。
  17.     SetCurrentRouteName(currentRouteName string)
  18.     // GetCurrentRoute 返回当前注册到当前请求路径的 「只读」路由。
  19.     GetCurrentRoute() RouteReadOnly
  21.     // AddHandler 可以在服务时添加处理方法到当前请求，但是这些处理方法不会持久化到路由。
  22.     // 
  23.     // Router 将会调用这些添加到某个路由的处理方法。如果 AddHandler 被调用，
  24.     // 那么处理方法将被添加到已经定义的路由的处理方法的后面。
  25.     AddHandler(...Handler)
  26.     // SetHandlers 替换所有原有的处理方法。
  27.     SetHandlers(Handlers)
  28.     // Handlers 记录当前的处理方法。
  29.     Handlers() Handlers
  31.     // HandlerIndex 设置当前上下文处理方法链中当前索引。
  32.     // 如果传入 -1 ，不会当前索引。
  33.     //
  34.     // 也可以查看 Handlers(), Next() and StopExecution()。
  35.     HandlerIndex(n int) (currentIndex int)
  36.     // HandlerName 返回当前路由名称，方便调试。
  37.     HandlerName() string
  38.     // Next 调用从处理方法链中选择剩下的进行调用，他应该被用于一个中间件中。
  39.     // 
  40.     // 提醒：自定义的上下文应该重写这个方法，以便能够传入他自己的 context.Context 实现。
  41.     Next()
  42.     // NextHandler 从处理链中返回下一个处理方法(但不执行)。
  43.     // 
  44.     // 为了执行下一个 ，可以使用 .Skip() 跳过某个处理方法。
  45.     NextHandler() Handler
  46.     // Skip 从处理链中 忽略/跳过 下一个处理方法。
  47.     // 它应该在中间件内使用。
  48.     Skip()
  49.     // 如果调用了 StopExecution ，接下来的 .Next 调用将被局略。
  50.     StopExecution()
  51.     // IsStopped 检查当前位置的Context是否是255, 如果是, 则返回true, 意味着 StopExecution() 被调用了。
  52.     IsStopped() bool
  54.     //  +------------------------------------------------------------+
  55.     //  | 当前的 "user/request" 存储                                    |
  56.     //  | 处理方法之间共享信息 - Values().                                  |
  57.     //  | 保存并获取路径参数 - Params()                                    |
  58.     //  +------------------------------------------------------------+
  60.     // Params 返回当前URL中的命名参数。命名的路径参数是被保存在这里的。
  61.     // 这个存储对象随着整个上下文，存活于每个请求声明周期。
  62.     Params() *RequestParams
  64.     // Values 返回当前 「用户」的存储信息。
  65.     // 命名路径参数和任何可选数据可以保存在这里。
  66.     // 这个存储对象，也是存在于整个上下文，每个请求的声明周期中。
  67.     // 
  68.     // 你可以用这个函数设置和获取用于在处理方法和中间件之间共享信息的局部值。
  69.     Values() *memstore.Store
  70.     // Translate 是 i18n 函数，用于本地化。它调用 Get("translate") 返回翻译值。
  71.     //
  72.     // 示例：https://github.com/kataras/iris/tree/master/_examples/miscellaneous/i18n
  73.     Translate(format string, args ...interface{}) string
  75.     //  +------------------------------------------------------------+
  76.     //  | 路径, 主机, 子域名, IP, HTTP 头 等                            |
  77.     //  +------------------------------------------------------------+
  79.     // Method 返回 request.Method， 客户端的请求方法。
  80.     Method() string
  81.     // Path 返回完整请求路径，如果 EnablePathEscape 为 True，将会转义。
  82.     Path() string
  83.     // RequestPath 返回转义过的请求完整路径。
  84.     RequestPath(escape bool) string
  86.     // Host 返回当前URL的主机部分。
  87.     Host() string
  88.     // Subdomain 返回当前请求的子域名，如果有。
  89.     // 提醒，这个方法可能在某些情况下不能正常使用。
  90.     Subdomain() (subdomain string)
  91.     // RemoteAddr 尝试解析并返回客户端正式IP。
  92.     //
  93.     // 基于允许的头名称，可以通过 Configuration.RemoteAddrHeaders  修改。
  94.     //
  95.     // 如果基于这些请求头的解析失败，将会 Request 的 `RemoteAddr` 字段，它在 Http 处理方法之前有 server 填充。
  96.     //
  97.     // 查看 `Configuration.RemoteAddrHeaders`,
  98.     //      `Configuration.WithRemoteAddrHeader(...)`,
  99.     //      `Configuration.WithoutRemoteAddrHeader(...)` 获取更多信息。
  100.     RemoteAddr() string
  101.     // GetHeader 返回指定的请求头值。
  102.     GetHeader(name string) string
  103.     // IsAjax 返回这个请求是否是一个 'ajax request'( XMLHttpRequest)。
  104.     //
  105.     // 不能百分之百确定一个请求是否是Ajax模式。
  106.     // 永远不要信任来自客户端的数据，他们很容易被篡改。
  107.     //
  108.     // 提醒，"X-Requested-With" 头可以被任何客户端修改，对于十分严重的情况，不要依赖于 IsAjax。
  109.     // 试试另外的鉴别方式，例如，内容类型（content-type）。
  110.     // 有很多描述这些问题的博客并且提供了很多不同的解决方案，这就是为什么说 `IsAjax` 
  111.     // 太简单，只能用于一般目的。
  112.     //
  113.     // 更多请看： https://developer.mozilla.org/en-US/docs/AJAX
  114.     // 以及： https://xhr.spec.whatwg.org/
  115.     IsAjax() bool
  117.     //  +------------------------------------------------------------+
  118.     //  | 响应头助手                                                   |
  119.     //  +------------------------------------------------------------+
  121.     // Header 添加响应头到响应 writer。
  122.     Header(name string, value string)
  124.     // ContentType 设置响应头 "Content-Type" 为 'cType'。
  125.     ContentType(cType string)
  126.     // GetContentType 返回响应头 "Content-Type" 的值。
  127.     GetContentType() string
  129.     // StatusCode 设置响应状态码。
  130.     // 也可查看 .GetStatusCode。
  131.     StatusCode(statusCode int)
  132.     // GetStatusCode 返回当前响应的状态码。
  133.     // 也可查阅 StatusCode。
  134.     GetStatusCode() int
  136.     // Redirect 发送一个重定向响应到客户端，接受两个参数，字符串和可选的证书。
  137.     // 第一个参数是重定向的URL，第二个是重定向状态码，默认是302。
  138.     // 如果必要，你可以设置为301，代表永久转义。
  139.     Redirect(urlToRedirect string, statusHeader ...int)
  141.     //  +------------------------------------------------------------+
  142.     //  | 各种请求和 POST 数据                                         |
  143.     //  +------------------------------------------------------------+
  145.     // URLParam 返回请求中的参数，如果有。
  146.     URLParam(name string) string
  147.     // URLParamInt 从请求返回 int 类型的URL参数，如果解析失败，返回错误。
  148.     URLParamInt(name string) (int, error)
  149.     // URLParamInt64 从请求返回 int64 类型的参数，如果解析失败，返回错误。
  150.     URLParamInt64(name string) (int64, error)
  151.     // URLParams 返回请求查询参数映射，如果没有，返回为空。
  152.     URLParams() map[string]string
  154.     // FormValue 返回一个表单值。
  155.     FormValue(name string) string
  156.     // FormValues 从 data，get，post 和 查询参数中返回所有的数据值以及他们的键。
  157.     //
  158.     // 提醒: 检查是否是 nil 是很有必要的。
  159.     FormValues() map[string][]string
  160.     // PostValue 仅仅根据名称返回表单的post值，类似于 Request.PostFormValue。
  161.     PostValue(name string) string
  162.     // FormFile 返回键指定的第一个文件。
  163.     // 如果有必要，FormFile 调用 ctx.Request.ParseMultipartForm 和 ParseForm。
  164.     //
  165.     // 类似于 Request.FormFile.
  166.     FormFile(key string) (multipart.File, *multipart.FileHeader, error)
  168.     //  +------------------------------------------------------------+
  169.     //  | 自定义 HTTP 错误                                             |
  170.     //  +------------------------------------------------------------+
  172.     // NotFound 发送一个 404 错误到客户端，使用自定义的错误处理方法。
  173.     // 如果你不想剩下的处理方法被执行，你可能需要去调用 ctx.StopExecution()。
  174.     // 你可以将错误码改成更具体的，例如：
  175.     // users := app.Party("/users")
  176.     // users.Done(func(ctx context.Context){ if ctx.StatusCode() == 400 { /*  custom error code for /users */ }})
  177.     NotFound()
  179.     //  +------------------------------------------------------------+
  180.     //  | Body Readers                                               |
  181.     //  +------------------------------------------------------------+
  183.     // SetMaxRequestBodySize 设置请求体大小的上限，应该在读取请求体之前调用。
  184.     SetMaxRequestBodySize(limitOverBytes int64)
  186.     // UnmarshalBody 读取请求体，并把它绑定到一个任何类型或者指针的值。
  187.     // 使用实例: context.ReadJSON, context.ReadXML。
  188.     UnmarshalBody(v interface{}, unmarshaler Unmarshaler) error
  189.     // ReadJSON 从请求体读取 JSON，并把它绑定到任何json有效类型的值。
  190.     ReadJSON(jsonObject interface{}) error
  191.     // ReadXML 从请求体读取 XML，并把它绑定到任何xml有效类型的值。
  192.     ReadXML(xmlObject interface{}) error
  193.     // ReadForm 是用表单数据绑定 formObject，支持任何类型的结构体。
  194.     ReadForm(formObject interface{}) error
  196.     //  +------------------------------------------------------------+
  197.     //  | Body (raw) Writers                                         |
  198.     //  +------------------------------------------------------------+
  200.     // Write 将数据作为一个HTTP响应的一部分写入连接。
  201.     // 
  202.     // 如果 WriteHeader 还没有调用，Write 将在 写入数据之前调用 WriteHeader(http.StatusOK)。
  203.     // 如果 Header 没有 Content-Type，Write 添加一个 Content-Type，设置为写入数据的前
  204.     // 512 字节的类型。
  205.     //
  206.     // 取决于 HTTP 版本和客户端，调用 Write 或者 WriteHeader 可能组织以后读取 Request.Body。
  207.     // 对于 HTTP/1.x 请求，处理方法应该在写入响应之前读取所有必要的请求体数据。一旦 HTTP 头被清掉
  208.     // (显示调用 Flusher.Flush 或者写入了足够的数据触发了清空操作)，请求体可能变得不可用。
  209.     // 对于 HTTP/2 请求，Go HTTP 服务器允许在写入响应的同时读取请求体。然而，这种行为可能不被所有
  210.     // HTTP/2 客户端支持。处理方法应该尽可能读取最大量的数据在写入之前。
  211.     Write(body []byte) (int, error)
  212.     // Writef 根据格式声明器格式化，然后写入响应。
  213.     //
  214.     // 返回写入的字节数量以及任何写入错误。
  215.     Writef(format string, args ...interface{}) (int, error)
  216.     // WriteString 将一个简单的字符串写入响应。
  217.     //
  218.     // 返回写入的字节数量以及任何写入错误。
  219.     WriteString(body string) (int, error)
  220.     // WriteWithExpiration 很像 Write，但是它发送了一个失效时间，它会被每个包级别的
  221.     // `StaticCacheDuration` 字段刷新。
  222.     WriteWithExpiration(body []byte, modtime time.Time) (int, error)
  223.     // StreamWriter 注册给定的流用于发布响应体。
  224.     //
  225.     // 这个函数可能被用于一下这些情况：
  226.     // 
  227.     //     * 如果响应体太大（超过了iris.LimitRequestBodySize）
  228.     //     * 如果响应体是慢慢从外部资源流入
  229.     //     * 如果响应体必须分片流向客户端（例如 `http server push`）
  230.     StreamWriter(writer func(w io.Writer) bool)
  232.     //  +------------------------------------------------------------+
  233.     //  | 带压缩的 Body Writers                            |
  234.     //  +------------------------------------------------------------+
  235.     // 如果客户端支持 gzip 压缩，ClientSupportsGzip 返回 true。
  236.     ClientSupportsGzip() bool
  237.     // WriteGzip accepts bytes, which are compressed to gzip format and sent to the client.
  238.     // WriteGzip 接受压缩成 gzip 格式的字节然后发送给客户端，并返回写入的字节数量和错误（如果错误不支持 gzip 格式）
  239.     //
  240.     // 这个函数写入临时的 gzip 内容，ResponseWriter 不会改变。
  241.     WriteGzip(b []byte) (int, error)
  242.     // TryWriteGzip 接受 gzip 格式压缩的字节，然后发送给客户端。
  243.     // 如果客户端不支持 gzip，就按照他们原来未压缩的样子写入。
  244.     //
  245.     // 这个函数写入临时的 gzip 内容，ResponseWriter 不会改变。
  246.     TryWriteGzip(b []byte) (int, error)
  247.     // GzipResponseWriter converts the current response writer into a response writer
  248.     // GzipResponseWriter 将当前的响应 writer 转化为一个 gzip 响应 writer。
  249.     // 当它的 .Write 方法被调用的时候，数据被压缩成 gzip 格式然后把他们写入客户端。
  250.     //
  251.     // 也可以使用 .Disable 禁用以及使用 .ResetBody 回滚到常规的响应写入器。
  252.     GzipResponseWriter() *GzipResponseWriter
  253.     // Gzip 开启或者禁用 gzip 响应写入器，如果客户端支持 gzip 压缩，所以接下来的响应数据将被作为
  254.     // 压缩的 gzip 数据发送给客户端。
  255.     Gzip(enable bool)
  257.     //  +------------------------------------------------------------+
  258.     //  | 富文本内容渲染器                                              |
  259.     //  +------------------------------------------------------------+
  261.     // ViewLayout 设置 「布局」选项，如果随后在相同的请求中 .View 被调用。
  262.     // 当需要去改变或者设置处理链中前一个方法的布局时很有用。
  263.     // 
  264.     // 注意 'layoutTmplFile' 参数可以被设置为 iris.NoLayout 或者 view.NoLayout 去禁用某个试图渲染动作的布局。
  265.     // 它禁用了配置项的布局属性。
  266.     //
  267.     // 也可查看 .ViewData 和 .View。
  268.     // 
  269.     // 示例：https://github.com/kataras/iris/tree/master/_examples/view/context-view-data/
  270.     ViewLayout(layoutTmplFile string)
  272.     // ViewData 保存一个或者多个键值对为了在后续的 .View 被调用的时候使用。
  273.     // 当需要处理链中前一个处理器的模板数据的时候是很有用的。
  274.     //
  275.     // 如果 .View 的绑定参数不是 nil 也不是 map 类型，这些数据就会被忽略，绑定是有优先级的，所以住路由的处理方法仍然有效。
  276.     // 如果绑定是一个map或者context.Map，这些数据然后就被添加到视图数据然后传递给模板。
  277.     //
  278.     // .View 调用之后，这些数据不会被丢掉，为了在必要的时候重用（再次声明，同一个请求中），为了清除这些数据，开发者可以调用
  279.     // ctx.Set(ctx.Application().ConfigurationReadOnly().GetViewDataContextKey(), nil)。
  280.     // 
  281.     // 如果 'key' 是空的，然后 值被作为它的（struct 或者 map）添加，并且开发者不能添加其他值。
  282.     //
  283.     // 推荐查看 .ViewLayout 和 .View。
  284.     //
  285.     // 示例：https://github.com/kataras/iris/tree/master/_examples/view/context-view-data/
  286.     ViewData(key string, value interface{})
  288.     // GetViewData 返回 `context#ViewData` 注册的值。
  289.     // 返回值是 `map[string]interface{}` 类型，这意味着如果一个自定义的结构体被添加到 ViewData， 这个函数将把它解析成
  290.     // map，如果失败返回 nil。
  291.     // 如果不同类型的值或者没有数据通过 `ViewData` 注册，检查是否为nil总是好的编程规范。
  292.     // 
  293.     // 类似于 `viewData := ctx.Values().Get("iris.viewData")` 或者 
  294.     // `viewData := ctx.Values().Get(ctx.Application().ConfigurationReadOnly().GetViewDataContextKey())`。
  295.     GetViewData() map[string]interface{}
  297.     // View 基于适配的视图引擎渲染模板。第一个参数是接受相对于视图引擎目录的文件名，
  298.     // 例如如果目录是 "./templates"，想要渲染： "./templates/users/index.html"
  299.     // 你应该传递 "users/index.html" 作为文件名参数。
  300.     // 也可以查看 .ViewData 和 .ViewLayout。
  301.     // 示例：https://github.com/kataras/iris/tree/master/_examples/view/
  302.     View(filename string) error
  304.     // Binary 将原生字节作为二进制数据返回。
  305.     Binary(data []byte) (int, error)
  306.     // Text 将字符串作为空白文本返回。
  307.     Text(text string) (int, error)
  308.     // HTML 将字符串作为 text/html 返回.
  309.     HTML(htmlContents string) (int, error)
  310.     // JSON 格式化给定的数据并且返回 json 数据。
  311.     JSON(v interface{}, options ...JSON) (int, error)
  312.     // JSONP 格式化给定的数据并且返回 json 数据。
  313.     JSONP(v interface{}, options ...JSONP) (int, error)
  314.     // XML 格式话给定数据，并返回 XML 数据。
  315.     XML(v interface{}, options ...XML) (int, error)
  316.     // Markdown 解析 markdown 数据为 HTML 返回给客户端。
  317.     Markdown(markdownB []byte, options ...Markdown) (int, error)
  319.     //  +------------------------------------------------------------+
  320.     //  | 文件响应                                                     |
  321.     //  +------------------------------------------------------------+
  323.     // ServeContent 返回的内容头是自动设置的，接受三个参数，它是一个低级的函数，你可以调用 .ServeFile(string,bool)/SendFile(string,string)。
  324.     // 这个函数调用之后，你可以定义自己的 "Content-Type" 头，不要实现 resuming，而应该使用 ctx.SendFile。
  325.     ServeContent(content io.ReadSeeker, filename string, modtime time.Time, gzipCompression bool) error
  326.     // ServeFile 渲染一个视图文件，如果要发送一个文件（例如zip文件）到客户端，你应该使用 SendFile(serverfilename,clientfilename)。
  327.     // 接受两个参数：
  328.     // filename/path (string)
  329.     // gzipCompression (bool)
  330.     // 这个函数调用之后，你可以定义自己的 "Content-Type" 头，这个函数没有实现 resuming，你应该使用 ctx.SendFile。
  331.     ServeFile(filename string, gzipCompression bool) error
  332.     // SendFile 发送强制下载的文件到客户端
  333.     // 
  334.     // 使用这个而不是 ServeFile 用于大文件下载到客户端。
  335.     SendFile(filename string, destinationName string) error
  337.     //  +------------------------------------------------------------+
  338.     //  | Cookies                                                    |
  339.     //  +------------------------------------------------------------+
  341.     // SetCookie 添加cookie
  342.     SetCookie(cookie *http.Cookie)
  343.     // SetCookieKV 添加一个 cookie，仅仅接受一个名字（字符串）和一个值（字符串）
  344.     //
  345.     // 如果你用这个方法设置cookie，它将在两小时之后失效。
  346.     // 如果你想去设置或者改变更多字段，使用 ctx.SetCookie 或者 http.SetCookie。
  347.     SetCookieKV(name, value string)
  348.     // GetCookie 通过名称返回值，如果没找到返回空字符串。
  349.     GetCookie(name string) string
  350.     // RemoveCookie 通过名字删除 cookie。
  351.     RemoveCookie(name string)
  352.     // VisitAllCookies 接受一个 visitor 循环每个cookie，visitor 接受两个参数：名称和值。
  353.     VisitAllCookies(visitor func(name string, value string))
  355.     // MaxAge 返回 "cache-control" 请求头的值，单位为：秒，类型为 int64
  356.     // 如果头没有发现或者解析失败返回 -1。
  357.     MaxAge() int64
  359.     //  +------------------------------------------------------------+
  360.     //  | 高级部分: 响应记录器和事务                                     |
  361.     //  +------------------------------------------------------------+
  363.     // Record 转化上下文基本的 responseWriter 为 ResponseRecorder，它可以被用于在任何时候重置内容体，
  364.     // 重置响应头，获取内容体，获取和设置状态码。
  365.     Record()
  366.     // Recorder 返回上下文的 ResponseRecorder，如果没有 recording 然后它将开始记录并返回新的上下文的 ResponseRecorder。
  367.     Recorder() *ResponseRecorder
  368.     // IsRecording 返回响应记录器以及一个bool值
  369.     // true 表示响应记录器正在记录状态码，内容体，HTTP 头以及更多，否则就是 false
  370.     IsRecording() (*ResponseRecorder, bool)
  372.     // BeginTransaction 开启一个有界事务。
  373.     //
  374.     // 你可以搜索第三方文章或者查看事务 Transaction 如何工作（这里相当简单特别）。
  375.     //
  376.     // 记着这个是唯一的，也是新的，目前为止，我没有在这个项目中看到任何例子和代码，就大多数 iris 功能而言。
  377.     // 它没有覆盖所有路径，例如数据库，这个应该由你使用的创建数据库连接的库管理，这个事务域仅仅用于上下文响应，
  378.     //
  379.     // 阅读 https://github.com/kataras/iris/tree/master/_examples/ 查看更多。
  380.     BeginTransaction(pipe func(t *Transaction))
  381.     // 如果调用 SkipTransactions 将跳过剩余的事务，或者如果在第一个事务之前调用，将跳过所有
  382.     SkipTransactions()
  383.     // TransactionsSkipped 返回事务到底被跳过还是被取消了。
  384.     TransactionsSkipped() bool
  386.     // Exec根据这个上下文调用framewrok的ServeCtx，但是改变了方法和路径，就像用户请求的那样，但事实并非如此。
  387.     //
  388.     // 离线意味着路线已注册到 iris 并具有正常路由所具有的所有功能。
  389.     // 但是它不能通过浏览获得，它的处理程序仅在其他处理程序的上下文调用它们时执行，它可以验证路径，拥有会话，路径参数等。
  390.     //
  391.     // 你可以通过 app.GetRoute("theRouteName") 找到路由，你可以设置一个路由名称如：
  392.     // myRoute := app.Get("/mypath", handler)("theRouteName")
  393.     // 这个将给路由设置一个名称并且返回它的 RouteInfo 实例为了进一步使用。
  394.     //
  395.     // 它不会更改全局状态，如果路由处于“脱机”状态，它将保持脱机状态。
  396.     //
  397.     // app.None(...) and app.GetRoutes().Offline(route)/.Online(route, method)
  398.     //
  399.     // 实例：https://github.com/kataras/iris/tree/master/_examples/routing/route-state
  400.     //
  401.     // 用户可以通过简单调用得到响应：rec := ctx.Recorder();     rec.Body()/rec.StatusCode()/rec.Header()
  402.     // Context 的 Values 和 Session 被记住为了能够通过结果路由通信，
  403.     // 它仅仅由于特别案例，99% 的用户不会用到的。
  404.     Exec(method string, path string)
  406.     // Application 返回 属于这个上下文的 iris 实例。
  407.     // 值得留意的是这个函数返回 Application 的一个接口，它包含的方法能够安全地在运行是执行。
  408.     // 为了开发者的安全性，整个 app 的 字段和方法这里是不可用的。
  409.     Application() Application
  410. }

动态路由参数

对于路由的路径生命语法，动态路径参数解析和计算，Iris有自己的解释器，我们简单的把它们叫作”宏”。
路由路径参数标准macor类型。

  1. +------------------------+
  2. | {param:string}         |
  3. +------------------------+
  4. string type
  5. anything
  7. +------------------------+
  8. | {param:int}            |
  9. +------------------------+
  10. int type
  11. only numbers (0-9)
  13. +------------------------+
  14. | {param:long}           |
  15. +------------------------+
  16. int64 type
  17. only numbers (0-9)
  19. +------------------------+
  20. | {param:boolean}        |
  21. +------------------------+
  22. bool type
  23. only "1" or "t" or "T" or "TRUE" or "true" or "True"
  24. or "0" or "f" or "F" or "FALSE" or "false" or "False"
  26. +------------------------+
  27. | {param:alphabetical}   |
  28. +------------------------+
  29. alphabetical/letter type
  30. letters only (upper or lowercase)
  32. +------------------------+
  33. | {param:file}           |
  34. +------------------------+
  35. file type
  36. letters (upper or lowercase)
  37. numbers (0-9)
  38. underscore (_)
  39. dash (-)
  40. point (.)
  41. no spaces ! or other character
  43. +------------------------+
  44. | {param:path}           |
  45. +------------------------+
  46. path type
  47. anything, should be the last part, more than one path segment,
  48. i.e: /path1/path2/path3 , ctx.Params().Get("param") == "/path1/path2/path3"

如果没有设置参数类型，默认就是string,所以{param}=={param:string}。
如果在该类型上找不到函数，那么string宏类型的函数将被使用。
除了iris提供的基本类型和一些默认的“宏函数”，我们也可以注册自己的。

  1. // 注册一个明明的路径参数函数。
  2. app.Macros().Get("int").RegisterFunc("min", func(minValue int) func(string) bool {
  3.     return func(paramValue string) bool{
  4.         n, err := strconv.Atoi(paramValue)
  5.         if err != nil {
  6.             return false
  7.         }
  8.         return n >= minValue
  9.     }
  10. })
  13. // 第二种写法
  15. import "github.com/kataras/iris/v12/macro"
  17. macro.Int.RegisterFunc("min", func(minValue int) func(string) bool {
  18.     return  func(paramValue string) bool {
  19.         n, err  := strconv.Atoi(paramValue)
  20.         if err !=  nil {
  21.             return  false
  22.         }
  23.         return n >= minValue
  24.     }
  25. })

示例代码：

  1. import (
  2.     "github.com/kataras/iris/v12"
  3.     "github.com/kataras/iris/v12/macro"
  4.     "strconv"
  5. )
  7. func main() {
  8.     app := iris.New()
  10.     app.Get("/username/{name}", func(ctx iris.Context) {
  11.         ctx.Writef("Hello %s",ctx.Params().Get("name"))
  12.     })
  14.     //// 注册int类型的宏函数
  15.     //// min 函数名称
  16.     //// minValue 函数参数
  17.     //// func(string) bool 宏的路径参数的求值函数，当用户请求包含 min(...)
  18.     //app.Macros().Get("int").RegisterFunc("min", func(minValue int) func(string) bool {
  19.     //    return func(paramValue string) bool{
  20.     //        n, err := strconv.Atoi(paramValue)
  21.     //        if err != nil {
  22.     //            return false
  23.     //        }
  24.     //        return n >= minValue
  25.     //    }
  26.     //})
  28.     macro.Int.RegisterFunc("min", func(minValue int) func(string) bool {
  29.         return func(paramValue string) bool {
  30.             n, err := strconv.Atoi(paramValue)
  31.             if err != nil {
  32.                 return false
  33.             }
  34.             return n >= minValue
  35.         }
  36.     })
  39.     // http://localhost:8080/profile/id>=1
  40.     // 如果路由是这样：/profile/0, /profile/blabla, /profile/-1，将抛出404错误
  41.     // 宏参数函数是可以省略的。
  42.     app.Get("/profile/{id:int min(1)}", func(ctx iris.Context) {
  43.         id, _ := ctx.Params().GetInt("id")
  44.         ctx.Writef("Hello id:%d",id)
  45.     })
  47.     // 改变路径参数错误引起的错误码
  48.     // 这将抛出504错误码,而不是404，如果所有路由宏没有通过
  49.     app.Get("/profile/{id:int min(1)}/friends/{friendid:int min(1) else 504}", func(ctx iris.Context) {
  50.         id, _ := ctx.Params().GetInt("id")
  51.         friendid, _ := ctx.Params().GetInt("friendid")
  52.         ctx.Writef("Hello id:%d looking for friend id:%d",id,friendid)
  53.     })
  56.     // http://localhostL8080/game/a-zA-Z/level/0-9
  57.     // 记着 alphabetical仅仅允许大小写字母
  58.     app.Get("/game/{name:alphabetical}/level/{level:int}", func(ctx iris.Context) {
  59.         ctx.Writef("name:%s | level:%s",ctx.Params().Get("name"),ctx.Params().Get("level"))
  60.     })
  63.     // 用一个简单的自定义正则表达式来雁阵一个路径参数仅仅是小写字母
  64.     // http://localhost:8080/lowercase/anylowercase
  65.     app.Get("/lowercase/{name:string regexp(^[a-z]+)}", func(ctx iris.Context) {
  66.         ctx.Writef("name should be only lowercase,otherwise this handler will never executed:%s",ctx.Params().Get("name"))
  67.     })
  69.     app.Run(iris.Addr(":8080"))
  70. }

一个路径参数名称应该只包含小写字母，像_和数字这样的符号是不允许的。
路径参数值获取通过ctx.Params()，上下文中用于处理器之间通信的局部存储和中间件使用ctx.Value()。

路由中间件

中间件

当我们在 iris 中讨论中间件的时候，我们就是在讨论运行一个 HTTP 请求处理器前后的代码。例如，日志中间件会把即将到来的请求明细写到日志中，然后在写响应日志详细之前，调用处理期代码。比较酷的是这些中间件是松耦合，而且可重用。
中间件仅仅是 func(ctx iris.Context) 的处理器形式，中间件在前一个调用 ctx.Next() 时执行，这个可以用于去认证，例如，如果登录了，调用 ctx.Next() 否则将触发一个错误响应。

中间件开发

  1. package main
  3. import "github.com/kataras/iris/v12"
  5. func main() {
  6.     app := iris.New()
  7.     app.Get("/",before,mainHandler,after)
  8.     app.Run(iris.Addr(":8080"))
  9. }
  12. func before(ctx iris.Context){
  13.     shareInformation := "this is a sharable information between handlers"
  15.     requestPath := ctx.Path()
  17.     println("Before the mainHandler:"+requestPath)
  19.     ctx.Values().Set("info",shareInformation)
  20.     ctx.Next()  // 执行下一个处理器
  21. }
  24. func after(ctx iris.Context){
  25.     println("After the mainHandler")
  26. }
  28. func mainHandler(ctx iris.Context){
  29.     println("Inside mainHandler")
  31.     // 获取“before”处理器中设置的“info”值
  32.     info := ctx.Values().GetString("info")
  34.     // 响应客户端
  35.     ctx.HTML("<h1>Response</h1>")
  36.     ctx.HTML("<br/>Info:"+ info)
  38.     ctx.Next()
  39. }
  1. Now listening on: http://localhost:8080
  2. Application started. Press CTRL+C to shut down.
  3. Before the mainHandler:/
  4. Inside mainHandler
  5. After the mainHandler

全局

  1. func before(ctx iris.Context){
  2.     shareInformation := "this is a sharable information between handlers"
  4.     requestPath := ctx.Path()
  6.     println("Before the mainHandler:"+requestPath)
  8.     ctx.Values().Set("info",shareInformation)
  9.     ctx.Next()  // 执行下一个处理器
  10. }
  13. func after(ctx iris.Context){
  14.     println("After the mainHandler")
  15. }
  17. func indexHandler(ctx iris.Context){
  18.     println("Inside mainHandler")
  20.     // 获取“before”处理器中设置的“info”值
  21.     info := ctx.Values().GetString("info")
  23.     // 响应客户端
  24.     ctx.HTML("<h1>Index</h1>")
  25.     ctx.HTML("<br/>Info:"+ info)
  27.     ctx.Next()  // 执行通过"Done"注册的"after"处理器
  28. }
  31. func contactHandler(ctx iris.Context){
  32.     info := ctx.Values().GetString("info")
  34.     // 响应客户端
  35.     ctx.HTML("<h1>Contact</h1>")
  36.     ctx.HTML("<br/>Info:"+info)
  37. }
  39. func main() {
  40.     app := iris.New()
  42.     // 注册“before”处理器作为当前域名所有路由中第一个处理函数
  43.     app.Use(before)
  44.     // 或者使用"UserGlobal"去注册一个中间件，用于在所有子域名中使用
  45.     // app.UseGlobal(before)
  47.     // 注册“after”，在所有路由处理程序之后调用
  48.     app.Done(after)
  50.     // 注册路由
  51.     app.Get("/",indexHandler)
  52.     app.Get("/contact",contactHandler)
  54.     app.Run(iris.Addr(":8080"))
  55. }

JWT

  1. package main
  3. import (
  4.     "github.com/iris-contrib/middleware/jwt"
  5.     "github.com/kataras/iris/v12"
  6.     "time"
  7. )
  10. var mySecret = []byte("secret")  // 定义秘钥
  12. var j = jwt.New(jwt.Config{
  13.     // 设置一个函数返回秘钥，关键在于return mySecret
  14.     ValidationKeyGetter: func(token *jwt.Token) (interface{}, error) {
  15.         return mySecret,nil
  16.     },
  17.     Expiration:true,  // 是否过期
  18.     Extractor: jwt.FromParameter("token"),  // 从请求参数token中获取
  19.     SigningMethod:jwt.SigningMethodHS256, // 设置加密方法
  20. })
  22. // 生成令牌
  23. func getTokenHandler(ctx iris.Context){
  24.     now := time.Now()
  25.     token := jwt.NewTokenWithClaims(jwt.SigningMethodHS256,jwt.MapClaims{
  26.         "foo":"bar",
  27.         "iat":now.Unix(),  // 签发时间
  28.         "exp":now.Add(15*time.Minute).Unix(), // 过期时间
  29.     })
  31.     // 生成完整的秘钥
  32.     tokenString,_ := token.SignedString(mySecret)
  33.     ctx.Writef("jwt=%s",tokenString)
  34. }
  36. // 验证
  37. func myAuthenticatedHandler(ctx iris.Context){
  38.     // 验证，验证不通过直接返回
  39.     if err := j.CheckJWT(ctx);err != nil {
  40.         j.Config.ErrorHandler(ctx, err)
  41.         return
  42.     }
  44.     token := ctx.Values().Get("jwt").(*jwt.Token)
  45.     ctx.Writef("This is an authenticated request\n\n")
  47.     foobar := token.Claims.(jwt.MapClaims)
  48.     ctx.Writef("foo=%s\n",foobar["foo"])
  49. }
  51. func main() {
  52.     app := iris.New()
  53.     app.Get("/",getTokenHandler)
  54.     app.Get("/protected",myAuthenticatedHandler)
  56.     app.Listen(":8080")
  57. }

错误处理

当程序产生了一个特定的 http 错误的时候，你可以定义你自己的错误处理代码。
错误代码是大于或者等于 400 的 http 状态码，像 404 not found 或者 500 服务器内部错误。
示例代码：

  1. package main
  3. import "github.com/kataras/iris/v12"
  5. func main() {
  6.     app := iris.New()
  7.     app.OnErrorCode(iris.StatusNotFound,notFound)
  8.     app.OnErrorCode(iris.StatusInternalServerError,internalServerError)
  10.     app.Get("/",index)
  11.     app.Run(iris.Addr(":8080"))
  12. }
  15. func notFound(ctx iris.Context){
  16.     // 出现404的时候，就跳转到views/errors/404.html模板
  17.     ctx.View("./views/errors/404.html")
  18. }
  20. func internalServerError(ctx iris.Context){
  21.     ctx.WriteString("Oups something went wrong,try again")
  22. }
  24. func index(ctx iris.Context){
  25.     ctx.View("index.html")
  26. }

Session

Overview

  1. import "github.com/kataras/iris/v12/sessions"
  3. sess := sessions.Start(http.ResponseWriter, *http.Request)
  4. sess.
  5.   ID() string
  6.   Get(string) interface{}
  7.   HasFlash() bool
  8.   GetFlash(string) interface{}
  9.   GetFlashString(string) string
  10.   GetString(key string) string
  11.   GetInt(key string) (int, error)
  12.   GetInt64(key string) (int64, error)
  13.   GetFloat32(key string) (float32, error)
  14.   GetFloat64(key string) (float64, error)
  15.   GetBoolean(key string) (bool, error)
  16.   GetAll() map[string]interface{}
  17.   GetFlashes() map[string]interface{}
  18.   VisitAll(cb func(k string, v interface{}))
  19.   Set(string, interface{})
  20.   SetImmutable(key string, value interface{})
  21.   SetFlash(string, interface{})
  22.   Delete(string)
  23.   Clear()
  24.   ClearFlashes()

示例代码：

  1. package main
  3. import (
  4.     "github.com/kataras/iris/v12"
  5.     "github.com/kataras/iris/v12/sessions"
  7. )
  9. var (
  10.     cookieNameForSessionId = "mycookiessionnameid"
  11.     sess = sessions.New(sessions.Config{
  12.         Cookie: cookieNameForSessionId,
  13.     })
  14. )
  16. func secret(ctx iris.Context){
  17.     // 检查用户是否已通过身份验证
  18.     p := sess.Start(ctx).Get("authenticated")
  19.     println(p)
  20.     if auth, _ := sess.Start(ctx).GetBoolean("authenticated");!auth{
  21.         ctx.StatusCode(iris.StatusForbidden)
  22.         return
  23.     }
  24.     // 打印
  25.     ctx.WriteString("The cake is a lie!")
  26. }
  29. func login(ctx iris.Context){
  30.     session := sess.Start(ctx)
  31.     // 在此进行身份验证
  32.     // ...
  34.     // 将用户设置为已验证
  35.     session.Set("authenticated",true)
  36.     ctx.WriteString("登录成功")
  37. }
  39. func logout(ctx iris.Context){
  40.     session := sess.Start(ctx)
  42.     // 撤销身份认证
  43.     session.Set("authenticated",false)
  44. }
  47. func main() {
  48.     app := iris.New()
  49.     app.Get("/secret",secret)
  50.     app.Get("/login",login)
  51.     app.Get("/logout",logout)
  53.     app.Run(iris.Addr(":8080"))
  54. }