API 参考

Farrow 提供了一套完整的 API 来构建类型安全的 Web 应用。本文档提供了所有核心模块的详细 API 参考。

核心模块

farrow-http

TypeScript 优先的 Web 框架 - 提供类型安全的路由和自动验证功能

• HTTP/HTTPS 服务器创建和配置
• 类型安全的路由模式和自动验证
• 强大的 Response 构建系统
• 模块化路由器和中间件系统
• 上下文管理和错误处理
• 静态文件服务和 CORS 集成
• Express 集成支持

farrow-schema

强大的类型验证和序列化库 - 通过类型驱动设计轻松处理数据

• 完整的基础类型系统（String、Number、Boolean、Date、ID）
• 灵活的复合类型（List、Optional、Nullable、Record、Tuple）
• 结构化类型定义（ObjectType、Struct）
• 联合与交集类型（Union、Intersect、Literal）
• Schema 操作工具（pickObject、omitObject、partial、required）
• 内置和自定义验证器系统
• 完整的 TypeScript 类型推导支持

farrow-pipeline

类型安全的中间件管道库 - 提供函数式编程风格的请求处理

• 同步和异步 Pipeline 创建
• 类型安全的上下文管理系统
• Container 概念和依赖注入
• Pipeline 组合和中间件执行
• 实用工具和错误处理
• 异步追踪支持

快速导航

HTTP 服务

核心 API

• HTTP 服务器 - Http(), Https(), 配置选项
• 路由系统 - Router(), HTTP 方法路由
• 请求与验证 - RequestInfo, 自动验证
• 响应构建 - Response 对象和方法
• 中间件系统 - 洋葱模型, 执行顺序

高级功能

• 上下文管理 - Context 系统, 请求钩子
• 错误处理 - HttpError, 全局错误处理
• 工具函数 - ParseUrl, 类型工具
• 最佳实践 - 依赖注入, 测试策略

Schema 验证

类型系统

• 基础类型 Schema - String, Number, Boolean, Date, ID, Int, Float
• 复合类型 Schema - List, Optional, Nullable, Record, Tuple
• 结构化类型 Schema - ObjectType, StructType, Union, Intersect, Literal
• 特殊类型 Schema - Any, Unknown, Never, Json

验证与格式化

• 验证系统 (Validator) - 运行时数据验证
• 格式化系统 (Formatter) - 类型元数据提取
• Result 类型 - 函数式错误处理

辅助工具

• field - 字段元数据定义
• pick 系列 - 选择字段
• omit 系列 - 排除字段
• partial 系列 - 转为可选
• required 系列 - 转为必填

Pipeline 系统

核心功能

• Pipeline 类型系统 - createPipeline, createAsyncPipeline
• 中间件类型 - Middleware, Next, MiddlewareInput
• usePipeline - 继承容器运行子 Pipeline

上下文系统

• Context 上下文系统 - createContext, 上下文方法
• Container 容器系统 - createContainer, 容器方法
• 异步追踪 (AsyncTracer) - 异步上下文传递

API 规范

命名约定

• 类型: PascalCase (如 ObjectType, HttpError)
• 函数: camelCase (如 createContext, pickStruct)
• 常量: UPPER_CASE (如 DEFAULT_PORT)
• 文件: kebab-case (如 farrow-http)

类型标注

所有 API 都包含完整的 TypeScript 类型定义：

// 函数签名
function createContext<T>(defaultValue: T): Context<T>

// 类型定义
type RequestInfo = {
  readonly pathname: string
  readonly method?: string
  readonly query?: RequestQuery
  readonly body?: any
  readonly headers?: RequestHeaders
  readonly cookies?: RequestCookies
}