From 84cd4ca6f4c9dd3293464267c6a6866c70879234 Mon Sep 17 00:00:00 2001 From: "Gerasimos (Makis) Maropoulos" Date: Sun, 5 Feb 2017 20:26:40 +0200 Subject: [PATCH] Go v1.8 and the upcoming Iris version notes on HISTORY.md. --- HISTORY.md | 9 +++- README.md | 119 +++++++++++++++++++++++--------------------- docs/QUICK_START.md | 88 ++++++++++++++++++++++---------- iris/run.go | 8 +-- 4 files changed, 136 insertions(+), 88 deletions(-) diff --git a/HISTORY.md b/HISTORY.md index 5e87a2e8..d64691b0 100644 --- a/HISTORY.md +++ b/HISTORY.md @@ -14,13 +14,18 @@ Users should prepare their apps for: - **MOST IMPORTANT: REMOVE** Package-level exported `iris.Default's methods and variables`, `iris.Default` will exists but methods like `iris.Handle` should be replace with `iris.Default.Handle` or `app := iris.New(); app.Handle(...); // like before, these will never change`. - Why? - + Iris is bigger than it was, we need to keep a limit on the exported functions to help users understand the flow much easier. Users often asked questions about built'n features and functions usage because they are being confused of the big public API (`iris.` vs `app := iris.New(); app.`). This removal will also let me to describe the types with more sense. - + - NEW feature: `app.Adapt(iris.Policy)` which you will be able to adapt a **custom http router**, **custom template functions**, **custom http router wrappers**, **flow events** and much more. I'll cover these on book and examples when it will be released. - Replace: `.Plugins.` with `EventPolicy`: `app.Adapt(iris.EventPolicy{ Boot: func(*iris.Framework){}} )`. + - Why? + + To be ready and don't confuse future users with the go's plugin mechanism. + A 'real plugin system' is coming with go 1.8 BUT we will not use that ready because + they are not ready for all operating systems. - Replace: `.AcquireCtx/.ReleaseCtx` with `app.Context.Acquire/Release/Run`. diff --git a/README.md b/README.md index b88310e3..e7907b8a 100644 --- a/README.md +++ b/README.md @@ -50,6 +50,7 @@ If you're coming from Node.js world, this i

+ Installation ----------- @@ -59,6 +60,9 @@ The only requirement is the [Go Programming Language](https://golang.org/dl/), a $ go get -u github.com/kataras/iris/iris ``` +![Benchmark Wizzard July 21, 2016- Processing Time Horizontal Graph](https://raw.githubusercontent.com/smallnest/go-web-framework-benchmark/4db507a22c964c9bc9774c5b31afdc199a0fe8b7/benchmark.png) + + Overview ----------- @@ -66,74 +70,77 @@ Overview package main import ( - "github.com/kataras/iris" "github.com/kataras/go-template/html" + "github.com/kataras/iris" ) -func main(){ +func main() { + app := iris.New() + // 6 template engines are supported out-of-the-box: + // + // - standard html/template + // - amber + // - django + // - handlebars + // - pug(jade) + // - markdown + // + // Use the html standard engine for all files inside "./views" folder with extension ".html" + // Defaults to: + app.UseTemplate(html.New()).Directory("./views", ".html") - // 6 template engines are supported out-of-the-box: - // - // - standard html/template - // - amber - // - django - // - handlebars - // - pug(jade) - // - markdown - // - // Use the html standard engine for all files inside "./views" folder with extension ".html" - iris.UseTemplate(html.New()).Directory("./views", ".html") + // http://localhost:6111 + // Method: "GET" + // Render ./views/index.html + app.Get("/", func(ctx *iris.Context) { + ctx.Render("index.html", nil) + }) - // http://localhost:6111 - // Method: "GET" - // Render ./views/index.html - iris.Get("/", func(ctx *iris.Context){ - ctx.Render("index.html", nil) - }) + // Group routes, optionally: share middleware, template layout and custom http errors. + userAPI := app.Party("/users", userAPIMiddleware). + Layout("layouts/userLayout.html") + { + // Fire userNotFoundHandler when Not Found + // inside http://localhost:6111/users/*anything + userAPI.OnError(404, userNotFoundHandler) - // Group routes, optionally: share middleware, template layout and custom http errors. - userAPI := iris.Party("/users", userAPIMiddleware). - Layout("layouts/userLayout.html") - { - // Fire userNotFoundHandler when Not Found - // inside http://localhost:6111/users/*anything - userAPI.OnError(404, userNotFoundHandler) + // http://localhost:6111/users + // Method: "GET" + userAPI.Get("/", getAllHandler) - // http://localhost:6111/users - // Method: "GET" - userAPI.Get("/", getAllHandler) + // http://localhost:6111/users/42 + // Method: "GET" + userAPI.Get("/:id", getByIDHandler) - // http://localhost:6111/users/42 - // Method: "GET" - userAPI.Get("/:id", getByIDHandler) + // http://localhost:6111/users + // Method: "POST" + userAPI.Post("/", saveUserHandler) + } - // http://localhost:6111/users - // Method: "POST" - userAPI.Post("/", saveUserHandler) - } - - getByIDHandler := func(ctx *iris.Context){ - // take the :id from the path, parse to integer - // and set it to the new userID local variable. - userID,_ := ctx.ParamInt("id") - - // userRepo, imaginary database service <- your only job. - user := userRepo.GetByID(userID) - - // send back a response to the client, - // .JSON: content type as application/json; charset="utf-8" - // iris.StatusOK: with 200 http status code. - // - // send user as it is or make use of any json valid golang type, - // like the iris.Map{"username" : user.Username}. - ctx.JSON(iris.StatusOK, user) - } - - // Start the server at 0.0.0.0:6111 - iris.Listen(":6111") + // Start the server at 0.0.0.0:6111 + app.Listen(":6111") } +func getByIDHandler(ctx *iris.Context) { + // take the :id from the path, parse to integer + // and set it to the new userID local variable. + userID, _ := ctx.ParamInt("id") + + // userRepo, imaginary database service <- your only job. + user := userRepo.GetByID(userID) + + // send back a response to the client, + // .JSON: content type as application/json; charset="utf-8" + // iris.StatusOK: with 200 http status code. + // + // send user as it is or make use of any json valid golang type, + // like the iris.Map{"username" : user.Username}. + ctx.JSON(iris.StatusOK, user) +} ``` +> TIP: Execute `iris run main.go` to enable hot-reload on .go source code changes. + +> TIP: Set `app.Config.IsDevelopment = true` to monitor the template changes. Documentation ----------- diff --git a/docs/QUICK_START.md b/docs/QUICK_START.md index 6a3ccb09..0bd867fd 100644 --- a/docs/QUICK_START.md +++ b/docs/QUICK_START.md @@ -6,45 +6,83 @@ go get -u github.com/kataras/iris/iris ``` ```sh -cat hellojson.go +cat app.go ``` ```go -package main +package iris_test -import "github.com/kataras/iris" +import ( + "github.com/kataras/go-template/html" + "github.com/kataras/iris" +) -func main(){ +func main() { + app := iris.New() + // 6 template engines are supported out-of-the-box: + // + // - standard html/template + // - amber + // - django + // - handlebars + // - pug(jade) + // - markdown + // + // Use the html standard engine for all files inside "./views" folder with extension ".html" + // Defaults to: + app.UseTemplate(html.New()).Directory("./views", ".html") - // http://localhost:5700/api/user/42 - // Method: "GET" - iris.Get("/api/user/:id", func(ctx *iris.Context){ + // http://localhost:6111 + // Method: "GET" + // Render ./views/index.html + app.Get("/", func(ctx *iris.Context) { + ctx.Render("index.html", nil) + }) - // take the :id from the path, parse to integer - // and set it to the new userID local variable. - userID,_ := ctx.ParamInt("id") + // Group routes, optionally: share middleware, template layout and custom http errors. + userAPI := app.Party("/users", userAPIMiddleware). + Layout("layouts/userLayout.html") + { + // Fire userNotFoundHandler when Not Found + // inside http://localhost:6111/users/*anything + userAPI.OnError(404, userNotFoundHandler) - // userRepo, imaginary database service <- your only job. - user := userRepo.GetByID(userID) + // http://localhost:6111/users + // Method: "GET" + userAPI.Get("/", getAllHandler) - // send back a response to the client, - // .JSON: content type as application/json; charset="utf-8" - // iris.StatusOK: with 200 http status code. - // - // send user as it is or make use of any json valid golang type, - // like the iris.Map{"username" : user.Username}. - ctx.JSON(iris.StatusOK, user) + // http://localhost:6111/users/42 + // Method: "GET" + userAPI.Get("/:id", getByIDHandler) - }) + // http://localhost:6111/users + // Method: "POST" + userAPI.Post("/", saveUserHandler) + } - iris.Listen(":6000") + // Start the server at 0.0.0.0:6111 + app.Listen(":6111") +} + +func getByIDHandler(ctx *iris.Context) { + // take the :id from the path, parse to integer + // and set it to the new userID local variable. + userID, _ := ctx.ParamInt("id") + + // userRepo, imaginary database service <- your only job. + user := userRepo.GetByID(userID) + + // send back a response to the client, + // .JSON: content type as application/json; charset="utf-8" + // iris.StatusOK: with 200 http status code. + // + // send user as it is or make use of any json valid golang type, + // like the iris.Map{"username" : user.Username}. + ctx.JSON(iris.StatusOK, user) } ``` -```sh -$ go run hellojson.go -``` > TIP: $ iris run main.go to enable hot-reload on .go source code changes. > TIP: iris.Config.IsDevelopment = true to monitor the changes you make in the templates. @@ -52,8 +90,6 @@ $ go run hellojson.go > TIP: Want to change the default Router's behavior to something else like Gorilla's Mux? Go [there](https://github.com/iris-contrib/examples/tree/master/plugin_gorillamux) to learn how. -Open your browser or any other http client at http://localhost:6000/api/user/42. - ### New diff --git a/iris/run.go b/iris/run.go index f1b1bafb..19646a61 100644 --- a/iris/run.go +++ b/iris/run.go @@ -27,8 +27,8 @@ func run(cli.Flags) error { } func runAndWatch(programPath string) { - rizla.DefaultDisableProgramRerunOutput = true // we don't want the banner to be shown after the first run - // run with the filepath.Walk method instead of file signals because - // some (not the majority) users' editors override the operating system's file signals - rizla.RunWith(rizla.WatcherFromFlag("-walk")) + // we don't want the banner to be shown after the first run + rizla.DefaultDisableProgramRerunOutput = true + // See https://github.com/kataras/rizla/issues/6#issuecomment-277533051 + rizla.Run(programPath) }