mirror of
https://github.com/kataras/iris.git
synced 2025-01-23 10:41:03 +01:00
289 lines
12 KiB
Markdown
289 lines
12 KiB
Markdown
#  Iris
|
|
|
|
Iris is a fast, simple and efficient micro web framework for Go. It provides a beautifully expressive and easy to use foundation for your next website, API, or distributed app.
|
|
|
|
Web applications powered by Iris run everywhere, even [from an android device](https://medium.com/@kataras/how-to-turn-an-android-device-into-a-web-server-9816b28ab199).
|
|
|
|
[](https://travis-ci.org/kataras/iris)
|
|
[](http://goreportcard.com/report/kataras/iris)
|
|
[](https://godoc.org/github.com/kataras/iris)
|
|
[](http://support.iris-go.com)
|
|
[](https://github.com/kataras/iris/tree/master/_examples)
|
|
[](https://kataras.rocket.chat/channel/iris)
|
|
|
|
<!--
|
|
|
|
# Mo, 10 July 2017 | v8.0.0
|
|
|
|
### 📈 One and a half years with Iris and You...
|
|
|
|
- 7070 github stars
|
|
- 749 github forks
|
|
- 1m total views at its documentation
|
|
- ~800$ at donations (there're a lot for a golang open-source project, thanks to you)
|
|
- ~550 reported bugs fixed
|
|
- ~30 community feature requests have been implemented
|
|
|
|
### 🔥 Reborn
|
|
|
|
As you may have heard I have huge responsibilities on my new position at Dubai nowdays, therefore I don't have the needed time to work on this project anymore.
|
|
|
|
After almost a month of negotiations and searching I succeed to find a decent software engineer to continue my work on the open source community.
|
|
|
|
The leadership of this, open-source, repository was transfered to [hiveminded](https://github.com/hiveminded).
|
|
|
|
These types of projects need heart and sacrifices to continue offer the best developer experience like a paid software, please do support him as you did with me!
|
|
|
|
> Please [contact](https://kataras.rocket.chat/channel/iris) with the project team if you want to help at the development process!
|
|
|
|
-->
|
|
|
|
### 🔥 Hot features
|
|
|
|
- Focus on high performance
|
|
- Easy Fluent API
|
|
- Highly customizable
|
|
- Robust routing and middleware ecosystem
|
|
* build RESTful APIs with iris unique expressionist path interpreter
|
|
* dynamic path parameterized or wildcard routes are not conflict with static routes
|
|
* remove trailing slash from the URL with option to redirect
|
|
* virtual hosts and subdomains made easy
|
|
* group API's and static or even dynamic subdomains
|
|
* `net/http` and `negroni-like` handlers are compatible via `iris.FromStd`
|
|
* [learn the reasons that differ from what you've seen so far](_examples/#routing-grouping-dynamic-path-parameters-macros-and-custom-context)
|
|
- Automatically install and serve certificates from https://letsencrypt.org
|
|
- Request-Scoped Transactions
|
|
- Body binding for JSON, XML, Forms, can be extended to use your own custom binders
|
|
- More than 50 handy functions to send HTTP responses
|
|
- View system: supporting more than 6+ template engines, with prerenders. You can still use your favorite
|
|
- Graceful shutdown
|
|
- Limit request body
|
|
- Localization i18N
|
|
- Serve static and embedded files
|
|
- Cache
|
|
- Log requests
|
|
- Customizable format and output for the logger
|
|
- Customizable HTTP errors
|
|
- Compression (Gzip)
|
|
- Authentication
|
|
- OAuth, OAuth2 supporting 27+ popular websites
|
|
- JWT
|
|
- Basic Authentication
|
|
- HTTP Sessions. You can still use your favorite
|
|
- HTTP to HTTPS
|
|
- HTTP to HTTPS WWW
|
|
- Highly scalable rich content render (Markdown, JSON, JSONP, XML...)
|
|
- Websocket-only API similar to socket.io. You can still use your favorite
|
|
- Hot Reload on source code changes[*](https://github.com/kataras/rizla)
|
|
- Typescript integration + Web IDE
|
|
- And many other things that will surprise you
|
|
|
|
<p>
|
|
<img src="https://raw.githubusercontent.com/smallnest/go-web-framework-benchmark/4db507a22c964c9bc9774c5b31afdc199a0fe8b7/benchmark.png" alt="Third-party source for transparency." />
|
|
</p>
|
|
|
|
### 📑 Table of contents
|
|
|
|
<a href="https://github.com/kataras/iris/_examples" alt="documentation and examples">
|
|
<img align="right" src="learn.jpg" width="125" />
|
|
</a>
|
|
|
|
* [Installation](#-installation)
|
|
* [Latest changes](https://github.com/kataras/iris/blob/master/HISTORY.md#su-16-july-2017--v803)
|
|
* [Learn](#-learn)
|
|
* [HTTP Listening](_examples/#http-listening)
|
|
* [Configuration](_examples/#configuration)
|
|
* [Routing, Grouping, Dynamic Path Parameters, "Macros" and Custom Context](_examples/#routing-grouping-dynamic-path-parameters-macros-and-custom-context)
|
|
* [Subdomains](_examples/#subdomains)
|
|
* [Wrap `http.Handler/HandlerFunc`](_examples/#convert-httphandlerhandlerfunc)
|
|
* [View](_examples/#view)
|
|
* [Authentication](_examples/#authentication)
|
|
* [File Server](_examples/#file-server)
|
|
* [How to Read from `context.Request() *http.Request`](_examples/#how-to-read-from-contextrequest-httprequest)
|
|
* [How to Write to `context.ResponseWriter() http.ResponseWriter`](_examples/#how-to-write-to-contextresponsewriter-httpresponsewriter)
|
|
* [Test](_examples/#testing)
|
|
* [Cache](cache/#table-of-contents)
|
|
* [Sessions](sessions/#table-of-contents)
|
|
* [Websockets](websocket/#table-of-contents)
|
|
* [Miscellaneous](_examples/#miscellaneous)
|
|
* [Typescript Automation Tools](typescript/#table-of-contents)
|
|
* [Tutorial: Online Visitors](_examples/tutorial/online-visitors)
|
|
* [Tutorial: URL Shortener using BoltDB](https://medium.com/@kataras/a-url-shortener-service-using-go-iris-and-bolt-4182f0b00ae7)
|
|
* [Tutorial: How to turn your Android Device into a fully featured Web Server](https://medium.com/@kataras/how-to-turn-an-android-device-into-a-web-server-9816b28ab199)
|
|
* [Middleware](middleware/)
|
|
* [Dockerize](https://github.com/iris-contrib/cloud-native-go)
|
|
* [Philosophy](#-philosophy)
|
|
* [Support](#-support)
|
|
* [Versioning](#-version)
|
|
* [When should I upgrade?](#should-i-upgrade-my-iris)
|
|
* [Where can I find older versions?](#where-can-i-find-older-versions)
|
|
* [People](#-people)
|
|
|
|
### 🚀 Installation
|
|
|
|
The only requirement is the [Go Programming Language](https://golang.org/dl/), at least version 1.8
|
|
|
|
```sh
|
|
$ go get -u github.com/kataras/iris
|
|
```
|
|
|
|
> _iris_ takes advantage of the [vendor directory](https://docs.google.com/document/d/1Bz5-UB7g2uPBdOx-rw5t9MxJwkfpx90cqG9AFL0JAYo) feature. You get truly reproducible builds, as this method guards against upstream renames and deletes.
|
|
|
|
```go
|
|
// file: main.go
|
|
package main
|
|
import (
|
|
"github.com/kataras/iris"
|
|
"github.com/kataras/iris/context"
|
|
)
|
|
func main() {
|
|
app := iris.New()
|
|
// Load all templates from the "./templates" folder
|
|
// where extension is ".html" and parse them
|
|
// using the standard `html/template` package.
|
|
app.RegisterView(iris.HTML("./templates", ".html"))
|
|
|
|
// Method: GET
|
|
// Resource: http://localhost:8080
|
|
app.Get("/", func(ctx context.Context) {
|
|
// Bind: {{.message}} with "Hello world!"
|
|
ctx.ViewData("message", "Hello world!")
|
|
// Render template file: ./templates/hello.html
|
|
ctx.View("hello.html")
|
|
})
|
|
|
|
// Start the server using a network address and block.
|
|
app.Run(iris.Addr(":8080"))
|
|
}
|
|
```
|
|
```html
|
|
<!-- file: ./templates/hello.html -->
|
|
<html>
|
|
<head>
|
|
<title>Hello Page</title>
|
|
</head>
|
|
<body>
|
|
<h1>{{.message}}</h1>
|
|
</body>
|
|
</html>
|
|
```
|
|
|
|
```sh
|
|
$ go run main.go
|
|
> Now listening on: http://localhost:8080
|
|
> Application started. Press CTRL+C to shut down.
|
|
```
|
|
|
|
<details>
|
|
<summary>Hello World with Go 1.9</summary>
|
|
|
|
If you've installed Go 1.9 then you can omit the `github.com/kataras/iris/context` package from the imports statement.
|
|
|
|
```go
|
|
// +build go1.9
|
|
|
|
package main
|
|
|
|
import "github.com/kataras/iris"
|
|
|
|
func main() {
|
|
app := iris.New()
|
|
app.RegisterView(iris.HTML("./templates", ".html"))
|
|
|
|
app.Get("/", func(ctx iris.Context) {
|
|
ctx.ViewData("message", "Hello world!")
|
|
ctx.View("hello.html")
|
|
})
|
|
|
|
app.Run(iris.Addr(":8080"))
|
|
}
|
|
```
|
|
|
|
We expect Go version 1.9 to be released in August, however you can install Go 1.9 beta today.
|
|
|
|
### Installing Go 1.9beta2
|
|
|
|
1. Go to https://golang.org/dl/#go1.9beta2
|
|
2. Download a compatible, with your OS, archieve, i.e `go1.9beta2.windows-amd64.zip`
|
|
3. Unzip the contents of `go1.9beta2.windows-amd64.zip/go` folder to your $GOROOT, i.e `C:\Go`
|
|
4. Open a terminal and execute `go version`, it should output the go1.9beta2 version, i.e:
|
|
```sh
|
|
C:\Users\hiveminded>go version
|
|
go version go1.9beta2 windows/amd64
|
|
```
|
|
|
|
</details>
|
|
|
|
<details>
|
|
<summary>Why another new web framework?</summary>
|
|
|
|
_iris_ is easy, it has a familiar API while in the same has far more features than [Gin](https://github.com/gin-gonic/gin) or [Martini](https://github.com/go-martini/martini).
|
|
|
|
You own your code —it will never generate (unfamiliar) code for you, like [Beego](https://github.com/astaxie/beego), [Revel](https://github.com/revel/revel) and [Buffalo](https://github.com/gobuffalo/buffalo) do.
|
|
|
|
It's not just-another-router but its overall performance is equivalent with something like [httprouter](https://github.com/julienschmidt/httprouter).
|
|
|
|
Unlike [fasthttp](https://github.com/valyala/fasthttp), iris provides full HTTP/2 support for free.
|
|
|
|
Compared to the rest open source projects, this one is very active and you get answers almost immediately.
|
|
|
|
</details>
|
|
|
|
### 👥 Community
|
|
|
|
The most useful community repository for _iris_ developers is the
|
|
[iris-contrib/middleware](https://github.com/iris-contrib/middleware) which contains some HTTP handlers that can help you finish a lot of your tasks even easier.
|
|
|
|
```sh
|
|
$ go get -u github.com/iris-contrib/middleware/...
|
|
```
|
|
|
|
> Feel free to put your own middleware there!
|
|
|
|
Join the welcoming community of fellow _iris_ developers in [rocket.chat](https://kataras.rocket.chat/channel/iris).
|
|
|
|
### 📖 Learn
|
|
|
|
The awesome _iris_ community is always adding new examples, [_examples](_examples/) is a great place to get started!
|
|
|
|
Read the [godocs](https://godoc.org/github.com/kataras/iris) for a better understanding.
|
|
|
|
### 🤔 Philosophy
|
|
|
|
The _iris_ philosophy is to provide robust tooling for HTTP, making it a great solution for single page applications, web sites, hybrids, or public HTTP APIs. Keep note that, today, iris is faster than apache+nginx itself.
|
|
|
|
_iris_ does not force you to use any specific ORM. With support for the most popular template engines, websocket server and a fast sessions manager you can quickly craft your perfect application.
|
|
|
|
### 💙 Support
|
|
|
|
- [Post](http://support.iris-go.com) a feature request or report a bug
|
|
- :star: and watch the public [repository](https://github.com/kataras/iris/stargazers), will keep you up to date
|
|
- :earth_americas: publish [an article](https://medium.com/search?q=iris) or share a [tweet](https://twitter.com/hashtag/golang) about your personal experience with iris
|
|
|
|
### 📌 Version
|
|
|
|
Current: **8.0.3**
|
|
|
|
Each new release is pushed to the master. It stays there until the next version. When a next version is released then the previous version goes to its own branch with `gopkg.in` as its import path (and its own vendor folder), in order to keep it working "for-ever".
|
|
|
|
Changelog of the current version can be found at the [HISTORY](HISTORY.md) file.
|
|
|
|
#### Should I upgrade my iris?
|
|
|
|
Developers are not forced to use the latest _iris_ version, they can use any version in production, they can update at any time they want.
|
|
|
|
Testers should upgrade immediately, if you're willing to use _iris_ in production you can wait a little more longer, transaction should be as safe as possible.
|
|
|
|
#### Where can I find older versions?
|
|
|
|
Previous versions can be found at [releases page](https://github.com/kataras/iris/releases).
|
|
|
|
### 🥇 People
|
|
|
|
The original author of _iris_ is [Gerasimos Maropoulos](https://github.com/kataras)
|
|
|
|
The current lead maintainer is [Bill Qeras, Jr.](https://github.com/hiveminded)
|
|
|
|
[List of all contributors](https://github.com/kataras/iris/graphs/contributors)
|
|
|
|
[](https://www.paypal.com/cgi-bin/webscr?cmd=_donations&business=kataras2006%40hotmail%2ecom&lc=GR&item_name=Iris%20web%20framework&item_number=iriswebframeworkdonationid2016¤cy_code=EUR&bn=PP%2dDonationsBF%3abtn_donateCC_LG%2egif%3aNonHosted) |