GOMODULES
/
fiber
mirror of https://github.com/gofiber/fiber.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

📚 Doc: Update intro documentation (#3204) 

Auto update intro documentation
pull/3193/head^2
Juan Calderon-Perez 2024-11-13 07:11:09 -05:00 committed by GitHub
parent 2c7bdb9fd1
commit 7cddb84b21
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 35 additions and 28 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

63
docs/intro.md
View File

@ -4,15 +4,15 @@ id: welcome
title: 👋 Welcome title: 👋 Welcome
sidebar_position: 1 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 ### 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: 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 ### 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 ```go
func handler(c fiber.Ctx) error { func handler(c fiber.Ctx) error {
@ -44,13 +44,13 @@ func handler(c fiber.Ctx) error {
buffer := make([]byte, len(result)) buffer := make([]byte, len(result))
copy(buffer, result) copy(buffer, result)
resultCopy := string(buffer) 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 ```go
app.Get("/:foo", func(c fiber.Ctx) error { 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 ```go
app := fiber.New(fiber.Config{ 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 ### 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 ```go
package main package main
@ -95,15 +95,15 @@ func main() {
go run server.go 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. 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 ```go
// Function signature // Function signature
@ -115,10 +115,10 @@ app.Method(path string, ...func(fiber.Ctx) error)
- `path` is a virtual path on the server - `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 - `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 ```go
// Respond with "Hello, World!" on root path, "/" // Respond with "Hello, World!" on root path "/"
app.Get("/", func(c fiber.Ctx) error { app.Get("/", func(c fiber.Ctx) error {
return c.SendString("Hello, World!") return c.SendString("Hello, World!")
}) })
@ -131,11 +131,11 @@ app.Get("/", func(c fiber.Ctx) error {
app.Get("/:value", func(c fiber.Ctx) error { app.Get("/:value", func(c fiber.Ctx) error {
return c.SendString("value: " + c.Params("value")) return c.SendString("value: " + c.Params("value"))
// => Get request with value: hello world // => Response: "value: hello world"
}) })
``` ```
#### Optional parameter #### Optional Parameter
```go ```go
// GET http://localhost:3000/john // 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 { app.Get("/:name?", func(c fiber.Ctx) error {
if c.Params("name") != "" { if c.Params("name") != "" {
return c.SendString("Hello " + c.Params("name")) return c.SendString("Hello " + c.Params("name"))
// => Hello john // => Response: "Hello john"
} }
return c.SendString("Where is 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 { app.Get("/api/*", func(c fiber.Ctx) error {
return c.SendString("API path: " + c.Params("*")) 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. 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).
You can check out [static middleware](./middleware/static.md) for more information.
Function signature:
Use the following code to serve files in a directory named `./public`: Use the following code to serve files in a directory named `./public`:
```go ```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 ```bash
http://localhost:3000/hello.html http://localhost:3000/hello.html