Latest commit 2bd7a8e Nov 28, 2018
Permalink
Type Name Latest commit message Commit time
..
Failed to load latest commit information.
apidoc/yaag Update to version 8.5.6 | Read HISTORY.md Nov 5, 2017
authentication Update to version 8.5.6 | Read HISTORY.md Nov 5, 2017
cache add `Cache304` as an alternative to the server-side kataras/iris/cach… Jan 25, 2018
configuration Add a useful(?) introduction README.md section to some examples Nov 7, 2017
convert-handlers Add an example on how to use third-party handlers that are not compat… Oct 13, 2017
cookies Cookies: Ability to set custom cookie encoders to encode the cookie's… Jun 2, 2018
experimental-handlers Update to version 11.0.4. Read https://github.com/kataras/iris/blob/m… Nov 9, 2018
file-server Add 'context.OnConnectionClose(callbackFn) bool' and 'context.OnClose… Aug 2, 2018
hello-world one for today, one for tomorrow and ready :) Dec 30, 2017
hero Version 11 released. Read https://github.com/kataras/iris/blob/master… Oct 21, 2018
http-listening Version 11 released. Read https://github.com/kataras/iris/blob/master… Oct 21, 2018
http_request examples: update the cors example to be easier for beginners Nov 6, 2018
http_responsewriter examples: writing an API for the Apache Kafka: add a root handler for… Aug 5, 2018
miscellaneous Add example for struct validation(3rd-party) through json request bod… Jul 24, 2018
mvc Version 11 released. Read https://github.com/kataras/iris/blob/master… Oct 21, 2018
orm/xorm 8.4.0 | New MVC Features | Refactor examples and godoc for go 1.9 use… Aug 27, 2017
overview Version 11 released. Read https://github.com/kataras/iris/blob/master… Oct 21, 2018
routing fix #1141 and #1142 Nov 28, 2018
sessions #1061 Aug 14, 2018
structuring add context#StatusCodeNotSuccessful for customize even the most custo… Jan 31, 2018
subdomains Version 11 released. Read https://github.com/kataras/iris/blob/master… Oct 21, 2018
testing/httptest 8.4.0 | New MVC Features | Refactor examples and godoc for go 1.9 use… Aug 27, 2017
tutorial Version 11 released. Read https://github.com/kataras/iris/blob/master… Oct 21, 2018
versioning add versioning example Nov 18, 2018
view modify Oct 27, 2018
webassembly/basic Version 11 released. Read https://github.com/kataras/iris/blob/master… Oct 21, 2018
websocket Update to version 11.0.1. Feature request implemented: #1113 Oct 27, 2018
README.md add versioning example Nov 18, 2018
README_ZH.md Version 11 released. Read https://github.com/kataras/iris/blob/master… Oct 21, 2018

README.md

Examples

Please do learn how net/http std package works, first.

This folder provides easy to understand code snippets on how to get started with iris micro web framework.

It doesn't always contain the "best ways" but it does cover each important feature that will make you so excited to GO with iris!

Running the examples

  1. Install the Go Programming Language, version 1.9+ from here.
  2. Install Iris: go get -u github.com/kataras/iris
  3. Install any external packages that required by the examples
External packages
cd _examples && go get ./...
# or
go get github.com/iris-contrib/middleware/...
go get github.com/betacraft/yaag/irisyaag
go get github.com/markbates/goth/...
go get github.com/casbin/casbin
go get github.com/aws/aws-sdk-go/...
go get github.com/getsentry/raven-go/...
go get github.com/prometheus/client_golang/...
go get github.com/didip/tollbooth
go get github.com/valyala/quicktemplate
go get github.com/shiyanhui/hero
go get github.com/go-xorm/xorm
go get github.com/nfnt/resize
go get github.com/dgrijalva/jwt-go
go get github.com/newrelic/go-agent
go get github.com/valyala/tcplisten
go get github.com/kataras/bindata/cmd/bindata
go get github.com/jmespath/go-jmespath

And execute

$ cd $GOPATH/src/github.com/kataras/iris/_examples/overview
$ go run main.go

Test the examples by opening a terminal window and execute: GOCACHE=off && cd _examples && go test -v ./...

Overview

Structuring

Nothing stops you from using your favorite folder structure. Iris is a low level web framework, it has got MVC first-class support but it doesn't limit your folder structure, this is your choice.

Structuring depends on your own needs. We can't tell you how to design your own application for sure but you're free to take a closer look to the examples below; you may find something useful that you can borrow for your app;

HTTP Listening

Configuration

Routing, Grouping, Dynamic Path Parameters, "Macros" and Custom Context

  • app.Get("{userid:int min(1)}", myHandler)
  • app.Post("{asset:path}", myHandler)
  • app.Put("{custom:string regexp([a-z]+)}", myHandler)

Note: unlike other routers you'd seen, iris' router can handle things like these:

// Matches all GET requests prefixed with "/assets/"
app.Get("/assets/{asset:path}", assetsWildcardHandler)

// Matches only GET "/"
app.Get("/", indexHandler)
// Matches only GET "/about"
app.Get("/about", aboutHandler)

// Matches all GET requests prefixed with "/profile/"
// and followed by a single path part
app.Get("/profile/{username:string}", userHandler)
// Matches only GET "/profile/me" because 
// it does not conflict with /profile/{username:string}
// or the root wildcard {root:path}
app.Get("/profile/me", userHandler)

// Matches all GET requests prefixed with /users/
// and followed by a number which should be equal or bigger than 1
app.Get("/user/{userid:int min(1)}", getUserHandler)
// Matches all requests DELETE prefixed with /users/
// and following by a number which should be equal or bigger than 1
app.Delete("/user/{userid:int min(1)}", deleteUserHandler)

// Matches all GET requests except "/", "/about", anything starts with "/assets/" etc...
// because it does not conflict with the rest of the routes.
app.Get("{root:path}", rootWildcardHandler)

Navigate through examples for a better understanding.

Versioning

hero

MVC

Iris has first-class support for the MVC (Model View Controller) pattern, you'll not find these stuff anywhere else in the Go world.

Iris web framework supports Request data, Models, Persistence Data and Binding with the fastest possible execution.

Characteristics

All HTTP Methods are supported, for example if want to serve GET then the controller should have a function named Get(), you can define more than one method function to serve in the same Controller.

Serve custom controller's struct's methods as handlers with custom paths(even with regex parametermized path) via the BeforeActivation custom event callback, per-controller. Example:

import (
    "github.com/kataras/iris"
    "github.com/kataras/iris/mvc"
)

func main() {
    app := iris.New()
    mvc.Configure(app.Party("/root"), myMVC)
    app.Run(iris.Addr(":8080"))
}

func myMVC(app *mvc.Application) {
    // app.Register(...)
    // app.Router.Use/UseGlobal/Done(...)
    app.Handle(new(MyController))
}

type MyController struct {}

func (m *MyController) BeforeActivation(b mvc.BeforeActivation) {
    // b.Dependencies().Add/Remove
    // b.Router().Use/UseGlobal/Done // and any standard API call you already know

    // 1-> Method
    // 2-> Path
    // 3-> The controller's function name to be parsed as handler
    // 4-> Any handlers that should run before the MyCustomHandler
    b.Handle("GET", "/something/{id:long}", "MyCustomHandler", anyMiddleware...)
}

// GET: http://localhost:8080/root
func (m *MyController) Get() string { return "Hey" }

// GET: http://localhost:8080/root/something/{id:long}
func (m *MyController) MyCustomHandler(id int64) string { return "MyCustomHandler says Hey" }

Persistence data inside your Controller struct (share data between requests) by defining services to the Dependencies or have a Singleton controller scope.

Share the dependencies between controllers or register them on a parent MVC Application, and ability to modify dependencies per-controller on the BeforeActivation optional event callback inside a Controller, i.e func(c *MyController) BeforeActivation(b mvc.BeforeActivation) { b.Dependencies().Add/Remove(...) }.

Access to the Context as a controller's field(no manual binding is neede) i.e Ctx iris.Context or via a method's input argument, i.e func(ctx iris.Context, otherArguments...).

Models inside your Controller struct (set-ed at the Method function and rendered by the View). You can return models from a controller's method or set a field in the request lifecycle and return that field to another method, in the same request lifecycle.

Flow as you used to, mvc application has its own Router which is a type of iris/router.Party, the standard iris api. Controllers can be registered to any Party, including Subdomains, the Party's begin and done handlers work as expected.

Optional BeginRequest(ctx) function to perform any initialization before the method execution, useful to call middlewares or when many methods use the same collection of data.

Optional EndRequest(ctx) function to perform any finalization after any method executed.

Inheritance, recursively, see for example our mvc.SessionController, it has the Session *sessions.Session and Manager *sessions.Sessions as embedded fields which are filled by its BeginRequest, here. This is just an example, you could use the sessions.Session which returned from the manager's Start as a dynamic dependency to the MVC Application, i.e mvcApp.Register(sessions.New(sessions.Config{Cookie: "iris_session_id"}).Start).

Access to the dynamic path parameters via the controller's methods' input arguments, no binding is needed. When you use the Iris' default syntax to parse handlers from a controller, you need to suffix the methods with the By word, uppercase is a new sub path. Example:

If mvc.New(app.Party("/user")).Handle(new(user.Controller))

  • func(*Controller) Get() - GET:/user.
  • func(*Controller) Post() - POST:/user.
  • func(*Controller) GetLogin() - GET:/user/login
  • func(*Controller) PostLogin() - POST:/user/login
  • func(*Controller) GetProfileFollowers() - GET:/user/profile/followers
  • func(*Controller) PostProfileFollowers() - POST:/user/profile/followers
  • func(*Controller) GetBy(id int64) - GET:/user/{param:long}
  • func(*Controller) PostBy(id int64) - POST:/user/{param:long}

If mvc.New(app.Party("/profile")).Handle(new(profile.Controller))

  • func(*Controller) GetBy(username string) - GET:/profile/{param:string}

If mvc.New(app.Party("/assets")).Handle(new(file.Controller))

  • func(*Controller) GetByWildard(path string) - GET:/assets/{param:path}

    Supported types for method functions receivers: int, int64, bool and string.

Response via output arguments, optionally, i.e

func(c *ExampleController) Get() string |
                                (string, string) |
                                (string, int) |
                                int |
                                (int, string) |
                                (string, error) |
                                error |
                                (int, error) |
                                (any, bool) |
                                (customStruct, error) |
                                customStruct |
                                (customStruct, int) |
                                (customStruct, string) |
                                mvc.Result or (mvc.Result, error)

where mvc.Result is an interface which contains only that function: Dispatch(ctx iris.Context).

Using Iris MVC for code reuse

By creating components that are independent of one another, developers are able to reuse components quickly and easily in other applications. The same (or similar) view for one application can be refactored for another application with different data because the view is simply handling how the data is being displayed to the user.

If you're new to back-end web development read about the MVC architectural pattern first, a good start is that wikipedia article.

Follow the examples below,

Subdomains

Convert http.Handler/HandlerFunc

View

Engine Declaration
template/html iris.HTML(...)
django iris.Django(...)
handlebars iris.Handlebars(...)
amber iris.Amber(...)
pug(jade) iris.Pug(...)

You can serve quicktemplate and hero templates files too, simply by using the context#ResponseWriter, take a look at the http_responsewriter/quicktemplate and http_responsewriter/herotemplate examples.

Authentication

File Server

How to Read from context.Request() *http.Request

The context.Request() returns the same *http.Request you already know, these examples show some places where the Context uses this object. Besides that you can use it as you did before iris.

How to Write to context.ResponseWriter() http.ResponseWriter

The context/context#ResponseWriter() returns an enchament version of a http.ResponseWriter, these examples show some places where the Context uses this object. Besides that you can use it as you did before iris.

ORM

Miscellaneous

Experimental Handlers

More

https://github.com/kataras/iris/tree/master/middleware#third-party-handlers

Automated API Documentation

Testing

The httptest package is your way for end-to-end HTTP testing, it uses the httpexpect library created by our friend, gavv.

Example

Caching

iris cache library lives on its own package.

You're free to use your own favourite caching package if you'd like so.

Cookies

Sessions

iris session manager lives on its own package.

You're free to use your own favourite sessions package if you'd like so.

Websockets

iris websocket library lives on its own package.

The package is designed to work with raw websockets although its API is similar to the famous socket.io. I have read an article recently and I felt very contented about my decision to design a fast websocket-only package for Iris and not a backwards socket.io-like package. You can read that article by following this link: https://medium.com/@ivanderbyl/why-you-don-t-need-socket-io-6848f1c871cd.

You're free to use your own favourite websockets package if you'd like so.

Typescript Automation Tools

typescript automation tools have their own repository: https://github.com/kataras/iris/tree/master/typescript it contains examples

I'd like to tell you that you can use your favourite but I don't think you will find such a thing anywhere else.

Hey, You

Developers should read the godocs and https://docs.iris-go.com for a better understanding.

Psst, I almost forgot; do not forget to star or watch the project in order to stay updated with the latest tech trends, it never takes more than a second!