首页
/ 2025全新指南：用Wisp构建高性能Gleam Web应用的实战指南

2025全新指南：用Wisp构建高性能Gleam Web应用的实战指南

2026-01-19 10:20:06作者：范垣楠Rhoda
wisp
🧚 A practical web framework for Gleam
项目地址：https://gitcode.com/gh_mirrors/wisp3/wisp

你是否还在为Gleam语言缺乏成熟Web框架而苦恼？是否在寻找兼顾开发效率与运行性能的解决方案？本文将带你深入探索Wisp——这款专为Gleam打造的实用Web框架，通过10个核心场景示例和500行实战代码，让你在30分钟内从零掌握高性能Web应用开发。

为什么选择Wisp？Gleam生态的Web开发革新

Gleam作为一门强类型函数式编程语言，凭借其优雅的语法和强大的类型系统，正在函数式编程社区迅速崛起。然而，Web开发框架的缺失一直是其生态系统的短板——直到Wisp的出现。

Wisp（发音/wɪsp/，意为"小精灵"）是一个专注于实用性的Gleam Web框架，它借鉴了Elixir Phoenix和Rust Axum的设计理念，同时充分发挥Gleam的类型安全优势。其核心优势包括：

  • 极简API设计：通过"处理器(Handler) + 中间件(Middleware)"双概念模型，降低认知负担
  • 原生类型安全：利用Gleam的类型系统消除常见的Web开发错误
  • 零成本抽象：高性能运行时，无额外性能开销
  • 丰富中间件生态：内置日志、路由、静态文件服务等必备功能
classDiagram
    class Request {
        +method: Method
        +path: String
        +headers: List(Header)
        +body: String
    }
    
    class Response {
        +status: Int
        +headers: List(Header)
        +body: String
    }
    
    class Handler {
        <<function>>
        +handle(request: Request, context: Context): Response
    }
    
    class Middleware {
        <<function>>
        +wrap(handler: Handler): Handler
    }
    
    Handler --> Request
    Handler --> Response
    Middleware --> Handler

快速入门：5分钟搭建你的第一个Wisp应用

环境准备

在开始前，请确保你的系统已安装：

  • Erlang/OTP 25+
  • Gleam 1.0+
  • rebar3 3.19+

通过以下命令创建新项目：

gleam new my_wisp_app && cd my_wisp_app
gleam add wisp

核心概念：处理器(Handler)详解

处理器是Wisp应用的核心，它是一个接收HTTP请求(Request)并返回HTTP响应(Response)的函数。处理器还可以接收其他参数，例如应用程序定义的"上下文(Context)"类型，用于存储数据库连接或用户会话等状态。

import wisp.{type Request, type Response}

// 定义应用上下文
pub type Context {
  Context(secret_key: String, db_connection: String)
}

// 基础处理器实现
pub fn home_handler(request: Request, context: Context) -> Response {
  wisp.html("""
    <!DOCTYPE html>
    <html>
      <head><title>Wisp Example</title></head>
      <body>
        <h1>Hello from Wisp!</h1>
        <p>Secret key: <%= context.secret_key %></p>
      </body>
    </html>
  """)
}

中间件(Middleware)：功能扩展的艺术

中间件是一个接收处理器作为参数并返回新处理器的函数，用于实现横切关注点(cross-cutting concerns)。Wisp利用Gleam的use语法实现优雅的中间件链。

import wisp.{type Request, type Response}

pub fn handle_request(request: Request, context: Context) -> Response {
  // 日志中间件：记录请求信息
  use <- wisp.log_request(request)
  
  // 静态文件服务中间件：从/public目录提供/static路径下的文件
  use <- wisp.serve_static(request, under: "/static", from: "priv/static")
  
  // 认证中间件：验证API密钥
  use <- wisp.require_header(request, "X-API-Key", context.secret_key)
  
  // 最终响应
  wisp.json(%{
    "status": "ok",
    "message": "Hello from Wisp!",
    "time": wisp.current_time()
  })
}

路由系统：构建RESTful API的基石

Wisp的路由系统允许你将不同的URL路径映射到对应的处理器函数。以下是一个完整的路由示例：

import wisp/router.{type Router}
import wisp.{type Request, type Response}

pub fn setup_routes() -> Router(Request, Response) {
  let router = router.new()
  
  // 基础路由
  |> router.get("/", home_handler)
  
  // 路径参数
  |> router.get("/users/:id", user_handler)
  
  // 嵌套路由组
  |> router.group("/api", fn(router) {
    router
    |> router.post("/login", auth_handler)
    |> router.get("/profile", profile_handler)
  })
  
  // 带查询参数的路由
  |> router.get("/search", search_handler)
}

// 路径参数处理器实现
pub fn user_handler(request: Request) -> Response {
  let user_id = router.param(request, "id")
  case user_id {
    Ok(id) -> wisp.text("User ID: " <> id)
    Error(_) -> wisp.bad_request()
  }
}

// 查询参数处理器实现
pub fn search_handler(request: Request) -> Response {
  let query = router.query(request, "q")
  wisp.json(%{"query" => query, "results" => search_database(query)})
}

flowchart TD
    A[客户端请求] --> B{路由系统}
    B -->|GET /| C[home_handler]
    B -->|GET /users/:id| D[user_handler]
    B -->|POST /api/login| E[auth_handler]
    B -->|GET /search?q=...| F[search_handler]
    C --> G[返回HTML响应]
    D --> H[返回用户数据]
    E --> I[返回认证令牌]
    F --> J[返回搜索结果]

数据持久化：与数据库交互的最佳实践

Wisp不绑定特定的数据库ORM，而是鼓励使用Gleam生态中的专用库。以下是使用pg库与PostgreSQL交互的示例：

import pg
import wisp.{type Request, type Response}

// 定义数据模型
pub type User {
  User(id: Int, name: String, email: String)
}

// 数据库上下文
pub type DbContext {
  DbContext(connection: pg.Connection)
}

// 获取所有用户
pub fn list_users(request: Request, context: DbContext) -> Response {
  case pg.query(context.connection, "SELECT id, name, email FROM users") {
    Ok(rows) -> {
      let users = rows
                  |> list.map(fn(row) {
                    User(
                      id: pg.int_from_row(row, 0),
                      name: pg.string_from_row(row, 1),
                      email: pg.string_from_row(row, 2)
                    )
                  })
      wisp.json(users)
    }
    Error(e) -> {
      wisp.internal_server_error("Database error: " <> pg.error_to_string(e))
    }
  }
}

// 创建新用户
pub fn create_user(request: Request, context: DbContext) -> Response {
  use body <- wisp.json_body(request)
  case body {
    Ok(data) -> {
      let name = map.get(data, "name")
      let email = map.get(data, "email")
      
      case pg.execute(
        context.connection,
        "INSERT INTO users (name, email) VALUES ($1, $2) RETURNING id",
        [pg.Text(name), pg.Text(email)]
      ) {
        Ok(result) -> wisp.created("User created with ID: " <> pg.last_insert_id(result))
        Error(e) -> wisp.internal_server_error(pg.error_to_string(e))
      }
    }
    Error(_) -> wisp.bad_request("Invalid JSON body")
  }
}

高级功能：从理论到实践

1. 处理Cookie与会话管理

pub fn handle_session(request: Request) -> Response {
  // 读取Cookie
  let theme = wisp.get_cookie(request, "theme")
  
  // 设置Cookie
  wisp.ok()
  |> wisp.set_cookie("session_id", generate_session_id(), max_age: 86400)
  |> wisp.set_cookie("theme", "dark", max_age: 30*86400, secure: true, http_only: true)
}

2. 文件上传处理

pub fn handle_upload(request: Request) -> Response {
  use files <- wisp.multipart_form_data(request)
  
  case files {
    Ok(form_data) -> {
      let avatar = form_data |> list.find(fn(field) { field.name == "avatar" })
      
      case avatar {
        Some(file) -> {
          let save_result = file.content
                           |> file.write_to("uploads/" <> file.filename)
          
          case save_result {
            Ok(_) -> wisp.ok("File uploaded: " <> file.filename)
            Error(_) -> wisp.internal_server_error("Failed to save file")
          }
        }
        None -> wisp.bad_request("No avatar file provided")
      }
    }
    Error(_) -> wisp.bad_request("Invalid multipart data")
  }
}

3. 错误处理与日志

pub fn error_handling_example(request: Request) -> Response {
  use <- wisp.catch_errors(request, fn(error) {
    // 自定义错误响应
    wisp.internal_server_error("An error occurred: " <> error_to_string(error))
  })
  
  // 日志示例
  wisp.log_info("Processing request: " <> request.path)
  
  // 模拟可能出错的操作
  risky_operation()
  wisp.ok()
}

部署Wisp应用：从开发到生产

使用Docker容器化

创建Dockerfile：

FROM gleamlang/gleam:latest AS builder

WORKDIR /app
COPY . .
RUN gleam build --target erlang

FROM erlang:25-alpine

WORKDIR /app
COPY --from=builder /app/build/erlang /app
COPY --from=builder /app/gleam.toml /app

CMD ["./build/erlang/start.sh"]

部署到Fly.io

创建fly.toml：

app = "my-wisp-app"
primary_region = "ord"

[http_service]
  internal_port = 3000
  force_https = true
  auto_stop_machines = true
  auto_start_machines = true

部署命令：

fly launch
fly deploy

Wisp生态系统与资源

推荐库

功能 库 描述
数据库 gleam-pg PostgreSQL客户端
模板引擎 gleam-heex HEEx模板渲染
JSON处理 gleam-json JSON解析与生成
身份验证 gleam-jwt JWT实现
测试 gleam-wisp-test Wisp专用测试工具

学习资源

结语：开启Gleam Web开发之旅

Wisp框架为Gleam语言带来了实用、高效的Web开发体验。通过其简洁的API设计和强大的类型安全保障，你可以构建出既可靠又易于维护的Web应用。

无论你是函数式编程新手，还是有经验的开发者，Wisp都能为你提供愉悦的开发体验。立即行动起来：

# 克隆仓库
git clone https://gitcode.com/gh_mirrors/wisp3/wisp

# 运行示例
cd wisp/examples/hello_world
gleam run

开始你的Wisp之旅，构建下一个高性能Web应用！

timeline
    title Wisp学习路径
    0分钟 : 环境搭建与项目创建
    10分钟 : 理解处理器与中间件
    20分钟 : 实现基础路由与控制器
    30分钟 : 添加数据库交互
    45分钟 : 实现认证与会话管理
    60分钟 : 部署到生产环境

希望本文能帮助你快速掌握Wisp框架的核心概念和使用方法。如有任何问题或建议，欢迎参与Wisp社区讨论！

wisp
🧚 A practical web framework for Gleam
项目地址：https://gitcode.com/gh_mirrors/wisp3/wisp
登录后查看全文

相关内容推荐

1 Gleam项目中的JavaScript目标导入检查问题分析2 Gleam 包管理器版本解析机制解析3 探索Pterodactyl/WISP Docker镜像：为游戏服务器管理开启新纪元4 Gleam交互式数据可视化Python教程5 Puter项目v2.5.1版本发布：增强网络功能与开发体验6 在Neovim中配置Gleam语言服务器（LSP）的完整指南7 Gleam：用Python轻松构建交互式数据可视化8 Gleam语言构建系统与现有Erlang项目的集成挑战9 Gleam语言中"Extract Variable"重构功能的边界条件分析10 探索未来模组开发的利器：owo-lib
热门项目推荐
相关项目推荐

热门内容推荐

1 【亲测免费】 开源项目 `build-your-own-x` 使用指南2 【亲测免费】 探索科技之旅：《Build Your Own X》项目详解

最新内容推荐

py2exe：Python 3 的独立可执行文件生成工具【亲测免费】 mingw-w64-x86-64-V8.1.0-win32-seh离线安装包 【亲测免费】 华炎魔方低代码平台 - Steedos Platform 开源项目快速入门指南【亲测免费】 鼠标键盘录制和自动化操作工具【亲测免费】 ViennaRNA 开源项目指南 Python+OpenCV实现车牌检测与识别【亲测免费】 Holistically-Nested Edge Detection (HED) 项目使用教程【免费下载】 博途辅助工具：利用Openness API自动生成程序 计算机组成原理：自己动手画CPU 实训代码【亲测免费】 笔记本自带键盘一键禁用启用

项目优选

收起
kernelkernel
deepin linux kernel
C
27
11
docsdocs
OpenHarmony documentation | OpenHarmony开发者文档
Dockerfile
496
3.64 K
pytorchpytorch
Ascend Extension for PyTorch
Python
300
338
kernelkernel
openEuler内核是openEuler操作系统的核心，既是系统性能与稳定性的基石，也是连接处理器、设备与服务的桥梁。
C
307
131
ops-mathops-math
本项目是CANN提供的数学类基础计算算子库，实现网络在NPU上加速计算。
C++
868
479
flutter_flutterflutter_flutter
暂无简介
Dart
744
180
ohos_react_nativeohos_react_native
React Native鸿蒙化仓库
JavaScript
297
346
nop-entropynop-entropy
Nop Platform 2.0是基于可逆计算理论实现的采用面向语言编程范式的新一代低代码开发平台，包含基于全新原理从零开始研发的GraphQL引擎、ORM引擎、工作流引擎、报表引擎、规则引擎、批处理引引擎等完整设计。nop-entropy是它的后端部分，采用java语言实现，可选择集成Spring框架或者Quarkus框架。中小企业可以免费商用
Java
11
1
leetcodeleetcode
🔥LeetCode solutions in any programming language | 多种编程语言实现 LeetCode、《剑指 Offer（第 2 版）》、《程序员面试金典（第 6 版）》题解
Java
66
20
cangjie_compilercangjie_compiler
仓颉编译器源码及 cjdb 调试工具。
C++
150
882