mirror of
https://github.com/kataras/iris.git
synced 2025-01-23 18:51:03 +01:00
241 lines
12 KiB
Markdown
241 lines
12 KiB
Markdown
[](https://support.eji.org/give/153413/#!/donation/checkout)
|
||
|
||
<!-- # News -->
|
||
|
||
> This is the under-**development branch**. Stay tuned for the upcoming release [v12.2.0](HISTORY.md#Next). Looking for a stable release? Head over to the [v12.1.8 branch](https://github.com/kataras/iris/tree/v12.1.8) instead.
|
||
>
|
||
>  Try the official [Iris Command Line Interface](https://github.com/kataras/iris-cli) today!
|
||
|
||
<!--  Iris version **12.1.8** has been [released](HISTORY.md#su-16-february-2020--v1218)! -->
|
||
|
||
# Iris Web Framework <a href="README_GR.md"><img width="20px" src="https://iris-go.com/images/flag-greece.svg" /></a> <a href="README_FR.md"><img width="20px" src="https://iris-go.com/images/flag-france.svg" /></a> <a href="README_ZH.md"><img width="20px" src="https://iris-go.com/images/flag-china.svg" /></a> <a href="README_ES.md"><img width="20px" src="https://iris-go.com/images/flag-spain.png" /></a> <a href="README_FA.md"><img width="20px" src="https://iris-go.com/images/flag-iran.svg" /></a> <a href="README_RU.md"><img width="20px" src="https://iris-go.com/images/flag-russia.svg" /></a> <a href="README_KO.md"><img width="20px" src="https://iris-go.com/images/flag-south-korea.svg?v=12" /></a>
|
||
|
||
[](https://travis-ci.org/kataras/iris) [](https://github.com/kataras/iris/tree/master/_examples) [](https://gitter.im/iris_go/community) <!--[](https://app.fossa.io/projects/git%2Bgithub.com%2Fkataras%2Firis?ref=badge_shield)--> [](https://iris-go.com/donate) <!--[](https://goreportcard.com/report/github.com/kataras/iris)--><!--[](https://pkg.go.dev/github.com/kataras/iris/v12@v12.2.0)--> <!-- [](https://github.com/kataras/iris/releases) -->
|
||
|
||
<!-- <a href="https://iris-go.com"> <img align="right" src="https://iris-go.com/images/logo-w169.png"></a> -->
|
||
|
||
Iris is a fast, simple yet fully featured and very efficient web framework for Go.
|
||
|
||
It provides a beautifully expressive and easy to use foundation for your next website or API.
|
||
|
||
Learn what [others saying about Iris](https://iris-go.com/testimonials/) and **[star](https://github.com/kataras/iris/stargazers)** this open-source project to support its potentials.
|
||
|
||
[](https://iris-go.com/testimonials/)
|
||
|
||
[](https://github.com/kataras/server-benchmarks)
|
||
|
||
## 👑 <a href="https://www.paypal.com/cgi-bin/webscr?cmd=_donations&business=7DPAYRDR28MMJ&item_name=Iris+Web+Framework¤cy_code=EUR&source=url">Supporters</a>
|
||
|
||
<p>
|
||
<a href="https://github.com/sumjoe"><img src="https://avatars1.githubusercontent.com/u/32655210?v=4" alt ="Joseph De Paola" title="sumjoe" with="75" style="width:75px;max-width:75px;height:75px" height="75" /></a>
|
||
<a href="https://github.com/AlbinoGeek"><img src="https://avatars1.githubusercontent.com/u/1910461?v=4" alt ="Damon Blais" title="AlbinoGeek" with="75" style="width:75px;max-width:75px;height:75px" height="75" /></a>
|
||
<a href="https://github.com/LYF123123"><img src="https://avatars1.githubusercontent.com/u/33317812?v=4" alt ="陆 轶丰" title="LYF123123" with="75" style="width:75px;max-width:75px;height:75px" height="75" /></a>
|
||
<a href="https://github.com/xiaozhuai"><img src="https://avatars1.githubusercontent.com/u/4773701?v=4" alt ="Weihang Ding" title="xiaozhuai" with="75" style="width:75px;max-width:75px;height:75px" height="75" /></a>
|
||
<a href="https://github.com/fangli"><img src="https://avatars1.githubusercontent.com/u/3032639?v=4" alt ="Li Fang" title="fangli" with="75" style="width:75px;max-width:75px;height:75px" height="75" /></a>
|
||
<a href="https://github.com/TechMaster"><img src="https://avatars1.githubusercontent.com/u/1491686?v=4" alt ="TechMaster" title="TechMaster" with="75" style="width:75px;max-width:75px;height:75px" height="75" /></a>
|
||
<a href="https://github.com/lensesio"><img src="https://avatars1.githubusercontent.com/u/11728472?v=4" alt ="lenses.io" title="lensesio" with="75" style="width:75px;max-width:75px;height:75px" height="75" /></a>
|
||
<a href="https://github.com/celsosz"><img src="https://avatars1.githubusercontent.com/u/3466493?v=4" alt ="Celso Souza" title="celsosz" with="75" style="width:75px;max-width:75px;height:75px" height="75" /></a>
|
||
<a href="https://github.com/altafino"><img src="https://avatars1.githubusercontent.com/u/24539467?v=4" alt ="Altafino" title="altafino" with="75" style="width:75px;max-width:75px;height:75px" height="75" /></a>
|
||
<a href="https://github.com/thomasfr"><img src="https://avatars1.githubusercontent.com/u/287432?v=4" alt ="Thomas Fritz" title="thomasfr" with="75" style="width:75px;max-width:75px;height:75px" height="75" /></a>
|
||
<a href="https://github.com/hengestone"><img src="https://avatars1.githubusercontent.com/u/362587?v=4" alt ="Conrad Steenberg" title="hengestone" with="75" style="width:75px;max-width:75px;height:75px" height="75" /></a>
|
||
<a href="https://github.com/se77en"><img src="https://avatars1.githubusercontent.com/u/1468284?v=4" alt ="Damon Zhao" title="se77en" with="75" style="width:75px;max-width:75px;height:75px" height="75" /></a>
|
||
<a href="https://github.com/International"><img src="https://avatars1.githubusercontent.com/u/1022918?v=4" alt ="George Opritescu" title="International" with="75" style="width:75px;max-width:75px;height:75px" height="75" /></a>
|
||
<a href="https://github.com/Juanses"><img src="https://avatars1.githubusercontent.com/u/6137970?v=4" alt ="Juanses" title="Juanses" with="75" style="width:75px;max-width:75px;height:75px" height="75" /></a>
|
||
<a href="https://github.com/ansrivas"><img src="https://avatars1.githubusercontent.com/u/1695056?v=4" alt ="Ankur Srivastava" title="ansrivas" with="75" style="width:75px;max-width:75px;height:75px" height="75" /></a>
|
||
<a href="https://github.com/lexrus"><img src="https://avatars1.githubusercontent.com/u/219689?v=4" alt ="Lex Tang" title="lexrus" with="75" style="width:75px;max-width:75px;height:75px" height="75" /></a>
|
||
<a href="https://github.com/li3p"><img src="https://avatars1.githubusercontent.com/u/55519?v=4" alt ="li3p" title="li3p" with="75" style="width:75px;max-width:75px;height:75px" height="75" /></a>
|
||
</p>
|
||
|
||
## 📖 Learning Iris
|
||
|
||
```sh
|
||
# https://github.com/kataras/iris/wiki/Installation
|
||
$ go get github.com/kataras/iris/v12@master
|
||
# assume the following code in main.go file
|
||
$ cat main.go
|
||
```
|
||
|
||
```go
|
||
package main
|
||
|
||
import "github.com/kataras/iris/v12"
|
||
|
||
func main() {
|
||
app := iris.New()
|
||
|
||
booksAPI := app.Party("/books")
|
||
{
|
||
booksAPI.Use(iris.Compression)
|
||
|
||
// GET: http://localhost:8080/books
|
||
booksAPI.Get("/", list)
|
||
// POST: http://localhost:8080/books
|
||
booksAPI.Post("/", create)
|
||
}
|
||
|
||
app.Listen(":8080")
|
||
}
|
||
|
||
// Book example.
|
||
type Book struct {
|
||
Title string `json:"title"`
|
||
}
|
||
|
||
func list(ctx iris.Context) {
|
||
books := []Book{
|
||
{"Mastering Concurrency in Go"},
|
||
{"Go Design Patterns"},
|
||
{"Black Hat Go"},
|
||
}
|
||
|
||
ctx.JSON(books)
|
||
// TIP: negotiate the response between server's prioritizes
|
||
// and client's requirements, instead of ctx.JSON:
|
||
// ctx.Negotiation().JSON().MsgPack().Protobuf()
|
||
// ctx.Negotiate(books)
|
||
}
|
||
|
||
func create(ctx iris.Context) {
|
||
var b Book
|
||
err := ctx.ReadJSON(&b)
|
||
// TIP: use ctx.ReadBody(&b) to bind
|
||
// any type of incoming data instead.
|
||
if err != nil {
|
||
ctx.StopWithProblem(iris.StatusBadRequest, iris.NewProblem().
|
||
Title("Book creation failure").DetailErr(err))
|
||
// TIP: use ctx.StopWithError(code, err) when only
|
||
// plain text responses are expected on errors.
|
||
return
|
||
}
|
||
|
||
println("Received Book: " + b.Title)
|
||
|
||
ctx.StatusCode(iris.StatusCreated)
|
||
}
|
||
```
|
||
|
||
**MVC** equivalent:
|
||
|
||
```go
|
||
import "github.com/kataras/iris/v12/mvc"
|
||
```
|
||
|
||
```go
|
||
m := mvc.New(booksAPI)
|
||
m.Handle(new(BookController))
|
||
```
|
||
|
||
```go
|
||
type BookController struct {
|
||
/* dependencies */
|
||
}
|
||
|
||
// GET: http://localhost:8080/books
|
||
func (c *BookController) Get() []Book {
|
||
return []Book{
|
||
{"Mastering Concurrency in Go"},
|
||
{"Go Design Patterns"},
|
||
{"Black Hat Go"},
|
||
}
|
||
}
|
||
|
||
// POST: http://localhost:8080/books
|
||
func (c *BookController) Post(b Book) int {
|
||
println("Received Book: " + b.Title)
|
||
|
||
return iris.StatusCreated
|
||
}
|
||
```
|
||
|
||
**Run** your Iris web server:
|
||
|
||
```sh
|
||
$ go run main.go
|
||
> Now listening on: http://localhost:8080
|
||
> Application started. Press CTRL+C to shut down.
|
||
```
|
||
|
||
**List** Books:
|
||
|
||
```sh
|
||
$ curl --header 'Accept-Encoding:gzip' http://localhost:8080/books
|
||
|
||
[
|
||
{
|
||
"title": "Mastering Concurrency in Go"
|
||
},
|
||
{
|
||
"title": "Go Design Patterns"
|
||
},
|
||
{
|
||
"title": "Black Hat Go"
|
||
}
|
||
]
|
||
```
|
||
|
||
**Create** a new Book:
|
||
|
||
```sh
|
||
$ curl -i -X POST \
|
||
--header 'Content-Encoding:gzip' \
|
||
--header 'Content-Type:application/json' \
|
||
--data "{\"title\":\"Writing An Interpreter In Go\"}" \
|
||
http://localhost:8080/books
|
||
|
||
> HTTP/1.1 201 Created
|
||
```
|
||
|
||
That's how an **error** response looks like:
|
||
|
||
```sh
|
||
$ curl -X POST --data "{\"title\" \"not valid one\"}" \
|
||
http://localhost:8080/books
|
||
|
||
> HTTP/1.1 400 Bad Request
|
||
|
||
{
|
||
"status": 400,
|
||
"title": "Book creation failure"
|
||
"detail": "invalid character '\"' after object key",
|
||
}
|
||
```
|
||
|
||
</details>
|
||
|
||
[](https://bit.ly/2YJeSZe)
|
||
|
||
Iris contains extensive and thorough **[wiki](https://github.com/kataras/iris/wiki)** making it easy to get started with the framework.
|
||
|
||
<!--  -->
|
||
|
||
For a more detailed technical documentation you can head over to our [godocs](https://godoc.org/github.com/kataras/iris). And for executable code you can always visit the [./_examples](_examples) repository's subdirectory.
|
||
|
||
### Do you like to read while traveling?
|
||
|
||
<a href="https://iris-go.com/#book"> <img alt="Book cover" src="https://iris-go.com/images/iris-book-cover-sm.jpg?v=12" /> </a>
|
||
|
||
[](https://twitter.com/intent/follow?screen_name=iris_framework)
|
||
|
||
[](https://www.facebook.com/iris.framework)
|
||
|
||
You can [request](https://www.iris-go.com/#ebookDonateForm) a PDF version and online access of the **E-Book** today and be participated in the development of Iris.
|
||
|
||
## 🙌 Contributing
|
||
|
||
We'd love to see your contribution to the Iris Web Framework! For more information about contributing to the Iris project please check the [CONTRIBUTING.md](CONTRIBUTING.md) file.
|
||
|
||
[List of all Contributors](https://github.com/kataras/iris/graphs/contributors)
|
||
|
||
## 🛡 Security Vulnerabilities
|
||
|
||
If you discover a security vulnerability within Iris, please send an e-mail to [iris-go@outlook.com](mailto:iris-go@outlook.com). All security vulnerabilities will be promptly addressed.
|
||
|
||
## 📝 License
|
||
|
||
This project is licensed under the [BSD 3-clause license](LICENSE), just like the Go project itself.
|
||
|
||
The project name "Iris" was inspired by the Greek mythology.
|
||
<!-- ## Stargazers over time
|
||
|
||
[](https://starchart.cc/kataras/iris) -->
|