☕ add a dependency-injection examples folder for the next release and some improvements

Former-commit-id: 040168afb7caf808618f7da5e68ae8eb01cb7170

_examples/dependency-injection/basic/main.go

@@ -0,0 +1,27 @@
+package main
+
+import "github.com/kataras/iris/v12"
+
+type (
+	testInput struct {
+		Email string `json:"email"`
+	}
+
+	testOutput struct {
+		ID   int    `json:"id"`
+		Name string `json:"name"`
+	}
+)
+
+func handler(id int, in testInput) testOutput {
+	return testOutput{
+		ID:   id,
+		Name: in.Email,
+	}
+}
+
+func main() {
+	app := iris.New()
+	app.HandleFunc(iris.MethodPost, "/{id:int}", handler)
+	app.Listen(":5000", iris.WithOptimizations)
+}

_examples/dependency-injection/basic/middleware/main.go

@@ -0,0 +1,61 @@
+package main
+
+import (
+	"errors"
+
+	"github.com/kataras/iris/v12"
+)
+
+type (
+	testInput struct {
+		Email string `json:"email"`
+	}
+
+	testOutput struct {
+		ID   int    `json:"id"`
+		Name string `json:"name"`
+	}
+)
+
+func handler(id int, in testInput) testOutput {
+	return testOutput{
+		ID:   id,
+		Name: in.Email,
+	}
+}
+
+var errCustom = errors.New("my_error")
+
+func middleware(in testInput) (int, error) {
+	if in.Email == "invalid" {
+		// stop the execution and don't continue to "handler"
+		// without firing an error.
+		return iris.StatusAccepted, iris.ErrStopExecution
+	} else if in.Email == "error" {
+		// stop the execution and fire a custom error.
+		return iris.StatusConflict, errCustom
+	}
+
+	return iris.StatusOK, nil
+}
+
+func newApp() *iris.Application {
+	app := iris.New()
+
+	// handle the route, respond with
+	// a JSON and 200 status code
+	// or 202 status code and empty body
+	// or a 409 status code and "my_error" body.
+	app.HandleFunc(iris.MethodPost, "/{id:int}", middleware, handler)
+
+	app.Configure(
+		iris.WithOptimizations, /* optional */
+		iris.WithoutBodyConsumptionOnUnmarshal /* required when more than one handler is consuming request payload(testInput) */)
+
+	return app
+}
+
+func main() {
+	app := newApp()
+	app.Listen(":8080")
+}

_examples/dependency-injection/basic/middleware/main_test.go

@@ -0,0 +1,25 @@
+package main
+
+import (
+	"testing"
+
+	"github.com/kataras/iris/v12/httptest"
+)
+
+func TestDependencyInjectionBasic_Middleware(t *testing.T) {
+	app := newApp()
+
+	e := httptest.New(t, app)
+	e.POST("/42").WithJSON(testInput{Email: "my_email"}).Expect().
+		Status(httptest.StatusOK).
+		JSON().Equal(testOutput{ID: 42, Name: "my_email"})
+
+	// it should stop the execution at the middleware and return the middleware's status code,
+	// because the error is `ErrStopExecution`.
+	e.POST("/42").WithJSON(testInput{Email: "invalid"}).Expect().
+		Status(httptest.StatusAccepted).Body().Empty()
+
+	// it should stop the execution at the middleware and return the error's text.
+	e.POST("/42").WithJSON(testInput{Email: "error"}).Expect().
+		Status(httptest.StatusConflict).Body().Equal("my_error")
+}