kararas_iris/README_ZH_HANS.md

新闻

🚀 Iris v14 即将到来。 下一个大版本是本项目历史上最大的一次发布：基于 Go 泛型重建的框架、由编译器检查的应用构建器、替你完成校验的请求辅助函数、统一的错误映射表、三十个内置中间件，以及随仓库一同发布的一本书。详情见下方的 Iris v14 带来了什么。

这里介绍的 v12 仍然可用，也仍在持续修复。v14 使用新的 import 路径，所以它发布的那天，你这边不会有任何东西被破坏。

Iris Web Framework English العربية

⚡ Iris 是基于 Go 编写的一个快速、简单但功能齐全且非常高效的 Web 框架。

✨ 它为您的下一个网站或 API 提供了非常富有表现力且易于使用的基础。

🌟 看看其他人如何评价 Iris，同时欢迎为此开源项目点亮 star

package main

import "github.com/kataras/iris/v12"

func main() {
  app := iris.New()
  app.Use(iris.Compression)

  app.Get("/", func(ctx iris.Context) {
    ctx.HTML("Hello <strong>%s</strong>!", "World")
  })

  app.Listen(":8080")
}

正如一位 Go 开发者所说，Iris 面面俱到，多年来始终坚挺 ⭐

Iris 提供的部分功能：

• HTTP/2（Push，甚至支持内嵌数据）
• 中间件（Accesslog、Basicauth、CORS、gRPC、防机器人 hCaptcha、JWT、MethodOverride、ModRevision、Monitor、PPROF、Ratelimit、防机器人 reCaptcha、Recovery、RequestID、Rewrite）
• API 版本管理
• Model-View-Controller
• Websockets
• gRPC
• 自动 HTTPS
• 内置 ngrok 支持，把应用发布到公网最快的方式
• 独特的路由，支持把动态路径作为参数，内置 :uuid、:string、:int 等标准类型，也可以自定义
• 压缩
• 视图引擎（HTML、Django、Handlebars、Pug/Jade 等）
• 构建自己的文件服务器，托管自己的 WebDAV 服务
• 缓存
• 本地化（i18n、sitemap）
• 会话（Sessions）
• 丰富的响应（HTML、Text、Markdown、XML、YAML、Binary、JSON、JSONP、Protocol Buffers、MessagePack、内容协商、流式传输、Server-Sent Events 等）
• 响应压缩（gzip、deflate、brotli、snappy、s2）
• 丰富的请求（绑定 URL Query、Headers、Form、Text、XML、YAML、Binary、JSON、校验、Protocol Buffers、MessagePack 等）
• 依赖注入（MVC、Handlers、API Routers）
• 测试套件
• 以及最重要的一点……从第一天到今天，你都能得到快速的回复和支持

🚀 Iris v14 带来了什么

Iris v14 是本项目历史上最大的一次发布。它把框架重建在 Go 泛型之上，也改变了一个应用的组装方式：main 里的接线更少，处理函数更短，那些以前散落在每条路由上的决定，现在只在一个地方做。

这些今天都不需要你操心。v12 继续可用，继续收到修复，而 v14 会带着一份覆盖每个重命名和移除 API 的迁移指南一起到来。

整个应用写在一条由编译器检查的链里

iris.NewBuilder 用一个表达式把 CORS、压缩、访问日志、健康检查端点、错误映射表、你的服务和 API 分组连接起来。步骤顺序由编译器强制，所以应用要么正确构建，要么根本编译不过。

iris.NewBuilder().
    Prefix("/api").
    AllowOrigin("*").
    Compression(true).
    LogRequests(true).
    Health(true, "production", "kataras").
    Errors(errors.NewOptions().
        MapErrors(errors.NotFound, catalog.ErrNotFound)).
    Services(catalog.NewRepository, catalog.NewService).
    API("/products", api.NewProductsAPI).
    Build().
    Listen(":8080")

处理函数不再重复自己

解码、校验和错误渲染都搬出了处理函数的函数体。rest.ReadJSON[T] 解码请求，如果你的类型实现了 Validate() error 就顺带执行它，并自己写出 400。响应辅助函数写出成功状态码，或者写出你的中央映射表为该错误指定的响应。

func (api *ProductsAPI) create(ctx iris.Context) {
    input, ok := rest.ReadJSON[catalog.ProductInput](ctx)
    if !ok {
        return // 400 已写出：JSON 格式错误，或 Validate 未通过。
    }

    id, err := api.svc.Create(ctx, input)
    rest.Created(ctx, id, err) // 201，或集中映射后的错误。
}

rest.OK、rest.NoContent、rest.Count 和 rest.Paginated 覆盖了 API 返回的其余形态。

错误只声明一次

新的 rest/errors 包保存着从你的领域错误到 HTTP 响应的映射。客户端拿到规范的、机器可读的响应体。内部信息留在内部。注册一个 collector，每一次失败都会从同一个地方进入你的日志或数据库。错误可以渲染为 JSON，也可以渲染为视图，取决于客户端想要什么。

依赖注入无处不在，不再只属于 MVC

构造函数声明自己需要什么，容器负责提供：处理函数、API 分组、控制器都一样。实现了 Init(ctx context.Context) error 的服务会在 Build() 内部执行一次。可关闭的资源会在关停时关闭。hero 包不再存在，取而代之的是 dep 和 rest，用更少的代码做更多的事。MVC 控制器建立在泛型之上。

包都在你以为它们该在的地方

sessions、cache、websocket、i18n、view 和 versioning 都成了中间件。mvc 移到了 controller 之下，与新的 fileserver、sitemap 和 apigraph 控制器并列。apigraph 会把你的路由树画成一张可交互的 D3 图。

框架内置三十个中间件，其中包括这些新成员：httpcost（每个请求的时间、内存和 CPU，用于性能分析或计费）、bodylimit、compress、counter、referrer、geolocation、ipaccess 和 servertiming。视图引擎的实现迁移到了 iris-contrib/views。

配置是一个部分字面量

iris.Configuration 和那些 With* 配置器由 iris.Options 取代。只写你关心的字段，其余的来自默认值。Bind 先从 SERVER_CONFIG 环境变量读取 YAML，然后再从文件读取。

app := iris.New(iris.Options{Name: "myapp", LogLevel: "debug"})

名字如实说明它在做什么

读请求头和设置响应头不再共用一个会悄悄改变含义的前缀：ctx.Header 读取请求，而 ctx.SetHeader 和 ctx.ResponseHeader 作用于响应。Party 现在叫 Router。ctx.URLParam 现在是 ctx.Query().Get。每一处重命名都连同替代写法列在迁移指南里，其中大多数只需一次查找替换。

默认就是安全的

会话 cookie 默认带上 Secure 和 SameSite=Lax。请求体大小限制在所有读取路径上都会生效。重建的过程中也顺手解决了一批老问题，其中包括一个只记录限制却从不真正执行的限流器，以及一次可能把整个进程带走的 Logout 调用。

可以从头读到尾的文档

v14 附带一本收录在仓库里的 23 章图书、一份用单篇文档写出带测试的 REST API 的入门教程、一份面向 v12 应用的迁移指南，以及一个由源码生成、可以回答代码库问题的实时 AI wiki。

这对你的 v12 代码意味着什么

import 路径变为 github.com/kataras/iris/v14，因此 v12 和 v14 可以并存，发布当天不会有任何东西被破坏。什么时候升级由你决定。迁移指南覆盖 import 路径、包的移动、每一个被移除的 API 及其替代品，以及行为上的变化，机械的部分还给出了可直接执行的命令。

目前还没有公开的发布日期。关注 releases 或者 @iris_framework，第一时间收到消息。

👑 赞助者

有了你们的帮助，我们可以让开源 Web 开发对所有人都更好！

📖 开始学习 Iris

安装

唯一的要求是 Go 编程语言。

创建新项目

$ mkdir myapp
$ cd myapp
$ go mod init myapp
$ go get github.com/kataras/iris/v12@latest # 或 @v12.2.11

在已有项目中安装

$ cd myapp
$ go get github.com/kataras/iris/v12@latest

运行

$ go mod tidy -compat=1.23 # windows 下用 -compat="1.23"。
$ go run .

Iris 有完整且详尽的 使用文档，让您可以轻松地上手此框架。

要了解更详细的技术文档，请访问我们的 godocs。如果想要寻找可运行的示例代码，可以到仓库的 ./_examples 子目录下获取。

用 Plexon AI 开发

Plexon AI 是 Hellenic Development 推出的跨平台 AI 编程助手，它内置了一个专门的 Iris 技能（skill）：一份由框架作者亲自撰写的 v14 开发指南，包含十九篇参考文档，覆盖路由与宏、context API、rest 辅助函数、错误处理、全部三十个中间件、内置控制器、认证 SDK、安全加固、数据持久化、缓存、i18n、可观测性、性能、测试、部署，以及从 v12 到 v14 的迁移。

安装 Software Developer 人格（persona），Iris 技能会随之而来，与它启用的一批工程类 agent 并列。这样一来，助手写出的 Iris 代码就是框架本该被使用的样子，而不是靠训练时见过的零碎印象去猜。

你喜欢在旅行时阅读吗？

您可以立即获取 Iris 电子书（新版）的 PDF 版本和在线访问权限，并参与到 Iris 的开发中。

🙌 贡献

我们欢迎您为 Iris 框架做出贡献！想要知道如何为 Iris 项目做贡献，请查看 CONTRIBUTING.md。

贡献者名单

🛡 安全漏洞

如果您在 Iris 中发现安全漏洞，请发送电子邮件至 iris-go@outlook.com。所有安全漏洞将会得到及时解决。

📝 开源协议（License）

就像 Go 语言本身一样，此项目也采用 BSD 3-clause license。

项目名称 "Iris" 的灵感来自于希腊神话。