mirror of https://github.com/gofiber/fiber.git
parent
2c7bdb9fd1
commit
7cddb84b21
|
@ -4,15 +4,15 @@ id: welcome
|
|||
title: 👋 Welcome
|
||||
sidebar_position: 1
|
||||
---
|
||||
An online API documentation with examples so you can start building web apps with Fiber right away!
|
||||
Welcome to the online API documentation for Fiber, complete with examples to help you start building web applications with Fiber right away!
|
||||
|
||||
**Fiber** is an [Express](https://github.com/expressjs/express) inspired **web framework** built on top of [Fasthttp](https://github.com/valyala/fasthttp), the **fastest** HTTP engine for [Go](https://go.dev/doc/). Designed to **ease** things up for **fast** development with **zero memory allocation** and **performance** in mind.
|
||||
**Fiber** is an [Express](https://github.com/expressjs/express)-inspired **web framework** built on top of [Fasthttp](https://github.com/valyala/fasthttp), the **fastest** HTTP engine for [Go](https://go.dev/doc/). It is designed to facilitate rapid development with **zero memory allocations** and a strong focus on **performance**.
|
||||
|
||||
These docs are for **Fiber v3**, which was released on **March XX, 2024**.
|
||||
These docs are for **Fiber v3**, which was released on **Month xx, 202x**.
|
||||
|
||||
### Installation
|
||||
|
||||
First of all, [download](https://go.dev/dl/) and install Go. `1.22` or higher is required.
|
||||
First, [download](https://go.dev/dl/) and install Go. Version `1.22` or higher is required.
|
||||
|
||||
Installation is done using the [`go get`](https://pkg.go.dev/cmd/go/#hdr-Add_dependencies_to_current_module_and_install_them) command:
|
||||
|
||||
|
@ -22,7 +22,7 @@ go get github.com/gofiber/fiber/v3
|
|||
|
||||
### Zero Allocation
|
||||
|
||||
Fiber is optimized for **high-performance**, meaning values returned from **fiber.Ctx** are **not** immutable by default and **will** be re-used across requests. As a rule of thumb, you **must** only use context values within the handler and **must not** keep any references. Once you return from the handler, any values obtained from the context will be re-used in future requests. Here is an example:
|
||||
Fiber is optimized for **high performance**, meaning values returned from **fiber.Ctx** are **not** immutable by default and **will** be reused across requests. As a rule of thumb, you **must** only use context values within the handler and **must not** keep any references. Once you return from the handler, any values obtained from the context will be reused in future requests. Here is an example:
|
||||
|
||||
```go
|
||||
func handler(c fiber.Ctx) error {
|
||||
|
@ -44,13 +44,13 @@ func handler(c fiber.Ctx) error {
|
|||
buffer := make([]byte, len(result))
|
||||
copy(buffer, result)
|
||||
resultCopy := string(buffer)
|
||||
// Variable is now valid forever
|
||||
// Variable is now valid indefinitely
|
||||
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
We created a custom `CopyString` function that does the above and is available under [gofiber/utils](https://github.com/gofiber/utils).
|
||||
We created a custom `CopyString` function that performs the above and is available under [gofiber/utils](https://github.com/gofiber/utils).
|
||||
|
||||
```go
|
||||
app.Get("/:foo", func(c fiber.Ctx) error {
|
||||
|
@ -61,7 +61,7 @@ app.Get("/:foo", func(c fiber.Ctx) error {
|
|||
})
|
||||
```
|
||||
|
||||
Alternatively, you can also use the `Immutable` setting. It will make all values returned from the context immutable, allowing you to persist them anywhere. Of course, this comes at the cost of performance.
|
||||
Alternatively, you can enable the `Immutable` setting. This makes all values returned from the context immutable, allowing you to persist them anywhere. Note that this comes at the cost of performance.
|
||||
|
||||
```go
|
||||
app := fiber.New(fiber.Config{
|
||||
|
@ -69,11 +69,11 @@ app := fiber.New(fiber.Config{
|
|||
})
|
||||
```
|
||||
|
||||
For more information, please check [**\#426**](https://github.com/gofiber/fiber/issues/426), [**\#185**](https://github.com/gofiber/fiber/issues/185) and [**\#3012**](https://github.com/gofiber/fiber/issues/3012).
|
||||
For more information, please refer to [#426](https://github.com/gofiber/fiber/issues/426), [#185](https://github.com/gofiber/fiber/issues/185), and [#3012](https://github.com/gofiber/fiber/issues/3012).
|
||||
|
||||
### Hello, World
|
||||
|
||||
Embedded below is essentially the most straightforward **Fiber** app you can create:
|
||||
Below is the most straightforward **Fiber** application you can create:
|
||||
|
||||
```go
|
||||
package main
|
||||
|
@ -95,15 +95,15 @@ func main() {
|
|||
go run server.go
|
||||
```
|
||||
|
||||
Browse to `http://localhost:3000` and you should see `Hello, World!` on the page.
|
||||
Browse to `http://localhost:3000` and you should see `Hello, World!` displayed on the page.
|
||||
|
||||
### Basic routing
|
||||
### Basic Routing
|
||||
|
||||
Routing refers to determining how an application responds to a client request to a particular endpoint, which is a URI (or path) and a specific HTTP request method (`GET`, `PUT`, `POST`, etc.).
|
||||
Routing determines how an application responds to a client request to a particular endpoint, which is a URI (or path) and a specific HTTP request method (`GET`, `PUT`, `POST`, etc.).
|
||||
|
||||
Each route can have **multiple handler functions** that are executed when the route is matched.
|
||||
|
||||
Route definition takes the following structures:
|
||||
Route definitions follow the structure below:
|
||||
|
||||
```go
|
||||
// Function signature
|
||||
|
@ -115,10 +115,10 @@ app.Method(path string, ...func(fiber.Ctx) error)
|
|||
- `path` is a virtual path on the server
|
||||
- `func(fiber.Ctx) error` is a callback function containing the [Context](https://docs.gofiber.io/api/ctx) executed when the route is matched
|
||||
|
||||
#### Simple route
|
||||
#### Simple Route
|
||||
|
||||
```go
|
||||
// Respond with "Hello, World!" on root path, "/"
|
||||
// Respond with "Hello, World!" on root path "/"
|
||||
app.Get("/", func(c fiber.Ctx) error {
|
||||
return c.SendString("Hello, World!")
|
||||
})
|
||||
|
@ -131,11 +131,11 @@ app.Get("/", func(c fiber.Ctx) error {
|
|||
|
||||
app.Get("/:value", func(c fiber.Ctx) error {
|
||||
return c.SendString("value: " + c.Params("value"))
|
||||
// => Get request with value: hello world
|
||||
// => Response: "value: hello world"
|
||||
})
|
||||
```
|
||||
|
||||
#### Optional parameter
|
||||
#### Optional Parameter
|
||||
|
||||
```go
|
||||
// GET http://localhost:3000/john
|
||||
|
@ -143,9 +143,10 @@ app.Get("/:value", func(c fiber.Ctx) error {
|
|||
app.Get("/:name?", func(c fiber.Ctx) error {
|
||||
if c.Params("name") != "" {
|
||||
return c.SendString("Hello " + c.Params("name"))
|
||||
// => Hello john
|
||||
// => Response: "Hello john"
|
||||
}
|
||||
return c.SendString("Where is john?")
|
||||
// => Response: "Where is john?"
|
||||
})
|
||||
```
|
||||
|
||||
|
@ -156,27 +157,33 @@ app.Get("/:name?", func(c fiber.Ctx) error {
|
|||
|
||||
app.Get("/api/*", func(c fiber.Ctx) error {
|
||||
return c.SendString("API path: " + c.Params("*"))
|
||||
// => API path: user/john
|
||||
// => Response: "API path: user/john"
|
||||
})
|
||||
```
|
||||
|
||||
### Static files
|
||||
### Static Files
|
||||
|
||||
To serve static files such as **images**, **CSS**, and **JavaScript** files, replace your function handler with a file or directory string.
|
||||
You can check out [static middleware](./middleware/static.md) for more information.
|
||||
Function signature:
|
||||
To serve static files such as **images**, **CSS**, and **JavaScript** files, use the `Static` method with a directory path. For more information, refer to the [static middleware](./middleware/static.md).
|
||||
|
||||
Use the following code to serve files in a directory named `./public`:
|
||||
|
||||
```go
|
||||
app := fiber.New()
|
||||
package main
|
||||
|
||||
app.Get("/*", static.New("./public"))
|
||||
import (
|
||||
"github.com/gofiber/fiber/v3"
|
||||
)
|
||||
|
||||
app.Listen(":3000")
|
||||
func main() {
|
||||
app := fiber.New()
|
||||
|
||||
app.Static("/", "./public")
|
||||
|
||||
app.Listen(":3000")
|
||||
}
|
||||
```
|
||||
|
||||
Now, you can load the files that are in the `./public` directory:
|
||||
Now, you can access the files in the `./public` directory via your browser:
|
||||
|
||||
```bash
|
||||
http://localhost:3000/hello.html
|
||||
|
|
Loading…
Reference in New Issue