跳到主要内容

简介

Keq 是什么？​

Keq 是一个现代化的 TypeScript HTTP 客户端，基于 Fetch API 构建，同时支持浏览器和 Node.js 环境。它融合了 koa 的中间件设计理念和 superagent 的链式调用体验，让 HTTP 请求变得优雅而强大。

为什么选择 Keq？​

与传统的 HTTP 客户端不同，Keq 不仅仅是一个发送请求的工具——它是一个可组合、可扩展的请求解决方案：

  • 🎯 从 API 文档到代码：通过 @keq-request/cli 将 Swagger/OpenAPI 文档直接转换为类型安全的请求函数，告别手写重复的请求代码
  • 🧩 洋葱模型中间件：像 Koa 一样优雅地组合功能，轻松实现超时控制、自动重试、错误处理、缓存等复杂逻辑
  • 🔗 链式调用 API：流畅的调用体验，无需臃肿的配置对象，所有参数一目了然
  • 📘 完备的 TypeScript 支持：从请求参数到响应体，全链路类型推断，让编辑器成为你的最佳文档
  • 🎨 灵活的路由系统：根据域名、路径、模块等条件精准应用中间件，实现细粒度的请求控制

一个简单的例子​

import { request } from "keq";

// 简洁的链式调用
const cats = await request
  .get("/cats")
  .query("breed", "british_shorthair")
  .set("Authorization", "Bearer token")
  .timeout(3000)
  .retry(2);

console.log(`找到了 ${cats.length} 只猫咪`);

使用 @keq-request/cli 让开发更高效​

想象一下，你不再需要为每个 API 接口手写请求代码：

// @keq-request/cli 根据 Swagger 文档自动生成
import { getCats, createCat } from "./api/cat_service";

// 完整的类型提示，参数错误会在编译时发现
const cats = await getCats({ breed: "siamese" })
  .retry(3, 1000)
  .timeout(5000);

// 所有接口共享统一的中间件逻辑
request
  .useRouter()
  .module("catService", errorHandler());

核心特性​

🌐 跨平台支持​

在浏览器和 Node.js (≥20) 中使用同一套代码，基于标准 Fetch API，无需担心兼容性问题。

⚡ 链式调用​

流畅的 API 设计，让请求配置直观易读：

await request
  .post("/cats")
  .send({ name: "mimi", age: 3 })
  .set("Content-Type", "application/json")
  .query("lang", "zh-CN")
  .timeout(5000)
  .retry(2);

🎯 中间件系统​

通过中间件扩展 Keq 的能力，官方提供了丰富的开箱即用功能：

📘 TypeScript First​

完整的类型定义和类型推断，配合 @keq-request/cli 生成的代码，获得极致的开发体验：

// 自动推断响应体类型
const cat = await request.get<Cat>("/cats/1");
//    ^? Cat

// 严格的参数类型检查（getCats 由 @keq-request/cli 生成）
await getCats({ breed: "siamese" });
//              ^^^^^^ 类型提示和校验

🎨 灵活的路由​

精准控制中间件的应用范围：

request
  .useRouter()
  .host("api.example.com", authMiddleware())
  .pathname("/admin/**", adminAuthMiddleware())
  .module("catService", errorHandler())
  .method("POST", logMiddleware());

🛠️ 代码生成工具​

@keq-request/cli 是 Keq 的杀手级功能，将 Swagger/OpenAPI 文档转换为类型安全的请求函数：

  • ✅ 自动生成请求函数和 TypeScript 类型
  • ✅ 完整的接口参数类型检查
  • ✅ 支持路由参数、查询参数、请求头、请求体
  • ✅ 通过模块化组织，统一管理不同服务的接口
  • ✅ 保持手写代码的灵活性，支持动态参数

设计哲学​

Keq 的设计遵循以下原则：

  1. 优雅的 API：链式调用让代码更易读易写
  2. 可组合性：通过中间件组合复杂功能，而非臃肿的配置
  3. 类型安全：充分利用 TypeScript，在编译期发现问题
  4. 开发效率：通过 CLI 工具减少重复劳动
  5. 灵活可控：提供足够的扩展点，满足各种定制需求