安装

Iris是一个跨平台软件。
唯一的要求是Go编程语言，版本1.14及以上。

$ mkdir myapp
$ go mod init myapp
$ go get github.com/kataras/iris/v12@master

导入它在您的代码:

import "github.com/kataras/iris/v12"

疑问解答

如果您在安装期间出现网络错误，请确保您设置了一个有效的GOPROXY环境变量。

go env -w GOPROXY=https://goproxy.cn,https://gocenter.io,https://goproxy.io,direct

快速开始

# assume the following codes in main.go file
$ cat main.go

package main
import "github.com/kataras/iris/v12"
func main() {
    app := iris.New()
    booksAPI := app.Party("/books")
    {
        booksAPI.Use(iris.Compression)
        // GET: http://localhost:8080/books
        booksAPI.Get("/", list)
        // POST: http://localhost:8080/books
        booksAPI.Post("/", create)
    }
    app.Listen(":8080")
}
// Book example.
type Book struct {
    Title string `json:"title"`
}
func list(ctx iris.Context) {
    books := []Book{
        {"Mastering Concurrency in Go"},
        {"Go Design Patterns"},
        {"Black Hat Go"},
    }
    ctx.JSON(books)
    // TIP: negotiate the response between server's prioritizes
    // and client's requirements, instead of ctx.JSON:
    // ctx.Negotiation().JSON().MsgPack().Protobuf()
    // ctx.Negotiate(books)
}
func create(ctx iris.Context) {
    var b Book
    err := ctx.ReadJSON(&b)
    // TIP: use ctx.ReadBody(&b) to bind
    // any type of incoming data instead.
    if err != nil {
        ctx.StopWithProblem(iris.StatusBadRequest, iris.NewProblem().
            Title("Book creation failure").DetailErr(err))
        // TIP: use ctx.StopWithError(code, err) when only
        // plain text responses are expected on errors.
        return
    }
    println("Received Book: " + b.Title)
    ctx.StatusCode(iris.StatusCreated)
}

MVC

import "github.com/kataras/iris/v12/mvc"

m := mvc.New(booksAPI)
m.Handle(new(BookController))

type BookController struct {
    /* dependencies */
}
// GET: http://localhost:8080/books
func (c *BookController) Get() []Book {
    return []Book{
        {"Mastering Concurrency in Go"},
        {"Go Design Patterns"},
        {"Black Hat Go"},
    }
}
// POST: http://localhost:8080/books
func (c *BookController) Post(b Book) int {
    println("Received Book: " + b.Title)
    return iris.StatusCreated
}

运行你的iris Web服务：

$ go run main.go
> Now listening on: http://localhost:8080
> Application started. Press CTRL+C to shut down.

Books 列表

$ curl --header 'Accept-Encoding:gzip' http://localhost:8080/books
[
  {
    "title": "Mastering Concurrency in Go"
  },
  {
    "title": "Go Design Patterns"
  },
  {
    "title": "Black Hat Go"
  }
]

创建一个新的Book

$ curl -i -X POST \
--header 'Content-Encoding:gzip' \
--header 'Content-Type:application/json' \
--data "{\"title\":\"Writing An Interpreter In Go\"}" \
http://localhost:8080/books
> HTTP/1.1 201 Created

错误相应

$ curl -X POST --data "{\"title\" \"not valid one\"}" \
http://localhost:8080/books
> HTTP/1.1 400 Bad Request
{
  "status": 400,
  "title": "Book creation failure"
  "detail": "invalid character '\"' after object key",
}

基准测试

Iris使用了一个定制版本的muxie。
See all benchmarks
动态参数的int 200000个请求,发送JSON请求主体和接收JSON响应。

Api 例子

您可以在Iris示例库中找到许多准备运行的示例。

GET,POST,PUT,PATCH,DELETE and OPTIONS

func main() {
    // Creates an iris application with default middleware:
    // Default with "debug" Logger Level.
    // Localization enabled on "./locales" directory
    // and HTML templates on "./views" or "./templates" directory.
    // It runs with the AccessLog on "./access.log",
    // Recovery (crash-free) and Request ID middleware already attached.
    app := iris.Default()
    app.Get("/someGet", getting)
    app.Post("/somePost", posting)
    app.Put("/somePut", putting)
    app.Delete("/someDelete", deleting)
    app.Patch("/somePatch", patching)
    app.Header("/someHead", head)
    app.Options("/someOptions", options)
    app.Listen(":8080")
}

路径参数

func main() {
    app := iris.Default()
    // This handler will match /user/john but will not match /user/ or /user
    app.Get("/user/{name}", func(ctx iris.Context) {
        name := ctx.Params().Get("name")
        ctx.Writef("Hello %s", name)
    })
    // However, this one will match /user/john/ and also /user/john/send
    // If no other routers match /user/john, it will redirect to /user/john/
    app.Get("/user/{name}/{action:path}", func(ctx iris.Context) {
        name := ctx.Params().Get("name")
        action := ctx.Params().Get("action")
        message := name + " is " + action
        ctx.WriteString(message)
    })
    // For each matched request Context will hold the route definition
    app.Post("/user/{name:string}/{action:path}", func(ctx iris.Context) {
        ctx.GetCurrentRoute().Tmpl().Src == "/user/{name:string}/{action:path}" // true
    })
    app.Listen(":8080")
}

内置可用参数类型:

More examples can be found at: _examples/routing.

查询字符串参数

func main() {
    app := iris.Default()
    // Query string parameters are parsed using the existing underlying request object.
    // The request responds to a url matching:  /welcome?firstname=Jane&lastname=Doe
    app.Get("/welcome", func(ctx iris.Context) {
        firstname := ctx.URLParamDefault("firstname", "Guest")
        lastname := ctx.URLParam("lastname") // shortcut for ctx.Request().URL.Query().Get("lastname")
        ctx.Writef("Hello %s %s", firstname, lastname)
    })
    app.Listen(":8080")
}

表单 Multipart/Urlencoded

func main() {
    app := iris.Default()
    app.Post("/form_post", func(ctx iris.Context) {
        message := ctx.PostValue("message")
        nick := ctx.PostValueDefault("nick", "anonymous")
        ctx.JSON(iris.Map{
            "status":  "posted",
            "message": message,
            "nick":    nick,
        })
    })
    app.Listen(":8080")
}

另一个例子:查询+发布表单

POST /post?id=1234&page=1 HTTP/1.1
Content-Type: application/x-www-form-urlencoded
name=kataras&message=this_is_great

func main() {
    app := iris.Default()
    app.Post("/post", func(ctx iris.Context) {
        id, err := ctx.URLParamInt("id", 0)
        if err != nil {
            ctx.StopWithError(iris.StatusBadRequest, err)
            return
        }
        page := ctx.URLParamIntDefault("page", 0)
        name := ctx.PostValue("name")
        message := ctx.PostValue("message")
        ctx.Writef("id: %d; page: %d; name: %s; message: %s", id, page, name, message)
    })
    app.Listen(":8080")
}

id: 1234; page: 1; name: kataras; message: this_is_great

查询和发布表单参数

POST /post?id=a&id=b&id=c&name=john&name=doe&name=kataras
Content-Type: application/x-www-form-urlencoded

func main() {
    app := iris.Default()
    app.Post("/post", func(ctx iris.Context) {
        ids := ctx.URLParamSlice("id")
        names, err := ctx.PostValues("name")
        if err != nil {
            ctx.StopWithError(iris.StatusBadRequest, err)
            return
        }
        ctx.Writef("ids: %v; names: %v", ids, names)
    })
    app.Listen(":8080")
}

ids: [a b c], names: [john doe kataras]

上传文件

单个文件

const maxSize = 8 * iris.MB
func main() {
    app := iris.Default()
    app.Post("/upload", func(ctx iris.Context) {
        // Set a lower memory limit for multipart forms (default is 32 MiB)
        ctx.SetMaxRequestBodySize(maxSize)
        // OR
        // app.Use(iris.LimitRequestBodySize(maxSize))
        // OR
        // OR iris.WithPostMaxMemory(maxSize)
        // single file
        file, _, err:= ctx.FormFile("file")
        if err != nil {
            ctx.StopWithError(iris.StatusBadRequest, err)
            return
        }
        // Upload the file to specific destination.
        dest := filepath.Join("./uploads", file.Filename)
        ctx.SaveFormFile(file, dest)
        ctx.Writef("File: %s uploaded!", file.Filename)
    })
    app.Listen(":8080")
}

如何curl：

curl -X POST http://localhost:8080/upload \
  -F "file=@/Users/kataras/test.zip" \
  -H "Content-Type: multipart/form-data"

多文件上传

查看示例代码细节

func main() {
    app := iris.Default()
    app.Post("/upload", func(ctx iris.Context) {
        files, n, err := ctx.UploadFormFiles("./uploads")
        if err != nil {
            ctx.StopWithStatus(iris.StatusInternalServerError)
            return
        }
        ctx.Writef("%d files of %d total size uploaded!", len(files), n))
    })
    app.Listen(":8080", iris.WithPostMaxMemory(8 * iris.MB))
}

如何curl：

curl -X POST http://localhost:8080/upload \
  -F "upload[]=@/Users/kataras/test1.zip" \
  -F "upload[]=@/Users/kataras/test2.zip" \
  -H "Content-Type: multipart/form-data"

路由组

func main() {
    app := iris.Default()
    // Simple group: v1
    v1 := app.Party("/v1")
    {
        v1.Post("/login", loginEndpoint)
        v1.Post("/submit", submitEndpoint)
        v1.Post("/read", readEndpoint)
    }
    // Simple group: v2
    v2 := app.Party("/v2")
    {
        v2.Post("/login", loginEndpoint)
        v2.Post("/submit", submitEndpoint)
        v2.Post("/read", readEndpoint)
    }
    app.Listen(":8080")
}

默认情况下没有中间件

使用

app := iris.New()

代替

// Default with "debug" Logger Level.
// Localization enabled on "./locales" directory
// and HTML templates on "./views" or "./templates" directory.
// It runs with the AccessLog on "./access.log",
// Recovery and Request ID middleware already attached.
app := iris.Default()

使用中间件

package main
import (
    "github.com/kataras/iris/v12"
    "github.com/kataras/iris/v12/middleware/logger"
    "github.com/kataras/iris/v12/middleware/recover"
)
func main() {
    // Creates an iris application without any middleware by default
    app := iris.New()
    // Global middleware using `UseRouter`.
    //
    // Recovery middleware recovers from any panics and writes a 500 if there was one.
    app.UseRouter(recover.New())
    // Logger middleware by-default will write the logs using app.Logger().Infof.
    app.UseRouter(logger.New())
    // Per route middleware, you can add as many as you desire.
    app.Get("/benchmark", MyBenchLogger(), benchEndpoint)
    // Authorization group
    // authorized := app.Party("/", AuthRequired())
    // exactly the same as:
    authorized := app.Party("/")
    // per group middleware! in this case we use the custom created
    // AuthRequired() middleware just in the "authorized" group.
    authorized.Use(AuthRequired())
    {
        authorized.Post("/login", loginEndpoint)
        authorized.Post("/submit", submitEndpoint)
        authorized.Post("/read", readEndpoint)
        // nested group
        testing := authorized.Party("testing")
        testing.Get("/analytics", analyticsEndpoint)
    }
    // Listen and serve on 0.0.0.0:8080
    app.Listen(":8080")
}

如何写日志文件

func main() {
    app := iris.Default()
    // Logging to a file.
    // Colors are automatically disabled when writing to a file.
    f, _ := os.Create("iris.log")
    app.Logger().SetOutput(f)
    // Use the following code if you need to write the logs
    // to file and console at the same time.
    // app.Logger().AddOutput(os.Stdout)
    app.Get("/ping", func(ctx iris.Context) {
        ctx.WriteString("pong")
    })
   app.Listen(":8080")
}

自定义请求日志

搜索access.log功能代替?详细的例子可以在这里找到。

// LogFunc field.
func customLogFunc(endTime time.Time,
  latency time.Duration,
  status, ip, method, path string,
  message, headerMessage interface{}) {
    // [...]
}

// LogFuncCtx field.
func customLogFuncWithContext(ctx iris.Context, latency time.Duration) {
    // [...]
}

import "github.com/kataras/iris/v12/middleware/logger"
func main() {
    app := iris.New()
    reqLogger := logger.New(logger.Config{
        Status:           true,
        IP:               true,
        Method:           true,
        Path:             true,
        PathAfterHandler: false,
        Query:            false,
        TraceRoute:       true,
        Columns:          false,
        LogFunc:          customLogFunc,
        LogFuncCtx:       nil,
        Skippers:         nil,
    })
    app.UseRouter(reqLogger)
    app.Get("/ping", func(ctx iris.Context) {
        ctx.WriteString("pong")
    })
    app.Listen(":8080")
}

控制日志输入颜色

默认情况下，控制台上的日志输出应该根据检测到的TTY着色。
自定义级别标题，文本，颜色和样式。
Import golog and pio:

import (
    "github.com/kataras/golog"
    "github.com/kataras/pio"
    // [...]
)

自定义一个级别，例如DebugLevel:

level := golog.Levels[golog.DebugLevel]

你可以完全控制他的文本，标题和风格:

// The Name of the Level
// that named (lowercased) will be used
// to convert a string level on `SetLevel`
// to the correct Level type.
Name string
// AlternativeNames are the names that can be referred to this specific log level.
// i.e Name = "warn"
// AlternativeNames = []string{"warning"}, it's an optional field,
// therefore we keep Name as a simple string and created this new field.
AlternativeNames []string
// Tha Title is the prefix of the log level.
// See `ColorCode` and `Style` too.
// Both `ColorCode` and `Style` should be respected across writers.
Title string
// ColorCode a color for the `Title`.
ColorCode int
// Style one or more rich options for the `Title`.
Style []pio.RichOption

示例代码：

level := golog.Levels[golog.DebugLevel]
level.Name = "debug" // default
level.Title = "[DBUG]" // default
level.ColorCode = pio.Yellow // default

更改格式化输出：

app.Logger().SetFormat("json", "    ")

注册自定义格式化程序：

app.Logger().RegisterFormatter(new(myFormatter))

golog.Formatter interface 看起来像这样：

// Formatter is responsible to print a log to the logger's writer.
type Formatter interface {
    // The name of the formatter.
    String() string
    // Set any options and return a clone,
    // generic. See `Logger.SetFormat`.
    Options(opts ...interface{}) Formatter
    // Writes the "log" to "dest" logger.
    Format(dest io.Writer, log *Log) bool
}

改变输出和格式每层:

app.Logger().SetLevelOutput("error", os.Stderr)
app.Logger().SetLevelFormat("json")

Model绑定和验证

要将请求主体绑定到类型中，请使用模型绑定。我们目前支持JSON绑定，JSONProtobuf, Protobuf, MsgPack, XML, YAML and standard form values (foo=bar&boo=baz).

ReadJSON(outPtr interface{}) error
ReadJSONProtobuf(ptr proto.Message, opts ...ProtoUnmarshalOptions) error
ReadProtobuf(ptr proto.Message) error
ReadMsgPack(ptr interface{}) error
ReadXML(outPtr interface{}) error
ReadYAML(outPtr interface{}) error
ReadForm(formObject interface{}) error
ReadQuery(ptr interface{}) error

在使用读取体时，Iris尝试根据内容类型标题推断绑定器。如果确定要绑定的是什么，可以使用特定的ReadXXX方法，例如ReadJSON或ReadProtobuf和e.t.c。

ReadBody(ptr interface{}) error

明智的是，Iris不提供内置数据验证。但是，它允许你附加一个验证器，自动调用方法，如ReadJSON, ReadXML…在这个示例中，我们将学习如何使用go-playground/validator/v10进行请求体验证。

注意，您需要在所有想要绑定的字段上设置相应的绑定标记。例如，当从JSON绑定时，设置JSON:“fieldname”。

您还可以指定所需的特定字段。如果一个字段用binding:”required”修饰，并且在绑定时有一个空值，那么将返回一个错误。

package main
import (
    "fmt"
    "github.com/kataras/iris/v12"
    "github.com/go-playground/validator/v10"
)
func main() {
    app := iris.New()
    app.Validator = validator.New()
    userRouter := app.Party("/user")
    {
        userRouter.Get("/validation-errors", resolveErrorsDocumentation)
        userRouter.Post("/", postUser)
    }
    app.Listen(":8080")
}
// User contains user information.
type User struct {
    FirstName      string     `json:"fname" validate:"required"`
    LastName       string     `json:"lname" validate:"required"`
    Age            uint8      `json:"age" validate:"gte=0,lte=130"`
    Email          string     `json:"email" validate:"required,email"`
    FavouriteColor string     `json:"favColor" validate:"hexcolor|rgb|rgba"`
    Addresses      []*Address `json:"addresses" validate:"required,dive,required"`
}
// Address houses a users address information.
type Address struct {
    Street string `json:"street" validate:"required"`
    City   string `json:"city" validate:"required"`
    Planet string `json:"planet" validate:"required"`
    Phone  string `json:"phone" validate:"required"`
}
type validationError struct {
    ActualTag string `json:"tag"`
    Namespace string `json:"namespace"`
    Kind      string `json:"kind"`
    Type      string `json:"type"`
    Value     string `json:"value"`
    Param     string `json:"param"`
}
func wrapValidationErrors(errs validator.ValidationErrors) []validationError {
    validationErrors := make([]validationError, 0, len(errs))
    for _, validationErr := range errs {
        validationErrors = append(validationErrors, validationError{
            ActualTag: validationErr.ActualTag(),
            Namespace: validationErr.Namespace(),
            Kind:      validationErr.Kind().String(),
            Type:      validationErr.Type().String(),
            Value:     fmt.Sprintf("%v", validationErr.Value()),
            Param:     validationErr.Param(),
        })
    }
    return validationErrors
}
func postUser(ctx iris.Context) {
    var user User
    err := ctx.ReadJSON(&user)
    if err != nil {
        // Handle the error, below you will find the right way to do that...
        if errs, ok := err.(validator.ValidationErrors); ok {
            // Wrap the errors with JSON format, the underline library returns the errors as interface.
            validationErrors := wrapValidationErrors(errs)
            // Fire an application/json+problem response and stop the handlers chain.
            ctx.StopWithProblem(iris.StatusBadRequest, iris.NewProblem().
                Title("Validation error").
                Detail("One or more fields failed to be validated").
                Type("/user/validation-errors").
                Key("errors", validationErrors))
            return
        }
        // It's probably an internal JSON error, let's dont give more info here.
        ctx.StopWithStatus(iris.StatusInternalServerError)
        return
    }
    ctx.JSON(iris.Map{"message": "OK"})
}
func resolveErrorsDocumentation(ctx iris.Context) {
    ctx.WriteString("A page that should document to web developers or users of the API on how to resolve the validation errors")
}

简单请求

{
    "fname": "",
    "lname": "",
    "age": 45,
    "email": "mail@example.com",
    "favColor": "#000",
    "addresses": [{
        "street": "Eavesdown Docks",
        "planet": "Persphone",
        "phone": "none",
        "city": "Unknown"
    }]
}

简单响应

{
    "title": "Validation error",
    "detail": "One or more fields failed to be validated",
    "type": "http://localhost:8080/user/validation-errors",
    "status": 400,
    "fields": [
    {
        "tag": "required",
        "namespace": "User.FirstName",
        "kind": "string",
        "type": "string",
        "value": "",
        "param": ""
    },
    {
        "tag": "required",
        "namespace": "User.LastName",
        "kind": "string",
        "type": "string",
        "value": "",
        "param": ""
    }
    ]
}

了解更多关于模型验证的信息:https://github.com/go-playground/validator/blob/master/_examples

绑定查询字符串

ReadQuery方法只绑定查询参数而不是post数据，使用ReadForm来绑定post数据。

package main
import "github.com/kataras/iris/v12"
type Person struct {
    Name    string `url:"name,required"`
    Address string `url:"address"`
}
func main() {
    app := iris.Default()
    app.Any("/", index)
    app.Listen(":8080")
}
func index(ctx iris.Context) {
    var person Person
    if err := ctx.ReadQuery(&person); err!=nil {
        ctx.StopWithError(iris.StatusBadRequest, err)
        return
    }
    ctx.Application().Logger().Infof("Person: %#+v", person)
    ctx.WriteString("Success")
}

绑定任何

根据客户端发送数据的内容类型，如JSON、XML、YAML、MessagePack、Protobuf、Form和URL查询，将请求体绑定到“ptr”。

package main
import (
    "time"
    "github.com/kataras/iris/v12"
)
type Person struct {
        Name       string    `form:"name" json:"name" url:"name" msgpack:"name"` 
        Address    string    `form:"address" json:"address" url:"address" msgpack:"address"`
        Birthday   time.Time `form:"birthday" time_format:"2006-01-02" time_utc:"1" json:"birthday" url:"birthday" msgpack:"birthday"`
        CreateTime time.Time `form:"createTime" time_format:"unixNano" json:"create_time" url:"create_time" msgpack:"createTime"`
        UnixTime   time.Time `form:"unixTime" time_format:"unix" json:"unix_time" url:"unix_time" msgpack:"unixTime"`
}
func main() {
    app := iris.Default()
    app.Any("/", index)
    app.Listen(":8080")
}
func index(ctx iris.Context) {
    var person Person
    if err := ctx.ReadBody(&person); err!=nil {
        ctx.StopWithError(iris.StatusBadRequest, err)
        return
    }
    ctx.Application().Logger().Infof("Person: %#+v", person)
    ctx.WriteString("Success")
}

测试：

$ curl -X GET "localhost:8085/testing?name=kataras&address=xyz&birthday=1992-03-15&createTime=1562400033000000123&unixTime=1562400033"

绑定url路径参数

package main
import "github.com/kataras/iris/v12"
type myParams struct {
    Name string   `param:"name"`
    Age  int      `param:"age"`
    Tail []string `param:"tail"`
}
// All parameters are required, as we already know,
// the router will fire 404 if name or int or tail are missing.
func main() {
    app := iris.Default()
    app.Get("/{name}/{age:int}/{tail:path}", func(ctx iris.Context) {
        var p myParams
        if err := ctx.ReadParams(&p); err != nil {
            ctx.StopWithError(iris.StatusInternalServerError, err)
            return
        }
        ctx.Writef("myParams: %#v", p)
    })
    app.Listen(":8088")
}

请求

$ curl -v http://localhost:8080/kataras/27/iris/web/framework

header头绑定

package main
import "github.com/kataras/iris/v12"
type myHeaders struct {
    RequestID      string `header:"X-Request-Id,required"`
    Authentication string `header:"Authentication,required"`
}
func main() {
    app := iris.Default()
    r.GET("/", func(ctx iris.Context) {
        var hs myHeaders
        if err := ctx.ReadHeaders(&hs); err != nil {
            ctx.StopWithError(iris.StatusInternalServerError, err)
            return
        }
        ctx.JSON(hs)
    })
    app.Listen(":8080")
}

请求

curl -H "x-request-id:373713f0-6b4b-42ea-ab9f-e2e04bc38e73" -H "authentication: Bearer my-token" \
http://localhost:8080

响应

{
  "RequestID": "373713f0-6b4b-42ea-ab9f-e2e04bc38e73",
  "Authentication": "Bearer my-token"
}

绑定HTML 复选框

package main
import "github.com/kataras/iris/v12"
func main() {
    app := iris.New()
    app.RegisterView(iris.HTML("./templates", ".html"))
    app.Get("/", showForm)
    app.Post("/", handleForm)
    app.Listen(":8080")
}
func showForm(ctx iris.Context) {
    ctx.View("form.html")
}
type formExample struct {
    Colors []string `form:"colors[]"` // or just "colors".
}
func handleForm(ctx iris.Context) {
    var form formExample
    err := ctx.ReadForm(&form)
    if err != nil {
        ctx.StopWithError(iris.StatusBadRequest, err)
        return
    }
    ctx.JSON(iris.Map{"Colors": form.Colors})
}

templates/form.html

<form action="/" method="POST">
    <p>Check one or more colors</p>
    <label for="red">Red</label>
    <!-- name can be "colors" too -->
    <input type="checkbox" name="colors[]" value="red" id="red">
    <label for="green">Green</label>
    <input type="checkbox" name="colors[]" value="green" id="green">
    <label for="blue">Blue</label>
    <input type="checkbox" name="colors[]" value="blue" id="blue">
    <input type="submit">
</form>

响应

{
  "Colors": [
    "red",
    "green",
    "blue"
  ]
}

JSON,JSONP,XML,Markdown,YAML and MsgPack rendering

示例细节在这里可以找到

func main() {
    app := iris.New()
    // iris.Map is an alias of map[string]interface{}
    app.Get("/json", func(ctx iris.Context) {
        ctx.JSON(iris.Map{"message": "hello", "status": iris.StatusOK})
    })
    // Use Secure field to prevent json hijacking.
    // It prepends `"while(1),"` to the body when the data is array.
    app.Get("/json_secure", func(ctx iris.Context) {
        response := []string{"val1", "val2", "val3"}
        options := iris.JSON{Indent: "", Secure: true}
        ctx.JSON(response, options)
        // Will output: while(1);["val1","val2","val3"]
    })
    // Use ASCII field to generate ASCII-only JSON
    // with escaped non-ASCII characters.
    app.Get("/json_ascii", func(ctx iris.Context) {
        response := iris.Map{"lang": "GO-虹膜", "tag": "<br>"}
        options := iris.JSON{Indent: "    ", ASCII: true}
        ctx.JSON(response, options)
        /* Will output:
           {
               "lang": "GO-\u8679\u819c",
               "tag": "\u003cbr\u003e"
           }
        */
    })
    // Normally, JSON replaces special HTML characters with their unicode entities.
    // If you want to encode such characters literally,
    // you SHOULD set the UnescapeHTML field to true.
    app.Get("/json_raw", func(ctx iris.Context) {
        options := iris.JSON{UnescapeHTML: true}
        ctx.JSON(iris.Map{
            "html": "<b>Hello, world!</b>",
        }, options)
        // Will output: {"html":"<b>Hello, world!</b>"}
    })
    app.Get("/json_struct", func(ctx iris.Context) {
        // You also can use a struct.
        var msg struct {
            Name    string `json:"user"`
            Message string
            Number  int
        }
        msg.Name = "Mariah"
        msg.Message = "hello"
        msg.Number = 42
        // Note that msg.Name becomes "user" in the JSON.
        // Will output: {"user": "Mariah", "Message": "hello", "Number": 42}
        ctx.JSON(msg)
    })
    app.Get("/jsonp", func(ctx iris.Context) {
        ctx.JSONP(iris.Map{"hello": "jsonp"}, iris.JSONP{Callback: "callbackName"})
    })
    app.Get("/xml", func(ctx iris.Context) {
        ctx.XML(iris.Map{"message": "hello", "status": iris.StatusOK})
    })
    app.Get("/markdown", func(ctx iris.Context) {
        ctx.Markdown([]byte("# Hello Dynamic Markdown -- iris"))
    })
    app.Get("/yaml", func(ctx iris.Context) {
        ctx.YAML(iris.Map{"message": "hello", "status": iris.StatusOK})
    })
    app.Get("/msgpack", func(ctx iris.Context) {
        u := User{
            Firstname: "John",
            Lastname:  "Doe",
            City:      "Neither FBI knows!!!",
            Age:       25,
        }
        ctx.MsgPack(u)
    })
    // Render using jsoniter instead of the encoding/json:
    app.Listen(":8080", iris.WithOptimizations)
}

Protobuf

Iris支持原生原生的protobuf和protobuf对JSON的编码和解码。

package main
import (
    "app/protos"
    "github.com/kataras/iris/v12"
)
func main() {
    app := iris.New()
    app.Get("/", send)
    app.Get("/json", sendAsJSON)
    app.Post("/read", read)
    app.Post("/read_json", readFromJSON)
    app.Listen(":8080")
}
func send(ctx iris.Context) {
    response := &protos.HelloReply{Message: "Hello, World!"}
    ctx.Protobuf(response)
}
func sendAsJSON(ctx iris.Context) {
    response := &protos.HelloReply{Message: "Hello, World!"}
    options := iris.JSON{
        Proto: iris.ProtoMarshalOptions{
            AllowPartial: true,
            Multiline:    true,
            Indent:       "    ",
        },
    }
    ctx.JSON(response, options)
}
func read(ctx iris.Context) {
    var request protos.HelloRequest
    err := ctx.ReadProtobuf(&request)
    if err != nil {
        ctx.StopWithError(iris.StatusBadRequest, err)
        return
    }
    ctx.Writef("HelloRequest.Name = %s", request.Name)
}
func readFromJSON(ctx iris.Context) {
    var request protos.HelloRequest
    err := ctx.ReadJSONProtobuf(&request)
    if err != nil {
        ctx.StopWithError(iris.StatusBadRequest, err)
        return
    }
    ctx.Writef("HelloRequest.Name = %s", request.Name)
}

使用静态文件

func main() {
    app := iris.New()
    app.Favicon("./resources/favicon.ico")
    app.HandleDir("/assets", iris.Dir("./assets"))
    app.Listen(":8080")
}

HandleDir方法接受第三个可选参数DirOptions:

type DirOptions struct {
    // Defaults to "/index.html", if request path is ending with **/*/$IndexName
    // then it redirects to **/*(/) which another handler is handling it,
    // that another handler, called index handler, is auto-registered by the framework
    // if end developer does not managed to handle it by hand.
    IndexName string
    // PushTargets filenames (map's value) to
    // be served without additional client's requests (HTTP/2 Push)
    // when a specific request path (map's key WITHOUT prefix)
    // is requested and it's not a directory (it's an `IndexFile`).
    //
    // Example:
    //     "/": {
    //         "favicon.ico",
    //         "js/main.js",
    //         "css/main.css",
    //     }
    PushTargets map[string][]string
    // PushTargetsRegexp like `PushTargets` but accepts regexp which
    // is compared against all files under a directory (recursively).
    // The `IndexName` should be set.
    //
    // Example:
    // "/": regexp.MustCompile("((.*).js|(.*).css|(.*).ico)$")
    // See `iris.MatchCommonAssets` too.
    PushTargetsRegexp map[string]*regexp.Regexp
    // Cache to enable in-memory cache and pre-compress files.
    Cache DirCacheOptions
    // When files should served under compression.
    Compress bool
    // List the files inside the current requested directory if `IndexName` not found.
    ShowList bool
    // If `ShowList` is true then this function will be used instead
    // of the default one to show the list of files of a current requested directory(dir).
    // See `DirListRich` package-level function too.
    DirList DirListFunc
    // Files downloaded and saved locally.
    Attachments Attachments
    // Optional validator that loops through each requested resource.
    AssetValidator func(ctx *context.Context, name string) bool
}

了解更多关于文件服务器的信息。

上下文服务数据

SendFile(filename string, destinationName string) error
SendFileWithRate(src, destName string, limit float64, burst int) error

使用

强制发送文件到客户端:

func handler(ctx iris.Context) {
    src := "./files/first.zip"
    ctx.SendFile(src, "client.zip")
}

限制下载速度~50Kb/s，一次100KB的下载:

func handler(ctx iris.Context) {
    src := "./files/big.zip"
    // optionally, keep it empty to resolve the filename based on the "src".
    dest := "" 
    limit := 50.0 * iris.KB
    burst := 100 * iris.KB
    ctx.SendFileWithRate(src, dest, limit, burst)
}

ServeContent(content io.ReadSeeker, filename string, modtime time.Time)
ServeContentWithRate(content io.ReadSeeker, filename string, modtime time.Time, limit float64, burst int)
ServeFile(filename string) error
ServeFileWithRate(filename string, limit float64, burst int) error

使用

func handler(ctx iris.Context) {
    ctx.ServeFile("./public/main.js")
}

模式渲染

Iris支持8个开箱即用的模板引擎，开发人员仍然可以使用任何外部的golang模板引擎，因为Context.ResponseWriter()是一个io.Writer。

所有的模板引擎都共享一个通用的API，例如使用嵌入资产的解析，布局和特定于团队的布局，模板函数，部分渲染等等。

List of Examples
List of Benchmarks
视图引擎可以为每一方注册。要注册一个视图引擎，可以使用Application/Party.RegisterView(ViewEngine)方法，如下所示。

从”./view”目录加载所有扩展名是”.html”，并使用标准的html/模板包解析它们。

// [app := iris.New...]
tmpl := iris.HTML("./views", ".html")
app.RegisterView(tmpl)

使用Context.View呈现或执行视图。视图方法在主路由的处理程序内。

ctx.View("hi.html")

要通过中间件或主处理程序在视图中使用键-值模式绑定Go值，请使用上下文。在Context.View之前的ViewData方法。一个视图。

绑定值为”Hello world”的变量。

ctx.ViewData("message", "Hello world!")

根绑定：

ctx.View("user-page.html", User{})
// root binding as {{.Name}}

要添加模板函数，请使用首选视图引擎的AddFunc方法。

//       func name, input arguments, render value
tmpl.AddFunc("greet", func(s string) string {
    return "Greetings " + s + "!"
})

要在每个请求上重新加载，请调用视图引擎的reload方法。

tmpl.Reload(true)

要使用嵌入式模板而不依赖于本地文件系统，请使用go-bindata外部工具并将其AssetFile()生成的函数传递给首选视图引擎的第一个输入参数。

 tmpl := iris.HTML(AssetFile(), ".html")

代码示例：

// file: main.go
package main
import "github.com/kataras/iris/v12"
func main() {
    app := iris.New()
    // Parse all templates from the "./views" folder
    // where extension is ".html" and parse them
    // using the standard `html/template` package.
    tmpl := iris.HTML("./views", ".html")
    // Set custom delimeters.
    tmpl.Delims("{{", "}}")
    // Enable re-build on local template files changes.
    tmpl.Reload(true)
    // Default template funcs are:
    //
    // - {{ urlpath "myNamedRoute" "pathParameter_ifNeeded" }}
    // - {{ render "header.html" }}
    // and partial relative path to current page:
    // - {{ render_r "header.html" }} 
    // - {{ yield }}
    // - {{ current }}
    // Register a custom template func:
    tmpl.AddFunc("greet", func(s string) string {
        return "Greetings " + s + "!"
    })
    // Register the view engine to the views,
    // this will load the templates.
    app.RegisterView(tmpl)
    // Method:    GET
    // Resource:  http://localhost:8080
    app.Get("/", func(ctx iris.Context) {
        // Bind: {{.message}} with "Hello world!"
        ctx.ViewData("message", "Hello world!")
        // Render template file: ./views/hi.html
        ctx.View("hi.html")
    })
    app.Listen(":8080")
}

<!-- file: ./views/hi.html -->
<html>
<head>
    <title>Hi Page</title>
</head>
<body>
    <h1>{{.message}}</h1>
    <strong>{{greet "to you"}}</strong>
</body>
</html>

访问http://localhost:8080

已经渲染的效果看起来像这样：

<html>
<head>
    <title>Hi Page</title>
</head>
<body>
    <h1>Hello world!</h1>
    <strong>Greetings to you!</strong>
</body>
</html>

多个模板文件

Iris允许每个应用程序无限制地注册视图引擎。除此之外，您还可以为每一方或通过中间件注册一个视图引擎!

// Register a view engine per group of routes.
adminGroup := app.Party("/admin")
adminGroup.RegisterView(iris.Blocks("./views/admin", ".html"))

通过中间件

func middleware(views iris.ViewEngine) iris.Handler {
    return func(ctx iris.Context) {
        ctx.ViewEngine(views)
        ctx.Next()
    }
}

使用

// Register a view engine on-fly for the current chain of handlers.
views := iris.Blocks("./views/on-fly", ".html")
views.Load()
app.Get("/", setViews(views), onFly)

重定向

发出HTTP重定向很容易。支持内部和外部位置。我们说的位置是指路径，子域，域等等。

处理器

app.Get("/", func(ctx iris.Context) {
    ctx.Redirect("https://golang.org/dl", iris.StatusMovedPermanently)
})

从POST发出HTTP重定向。

app.Post("/", func(ctx iris.Context) {
    ctx.Redirect("/login", iris.StatusFound)
})

从处理程序发出本地路由器重定向，使用应用程序。ServeHTTPC或Exec()，如下所示。

app.Get("/test", func(ctx iris.Context) {
    r := ctx.Request()
    r.URL.Path = "/test2"
    ctx.Application().ServeHTTPC(ctx)
    // OR
    // ctx.Exec("GET", "/test2")
})
app.Get("/test2", func(ctx iris.Context) {
    ctx.JSON(iris.Map{"hello": "world"})
})