为什么选择 farrow-http?

🎯 一份让你爱上类型安全 Web 开发的现代教程 🚀 从零开始,带你玩转 TypeScript Web 框架

---

开篇：为什么要用 farrow-http?

想象一下,你正在用 Express.js 开发 API。有个路由是这样的:

// 😱 Express.js 的日常困扰
app.get('/users/:id', (req, res) => {
  const id = req.params.id  // 这是 string 还是 number? 天知道!
  const user = getUserById(id)

  if (user) {
    res.json(user)
  }
  // 💀 糟了,忘记处理 user 不存在的情况
  // 客户端会永远等待响应...
})

现在,让 farrow-http 来拯救你:

// ✨ farrow-http 的优雅方式
app.get('/users/<id:int>').use((req) => {
  const user = getUserById(req.params.id)  // id 自动推导为 number 类型!

  if (!user) {
    return Response.status(404).json({ error: '用户不存在' })
  }

  return Response.json(user)  // 编译器强制要求返回响应!
})

三大杀手锏:

1. 类型安全到牙齿 - URL 模式自动推导类型,编译器帮你查错
2. 自动验证 - Schema 定义即验证规则,告别手动检查
3. 强制返回 - 函数式中间件必须返回 Response,再也不会忘记响应

---

Hello World (30秒上手)

安装依赖

npm install farrow-http farrow-schema farrow-pipeline
# 或
pnpm add farrow-http farrow-schema farrow-pipeline

第一个 API

import { Http, Response } from 'farrow-http'

const app = Http()

app.get('/').use(() => {
  return Response.json({ message: 'Hello farrow-http! 🎉' })
})

app.listen(3000, () => {
  console.log('🚀 服务器启动: http://localhost:3000')
})

访问 http://localhost:3000,你会看到:

{ "message": "Hello farrow-http! 🎉" }

这就完了? 是的! 3 行代码,一个 API 服务就跑起来了。

核心优势

1. 类型安全的路由

// 路径参数自动推导类型
app.get('/users/<id:int>').use((req) => {
  req.params.id  // 类型: number,已验证为整数
  return Response.json({ userId: req.params.id })
})

// 查询参数自动推导
app.get('/search?<q:string>&<page?:int>').use((req) => {
  req.query.q     // 类型: string (必需)
  req.query.page  // 类型: number | undefined (可选)
  return Response.json({ query: req.query.q })
})

2. Schema 自动验证

import { ObjectType, String, Int } from 'farrow-schema'

class CreateUserInput extends ObjectType {
  name = String
  age = Int
}

app.post('/users', { body: CreateUserInput }).use((req) => {
  // req.body 已经过验证,类型安全!
  const { name, age } = req.body
  return Response.status(201).json({ name, age })
})

3. 函数式中间件

// 洋葱模型,必须返回 Response
app.use((req, next) => {
  console.log('请求前')
  const response = next(req)
  console.log('请求后')
  return response  // 必须返回!
})

与 Express 对比

特性	Express	farrow-http
类型安全	❌ 手动断言	✅ 自动推导
运行时验证	❌ 手写验证	✅ Schema 自动验证
强制返回	❌ 容易忘记	✅ 编译器强制
URL 参数类型	❌ 全是字符串	✅ 支持 int/float/boolean 等
中间件模型	回调地狱	纯函数 + 洋葱模型
异步支持	async/await	async/await + Pipeline

快速示例

import { Http, Response } from 'farrow-http'
import { ObjectType, String, Int } from 'farrow-schema'

const app = Http()

// 1. 简单路由
app.get('/').use(() => {
  return Response.json({ message: 'Welcome' })
})

// 2. 路径参数
app.get('/users/<id:int>').use((req) => {
  return Response.json({ userId: req.params.id })
})

// 3. 查询参数
app.get('/search?<q:string>').use((req) => {
  return Response.json({ query: req.query.q })
})

// 4. 请求体验证
class CreatePostInput extends ObjectType {
  title = String
  content = String
}

app.post('/posts', { body: CreatePostInput }).use((req) => {
  return Response.status(201).json(req.body)
})

app.listen(3000)

下一步

现在你已经了解了 farrow-http 的核心优势,接下来深入学习:

1. 路由与类型魔法 - 掌握 URL 模式和类型推导
2. 请求体验证 - 使用 Schema 验证数据
3. 响应构建 - 构建各种响应类型