Skip to content

Latest commit

 

History

History
725 lines (561 loc) · 49.9 KB

README_zh-TW.md

File metadata and controls

725 lines (561 loc) · 49.9 KB

Fiber

Fiber 是款啟發自 ExpressWeb 框架,建基於 Fasthttp——Go最快的 HTTP 引擎。設計旨在 減輕 快速開發的負擔,兼顧 零記憶體分配效能

⚡️ 快速入門

package main

import "github.com/gofiber/fiber/v2"

func main() {
    app := fiber.New()

    app.Get("/", func(c *fiber.Ctx) error {
        return c.SendString("Hello, World 👋!")
    })

    app.Listen(":3000")
}

🤖 效能評定結果

這些測試由 TechEmpowerGo Web 框架效能測試 完成。若需參閱所有結果,請參閱我們的 Wiki 資訊。

⚙️ 安裝

先確定您已經安裝 1.17 或更新版本的 Go(點此下載)。

要初始化專案,首先建立檔案夾,然後在檔案夾中執行 go mod init github.com/名稱/儲存庫深入了解)。接著,使用 go get 命令安裝 Fiber:

go get -u github.com/gofiber/fiber/v2

🎯 特色

💡 設計哲學

Node.js 轉到 Go 的新進 Go 開發者,得先面對 Go 的各種知識點,才能開始建構自己的 Web 應用程式或微服務。Fiber 作為一款 Web 框架,設計之初便以 極簡主義 為理念,並遵循 UNIX 之道,讓新進 Go 開發者能夠快速隨著友善且值得信賴的社群,進入 Go 的世界。

Fiber 啟發自 Express——網際網路上最知名的 Web 框架,我們將 Express 的 易用性 和 Go 的 原始效能 結合在一起。如果您曾經在 Node.js(使用 Express 或類似框架)實作過 Web 應用程式,那麼許多方法和開發準則,將讓您感到 無比熟悉

我們 傾聽 使用者在 Issues、Discord 群組網路上任何角落 的意見和建議,製作出 快速靈活易於上手 的 Go Web 框架,來應對任何工作、繳件期限以及開發者的能力區間——如同 Express 在 JavaScript 世界所扮演的角色一樣!

⚠️ 限制

  • 由於 Fiber 有用到 Unsafe,本函式庫有時可能無法相容最新版的 Go 語言。Fiber 2.40.0 已在 Go 1.17 至 1.21 的版本測試過。
  • Fiber 不相容 net/http 的介面,意味著您無法使用像是 gqlgen、go-swagger 或其他任何屬於 net/http 生態系統的專案。

👀 範例

下方列出一些常見範例。如果您想查看更多程式碼範例,請參閱我們的 Recipes 儲存庫,或前往我們提供的 API 文件

func main() {
    app := fiber.New()

    // GET /api/register
    app.Get("/api/*", func(c *fiber.Ctx) error {
        msg := fmt.Sprintf("✋ %s", c.Params("*"))
        return c.SendString(msg) // => ✋ register
    })

    // GET /flights/LAX-SFO
    app.Get("/flights/:from-:to", func(c *fiber.Ctx) error {
        msg := fmt.Sprintf("💸 從:%s,到:%s", c.Params("from"), c.Params("to"))
        return c.SendString(msg) // => 💸 從:LAX,到:SFO
    })

    // GET /dictionary.txt
    app.Get("/:file.:ext", func(c *fiber.Ctx) error {
        msg := fmt.Sprintf("📃 %s.%s", c.Params("file"), c.Params("ext"))
        return c.SendString(msg) // => 📃 dictionary.txt
    })

    // GET /john/75
    app.Get("/:name/:age/:gender?", func(c *fiber.Ctx) error {
        msg := fmt.Sprintf("👴 %s 已經 %s 歲了", c.Params("name"), c.Params("age"))
        return c.SendString(msg) // => 👴 john 已經 75 歲了
    })

    // GET /john
    app.Get("/:name", func(c *fiber.Ctx) error {
        msg := fmt.Sprintf("哈囉,%s 👋!", c.Params("name"))
        return c.SendString(msg) // => 哈囉,john 👋!
    })

    log.Fatal(app.Listen(":3000"))
}
func main() {
    app := fiber.New()

    // GET /api/register
    app.Get("/api/*", func(c *fiber.Ctx) error {
        msg := fmt.Sprintf("✋ %s", c.Params("*"))
        return c.SendString(msg) // => ✋ register
    }).Name("api")

    data, _ := json.MarshalIndent(app.GetRoute("api"), "", "  ")
    fmt.Print(string(data))
    // 會輸出:
    // {
    //    "method": "GET",
    //    "name": "api",
    //    "path": "/api/*",
    //    "params": [
    //      "*1"
    //    ]
    // }


    log.Fatal(app.Listen(":3000"))
}
func main() {
    app := fiber.New()

    app.Static("/", "./public")
    // => http://localhost:3000/js/script.js
    // => http://localhost:3000/css/style.css

    app.Static("/prefix", "./public")
    // => http://localhost:3000/prefix/js/script.js
    // => http://localhost:3000/prefix/css/style.css

    app.Static("*", "./public/index.html")
    // => http://localhost:3000/any/path/shows/index/html

    log.Fatal(app.Listen(":3000"))
}
func main() {
    app := fiber.New()

    // 符合任何路由
    app.Use(func(c *fiber.Ctx) error {
        fmt.Println("🥇 第一個處理常式")
        return c.Next()
    })

    // 符合所有 /api 開頭的路由
    app.Use("/api", func(c *fiber.Ctx) error {
        fmt.Println("🥈 第二個處理常式")
        return c.Next()
    })

    // GET /api/list
    app.Get("/api/list", func(c *fiber.Ctx) error {
        fmt.Println("🥉 最後一個處理常式")
        return c.SendString("Hello, World 👋!")
    })

    log.Fatal(app.Listen(":3000"))
}
📚 展示更多程式碼範例

檢視引擎

📖 組態設定 📖 引擎 📖 轉譯 (render)

若未指定檢視引擎,Fiber 預設採用 html/template

如果您想執行部分檢視 (partials),或者是使用如 amberhandlebarsmustachepug 等等不同的引擎……

請參考我們的 Template 套件——它支援多種檢視引擎。

package main

import (
    "github.com/gofiber/fiber/v2"
    "github.com/gofiber/template/pug"
)

func main() {
    // 您可以在 app 初始化前設定檢視 (Views) 引擎:
    app := fiber.New(fiber.Config{
        Views: pug.New("./views", ".pug"),
    })

    // 現在,您可以用下面這種方式呼叫 `./views/home.pug` 樣板:
    app.Get("/", func(c *fiber.Ctx) error {
        return c.Render("home", fiber.Map{
            "title": "Homepage",
            "year":  1999,
        })
    })

    log.Fatal(app.Listen(":3000"))
}

組合路由鏈

📖 分組

func middleware(c *fiber.Ctx) error {
    fmt.Println("不要理我!")
    return c.Next()
}

func handler(c *fiber.Ctx) error {
    return c.SendString(c.Path())
}

func main() {
    app := fiber.New()

    // 根 API 路由
    api := app.Group("/api", middleware) // /api

    // API v1 路由
    v1 := api.Group("/v1", middleware) // /api/v1
    v1.Get("/list", handler)           // /api/v1/list
    v1.Get("/user", handler)           // /api/v1/user

    // API v2 路由
    v2 := api.Group("/v2", middleware) // /api/v2
    v2.Get("/list", handler)           // /api/v2/list
    v2.Get("/user", handler)           // /api/v2/user

    // ...
}

中介模組記錄器

📖 記錄器

package main

import (
    "log"

    "github.com/gofiber/fiber/v2"
    "github.com/gofiber/fiber/v2/middleware/logger"
)

func main() {
    app := fiber.New()

    app.Use(logger.New())

    // ...

    log.Fatal(app.Listen(":3000"))
}

跨原始來源資源共用 (CORS)

📖 CORS

import (
    "log"

    "github.com/gofiber/fiber/v2"
    "github.com/gofiber/fiber/v2/middleware/cors"
)

func main() {
    app := fiber.New()

    app.Use(cors.New())

    // ...

    log.Fatal(app.Listen(":3000"))
}

Origin 標頭傳入任何網域來檢查 CORS 的效果:

curl -H "Origin: http://example.com" --verbose http://localhost:3000

自訂 404 回應

📖 HTTP 方法

func main() {
    app := fiber.New()

    app.Static("/", "./public")

    app.Get("/demo", func(c *fiber.Ctx) error {
        return c.SendString("This is a demo!")
    })

    app.Post("/register", func(c *fiber.Ctx) error {
        return c.SendString("Welcome!")
    })

    // 最後一個中介模組,符合所有條件
    app.Use(func(c *fiber.Ctx) error {
        return c.SendStatus(404)
        // => 404 "Not Found"
    })

    log.Fatal(app.Listen(":3000"))
}

JSON 回應

📖 JSON

type User struct {
    Name string `json:"name"`
    Age  int    `json:"age"`
}

func main() {
    app := fiber.New()

    app.Get("/user", func(c *fiber.Ctx) error {
        return c.JSON(&User{"John", 20})
        // => {"name":"John", "age":20}
    })

    app.Get("/json", func(c *fiber.Ctx) error {
        return c.JSON(fiber.Map{
            "success": true,
            "message": "Hi John!",
        })
        // => {"success":true, "message":"Hi John!"}
    })

    log.Fatal(app.Listen(":3000"))
}

WebSocket 升級 (Upgrade)

📖 Websocket

import (
    "github.com/gofiber/fiber/v2"
    "github.com/gofiber/fiber/v2/middleware/websocket"
)

func main() {
  app := fiber.New()

  app.Get("/ws", websocket.New(func(c *websocket.Conn) {
    for {
      mt, msg, err := c.ReadMessage()
      if err != nil {
        log.Println("read:", err)
        break
      }
      log.Printf("recv: %s", msg)
      err = c.WriteMessage(mt, msg)
      if err != nil {
        log.Println("write:", err)
        break
      }
    }
  }))

  log.Fatal(app.Listen(":3000"))
  // ws://localhost:3000/ws
}

Server-Sent Events

📖 更多資訊

import (
    "github.com/gofiber/fiber/v2"
    "github.com/valyala/fasthttp"
)

func main() {
  app := fiber.New()

  app.Get("/sse", func(c *fiber.Ctx) error {
    c.Set("Content-Type", "text/event-stream")
    c.Set("Cache-Control", "no-cache")
    c.Set("Connection", "keep-alive")
    c.Set("Transfer-Encoding", "chunked")

    c.Context().SetBodyStreamWriter(fasthttp.StreamWriter(func(w *bufio.Writer) {
      fmt.Println("WRITER")
      var i int

      for {
        i++
        msg := fmt.Sprintf("%d - 目前時間為 %v", i, time.Now())
        fmt.Fprintf(w, "data: 訊息: %s\n\n", msg)
        fmt.Println(msg)

        w.Flush()
        time.Sleep(5 * time.Second)
      }
    }))

    return nil
  })

  log.Fatal(app.Listen(":3000"))
}

Recover 中介模組

📖 Recover

import (
    "github.com/gofiber/fiber/v2"
    "github.com/gofiber/fiber/v2/middleware/recover"
)

func main() {
    app := fiber.New()

    app.Use(recover.New())

    app.Get("/", func(c *fiber.Ctx) error {
        panic("正常來說,這會導致 app 當機")
    })

    log.Fatal(app.Listen(":3000"))
}

使用信任的代理伺服器

📖 組態設定

import (
    "github.com/gofiber/fiber/v2"
    "github.com/gofiber/fiber/v2/middleware/recover"
)

func main() {
    app := fiber.New(fiber.Config{
        EnableTrustedProxyCheck: true,
        TrustedProxies: []string{"0.0.0.0", "1.1.1.1/30"}, // IP 地址或 IP 地址區間
        ProxyHeader: fiber.HeaderXForwardedFor,
    })

    // ...

    log.Fatal(app.Listen(":3000"))
}

🧬 內建中介模組

這裡列出了 Fiber 框架內建的中介模組。

中介模組 描述
basicauth 提供 HTTP Basic 認證的基本認證中介模組。如果憑證有效,則會呼叫接續函式 (next);如果沒有憑證或失效,則回傳 401 Unauthorized。
cache 攔截並快取回應。
compress 適用於 Fiber 的壓縮中介模組。預設支援 deflategzipbrotli
cors 啟用跨來源資源共用 (CORS),可調整多種選項。
csrf 保護資源防止 CSRF 利用。
encryptcookie 加密中介模組,會將 Cookie 的值進行加密。
envvar 公開環境變數,並提供可調整設定。
etag ETag 中介模組,讓快取更高效,同時因為 Web 伺服器不需要在內容未更動時重新傳送完整請求,因此可以減少流量使用。
expvar Expvar 中介模組,透過其 HTTP 伺服器執行階段,提供 JSON 格式的公用變數。
favicon 不輸出 Favicons 請求記錄;若有提供檔案路徑,則從記憶體提供圖示。
filesystem 適用於 Fiber 的檔案系統中介模組。特別銘謝 Alireza Salary!
limiter 適用於 Fiber 的速率限制中介模組。用來限制傳入公開 API 或者(以及)端點(如密碼重設)的重複請求。
logger HTTP 請求/回應記錄工具。
monitor 監控中介模組,用來回報伺服器指標。啟發自 express-status-monitor。
pprof 特別感謝 Matthew Lee (@mthli)
proxy 讓您可以將請求代理 (proxy) 至多台伺服器。
recover Recover 中介模組:可以從呼叫堆疊鏈中任何部分的當機 (panic) 中復原,並將控制權交由中央的 錯誤處理常式 (ErrorHandler) 處理。
requestid 為每個請求加上 requestid。
session 連線階段中介模組。注意:這個中介模組有用到我們的 Storage 套件。
skip 略過中介模組,會在條件成立時略過封裝過的處理常式。
timeout 為請求加上最長時限,並在逾時後轉送至錯誤處理常式 (ErrorHandler)。
keyauth Key auth 中介模組提供以金鑰為基礎的認證模式。
redirect 用來重新導向的中介模組。
rewrite 重寫 (Rewrite) 中介模組:根據提供規則重寫 URL 路徑,適合用來向後相容,或者是製作更乾淨且更好懂的連結。
adaptor 將 net/http 處理常式轉換至 Fiber 處理常式,或者是反著做。特別感謝 @arsmn!
helmet 透過設定多種 HTTP 標頭,協助保護您應用程式的安全。

🧬 外掛中介模組

這裡列出由 Fiber 團隊 維護、存放在外部的中介模組。

中介模組 描述
jwt JWT 回傳 JSON Web Token (JWT) 認證中介模組。
storage 已經做好,實作 Storage 介面的儲存區驅動模組,設計用來與各種 Fiber 中介模組搭配使用。
template 本套件包含 8 種樣板引擎,可以和 Fiber v1.10.x 一起使用。需要 Go 1.13 或更新版本。
websocket 適用於 Fiber,建基於 Fasthttp 的 WebSocket。支援本機空間 (Locals)!

🕶️ Awesome List

更多文章、中介模組、範例或工具,請參考我們的 Awesome List

👍 貢獻

如果您想和我們 道謝,或者是支持 Fiber 繼續積極開發下去(也可以兩個都做):

  1. 送給專案一顆 GitHub 星星
  2. 在您的 𝕏 (Twitter) 上發出關於本專案的推文。
  3. MediumDev.to 或者是個人部落格上寫下評論或教學。
  4. 捐專案 一杯咖啡的費用 以示支持。

☕ 支持者

Fiber 是個仰賴捐款的開放原始碼專案——用來支付如域名、Gitbook、Netlify 和無服務器運算服務的費用。如果您想支持 Fiber,可以在 ☕ 這裡捐杯咖啡

使用者 捐款
@destari ☕ x 10
@dembygenesis ☕ x 5
@thomasvvugt ☕ x 5
@hendratommy ☕ x 5
@ekaputra07 ☕ x 5
@jorgefuertes ☕ x 5
@candidosales ☕ x 5
@l0nax ☕ x 3
@bihe ☕ x 3
@justdave ☕ x 3
@koddr ☕ x 1
@lapolinar ☕ x 1
@diegowifi ☕ x 1
@ssimk0 ☕ x 1
@raymayemir ☕ x 1
@melkorm ☕ x 1
@marvinjwendt ☕ x 1
@toishy ☕ x 1

‎‍💻 程式碼貢獻者

Code Contributors

⭐️ 收藏數

Stargazers over time

⚠️ 授權條款

著作權所有 (c) 2019-現在 Fenny貢獻者Fiber 是款依照 MIT License 授權,免費且開放原始碼的軟體。官方圖示 (logo) 由 Vic Shóstak 製作,並依據 創用 CC 授權條款散佈 (CC BY-SA 4.0 International)。

第三方函式庫的授權條款