Overview

Mizu is built to feel like Go itself: clear, small, and easy to understand. It adds only the essential tools needed to build real web applications while keeping everything familiar. You still use standard library types and patterns, but with a simpler structure for routing, context, and middleware.

The Request Lifecycle

When a request arrives at your Mizu application, it flows through these components:

Request → App → Middleware → Router → Handler → Response
                    ↑                    ↓
                    ←───────────────────←

Each component has a specific role:

Component	Description
App	Owns the HTTP server, manages startup and shutdown
Middleware	Pre/post-processing for requests (logging, auth, etc.)
Router	Matches URL patterns to handlers
Handler	Your code that processes requests
Context (Ctx)	Wraps request/response with helpers

Core Components

App

Server lifecycle, configuration, and health checks.

Routing

URL patterns, path parameters, and route groups.

Handler

Functions that process requests and return responses.

Context

Request/response wrapper with helper methods.

Data Flow

Request

Reading path params, query strings, headers, and body.

Response

Sending JSON, HTML, files, and streaming data.

Cross-Cutting Concerns

Middleware

Composable request processing pipelines.

Error Handling

Centralized error handling and panic recovery.

Logging

Structured logging with Go’s slog package.

Static Files

Serving images, CSS, JavaScript, and embedded files.

How They Work Together

Here’s a minimal example showing all core concepts:

package main

import (
    "time"
    "github.com/go-mizu/mizu"
)

func main() {
    // App: manages server lifecycle
    app := mizu.New()

    // Middleware: processes every request
    app.Use(func(next mizu.Handler) mizu.Handler {
        return func(c *mizu.Ctx) error {
            start := time.Now()
            err := next(c)
            c.Logger().Info("request", "duration", time.Since(start))
            return err
        }
    })

    // Router + Handler: maps URL to your code
    app.Get("/users/{id}", func(c *mizu.Ctx) error {
        // Context: access request data and send response
        id := c.Param("id")
        return c.JSON(200, map[string]string{"id": id})
    })

    // App: start the server
    app.Listen(":3000")
}

Learning Path

For the best learning experience, follow this order:

App - Understand the server lifecycle
Routing - Learn URL pattern matching
Handler - Write request processing logic
Context - Master the request/response wrapper
Request and Response - Data in and out
Middleware - Add cross-cutting behavior
Error and Logging - Handle problems gracefully

Getting Started

Core Concepts

Building Your App

Deployment

Learn More

Overview

The Request Lifecycle

Core Components

App

Routing

Handler

Context

Data Flow

Request

Response

Cross-Cutting Concerns

Middleware

Error Handling

Logging

Static Files

How They Work Together

Learning Path

​The Request Lifecycle

​Core Components

App

Routing

Handler

Context

​Data Flow

Request

Response

​Cross-Cutting Concerns

Middleware

Error Handling

Logging

Static Files

​How They Work Together

​Learning Path

The Request Lifecycle

Core Components

Data Flow

Cross-Cutting Concerns

How They Work Together

Learning Path