kararas_iris/README_ZH_HANT.md

新聞

🚀 Iris v14 即將登場。 下一個主要版本是本專案史上規模最大的一次發行：以 Go 泛型重建的框架、由編譯器把關的應用程式建構器、替你完成驗證的請求輔助函式、單一的錯誤對應表、三十個內建中介軟體，以及一本隨儲存庫一起發行的書。詳情請見下方的 Iris v14 帶來什麼。

這裡介紹的 v12 仍然可用，也仍持續收到修正。v14 會走新的 import 路徑，所以它發行的那天，你這邊不會有任何東西壞掉。

Iris Web 框架 English العربية

⚡ Iris 是款不僅迅速、簡捷，並且功能完善、高效率的 Go 語言 Web 框架。

✨ 它能為你的下一個網站或 API，立下漂亮、富有表達性，且易於使用的基礎。

🌟 看看其他人怎麼評價 Iris，也歡迎為這個開源專案點一顆 星星

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("哈囉，<strong>%s</strong>！", "世界")
  })

  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。每一處更名都連同替代寫法列在移轉指南裡，而且大多數只需要一次搜尋取代。

預設就是安全的

Session 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 Web 框架的貢獻！想知道如何為 Iris 專案貢獻，請參閱 CONTRIBUTING.md。

所有貢獻者名單

🛡 安全漏洞

如果你在 Iris 中發現安全漏洞，請寄送電子郵件至 iris-go@outlook.com。所有安全漏洞都會盡速處理。

📝 授權條款

本專案採用 BSD 3-clause 授權條款，與 Go 專案本身相同。

專案名稱「Iris」的靈感來自希臘神話。