Runnable programs for Iris v14, ordered the
way the book teaches: a tutorial that grows one
small service step by step, then one section per topic. Every example was
compiled against the framework source and exercised over HTTP before it was
committed; each main.go opens with a comment saying what it shows, what you
will be able to do afterwards, how to try it, and which example to read next.
Requirements: Go 1.27 or newer (the examples import the standard library's
uuid package). New to Iris? Start with 01-getting-started and do the steps
in order.
The _examples directory starts with an underscore, so the Go toolchain
ignores it and no example ships its own go.mod. Copy the code into your
own module:
mkdir myapp && cd myapp
go mod init myapp
go get github.com/kataras/iris/v14@latest
# copy the example's main.go here, then:
go run .Every example listens on :8080 and prints the endpoints it registers.
Thirteen programs that grow one service, the Bookshelf (shelves hold books; a
locked shelf freezes its books), from a single route to a tested,
production-shaped API on the iris.NewBuilder chain. Each step is a complete
main.go that adds one idea to the previous one, so you can diff two
neighbours to see exactly what changed. Do them in order; afterwards the other
sections stand alone as references. You should be comfortable with Go and with
HTTP methods, headers and status codes. No Iris experience is assumed.
TUTORIAL.md splits the final step into packages.
Book chapters 1 to 3: Getting Started, Core Concepts, Building Applications with iris.NewBuilder.
| Step | Shows |
|---|---|
| 01-hello-world | The smallest Iris program: iris.New, one route, one JSON response, app.Listen |
| 02-routes-and-params | A router prefix, {id:uuid}, ctx.Params, ctx.OK and a 404 in the standard envelope |
| 03-json-and-validation | ctx.BindJSON[T] running the payload's Validate(), ctx.Created, the exact 400 clients receive |
| 04-errors-mapped-once | Sentinel errors mapped to status codes once with errors.NewOptions; handlers forward with ctx.OK and ctx.NoContent |
| 05-storage-behind-an-interface | Repository interface, MemStore, a Service holding the rules; the request context reaches storage |
| 06-controllers | A controller: constructor + Routing(r iris.Router), mounted through the container |
| 07-nested-routes-and-guards | Books under shelves: a nested controller, a group guard, positional guards, ctx.Values caching |
| 08-pagination | ctx.Paginated with a typed filter, the Page[T] envelope, the list over GET and QUERY |
| 09-middleware | Writing a middleware and choosing UseRouter, Use or a positional guard |
| 10-admin-and-basicauth | An admin controller behind basicauth.Default; protection applied at the mount, not in the controller |
| 11-configuration | iris.LoadConfiguration[T] with an inlined iris.BaseConfiguration; secrets from the environment only |
| 12-newbuilder | The whole service on the iris.NewBuilder chain: Services, Errors, Health, API, Deferrables, Init/Close |
| 13-testing | httptest.New against newApp(cfg, repo): CRUD, pagination, guards, auth, and a one-method failing fake |
Book chapter 4: Routing & Controllers.
| Example | Shows |
|---|---|
| routing-basics | GET/POST/PUT/DELETE with ctx.BindJSON, ctx.List, ctx.Created, ctx.OK, ctx.NoContent and errors.NotFoundID |
| path-parameters | Typed macros ({id:int}, {uid:uuid}, {addr:mail}), safe accessor defaults, else 400 constraints, ctx.BindParam |
| groups | app.Router("/api"), nesting, per-group middleware |
| subdomains | Subdomain routing and wildcard subdomains |
| custom-macro | Registering your own path macro and parameter functions; errors.DefaultPathParameterTypeErrorHandler |
| wrap-router | WrapRouter for cross-cutting rewrites before routing |
Book chapter 4: Routing & Controllers; generic MVC is in chapter 24.
| Example | Shows |
|---|---|
| basic | The NewXxxAPI constructor + Routing(r iris.Router) convention |
| nested-guards | Nested routers, group guards, positional guards, cached context values |
| mvc-generics | Generic MVC controllers with generated CRUD routes |
| repository | mvc.UseRepository: the six resource routes over a repository, with Guard, Pagination and BeforeWrite |
Book chapter 5: Reading Requests.
| Example | Shows |
|---|---|
| query-and-forms | ctx.Query() typed getters, Lookup, GetSlice, ReadForm and its errors.InvalidArgument rejection |
| read-json-validate | ctx.BindJSON[T] running the payload's own Validate(); the 400 wire format |
| read-json-optional | ctx.BindJSONOptional[T] when the body may be absent |
| raw-body | ctx.ReadBody into *string, *[]byte and structs by content type; errors.HandleRequestError for what it returns |
| strict-query | ctx.QueryDate/QueryInt/QueryBool with required, default and zero-value options; ctx.BindUpdate and its unknown-column 400 |
| pagination | ctx.Paginated with a filter and the Page[T] envelope |
| uploads | UploadFormFiles, filename safety, PostMaxMemory |
| body-limits | BodyMaxMemory app-wide and bodylimit per route (413) |
Book chapter 6: Response Handling.
| Example | Shows |
|---|---|
| rest-helpers | ctx.OK/Created/NoContent, ctx.Count and the ctx.Helper(value, err) contract |
| writers | JSON (with options), JSONP, XML, YAML, Markdown, Text, HTML, Binary |
| content-negotiation | ctx.Negotiation() / Negotiate by Accept |
| files | ServeFile, SendFile, ServeContent, rate-limited downloads |
| streaming-sse | Server-Sent Events with sse.Open: deferred headers, heartbeat, terminal frame, batching |
| streaming-ai | One ai.Open handler serving both stream: true and a single JSON document |
Book chapter 7: Middleware, and chapter 12: Built-in Middleware.
| Example | Shows |
|---|---|
| writing-middleware | Writing your own; UseRouter vs Use vs positional scopes; guards that refuse through rest/errors |
| conditional | iris.NewConditionalHandler and filters |
| error-middleware | Middleware that returns error |
| cors | Cross-origin requests and preflight |
| rate-limit | Token-bucket limits, per-client identity, Retry-After |
| request-id | Correlation ids, including the server-only generator |
| accesslog | Structured request logs with custom fields |
| cache | Client cache headers and server-side response caching |
| i18n | Locale files, language detection, plurals and variables |
Book chapter 8: Dependency Injection.
| Example | Shows |
|---|---|
| constructors | Services(...) with values, constructors and interface resolution |
| handler-func | Handlers whose arguments are injected |
| request-scoped | Per-request dependencies from the live context |
| initializer | iris.Initializer warm-up, auto-closers, Deferrables |
Book chapter 9: Error Handling.
| Example | Shows |
|---|---|
| central-error-map | Domain sentinels mapped once; handlers just forward errors |
| handle-errorf | errors.HandleErrorf adding call-site detail to a mapped error |
| validation-errors | Field validation and the exact JSON clients receive |
| error-router | errors.NewRouter with handlers that return error |
Book chapter 10: Authentication & Authorization.
| Example | Shows |
|---|---|
| basicauth | HTTP Basic Auth on an admin group |
| api-key | middleware/apikey: Bearer and custom-header keys, hashed keys, a database Lookup |
| jwt-middleware | Signing and verifying tokens, claims, revocation |
| sessions | Typed sessions, secure cookie defaults, RegenerateID after sign-in |
| auth-sdk | The generic auth.Auth[User] SDK: signin, refresh, signout, JWKS |
Book chapter 11: Configuration Management.
| Example | Shows |
|---|---|
| configuration | iris.Options merging, YAML files, SERVER_CONFIG, secrets from the environment |
| configuration-worker | iris.LoadConfiguration and iris.BaseConfiguration, plus an iris.Worker the builder starts and stops |
Book chapter 12: Built-in Middleware (the view engine).
| Example | Shows |
|---|---|
| templates | HTML pages from embedded templates through a layout: blocks.New, view.Handler, view.Render and view.WithTemplate |
Book chapter 13: Database Integration.
| Example | Shows |
|---|---|
| postgres-mapping | The pgerrors opt-in import: no-rows to 404, duplicates to 409, without opening a database |
| pg-crud | A real Postgres behind the seam with kataras/pg: schema from struct tags, a typed repository, Init/Close on the builder, DATABASE_URL |
Book chapter 12: Built-in Middleware (websockets).
| Example | Shows |
|---|---|
| chat | A chat room on neffos: namespaces, connect and custom events, BroadcastOthers, the neffos.js browser client |
Book chapter 16: Testing. Both examples test the same tasks API, so you can read them side by side.
| Example | Shows |
|---|---|
| iris-httptest | The httptest package: fluent requests, JSON/header/cookie assertions, table-driven subtests, fakes through the repository seam |
| std-httptest | The same suite with net/http/httptest only: app.Build() + ServeHTTP, encoding/json, and a real server on a loopback port |
Book chapters 17 to 19: Monitoring & Observability, Security Best Practices, Deployment & DevOps.
| Example | Shows |
|---|---|
| serving-and-tls | Listen vs Run(iris.ServerOptions{...}), TLS files and Let's Encrypt |
| graceful-shutdown | Draining requests and running closers on interrupt |
| observability | Monitor dashboard, pprof and per-request cost behind auth |
Book chapter 24: Advanced Topics; ai-gateway belongs to chapter 21: AI Backends.
| Example | Shows |
|---|---|
| std-interop | iris.FromStd and serving the app as an http.Handler |
| typed-context | Your own context type through iris.NewContextWrapper |
| file-server | Static files with dotfile protection |
| multi-app | Two applications behind one host switcher |
| api-graph | A visual graph of the registered routes |
| sitemap | Generating sitemap.xml from your routes |
| patches | Process-global customization, such as swapping the JSON writer |
| ai-gateway | Relaying an upstream model stream with typed failure classification and failover |
- TUTORIAL.md builds the Bookshelf service of section 01 as a multi-package project.
- The book explains the concepts behind these examples; every section above names its chapter.
- The Code Wiki answers questions about the framework's source in plain language.