@omni/http

OmniAPI 的 HTTP Adapter（基于 Fastify），内置 OpenAPI 3.1 文档自动生成。

安装

pnpm add @omni/http @omni/core zod fastify

快速使用

import { Registry, defineProcedure } from '@omni/core';
import { createHttpAdapter } from '@omni/http';
import { z } from 'zod';

const registry = new Registry();
registry.register(
  defineProcedure({
    name: 'hello.world',
    description: 'say hello',
    input: z.object({ name: z.string() }),
    output: z.object({ greeting: z.string() }),
    handler: ({ input }) => ({ greeting: `Hello, ${input.name}!` }),
  }),
);

const adapter = createHttpAdapter({
  registry,
  port: 3000,
  openapi: { title: 'My API', version: '1.0.0' },
});
await adapter.listen();

启动后默认获得：

• POST /hello/world 业务接口
• GET /openapi.json OpenAPI 3.1 文档
• GET /docs 内嵌 Swagger UI（CDN 模式，零额外依赖）
• GET /_health 存活检查
• GET /_ready 就绪检查

路由派生规则

• meta.http.path 优先；否则按 name 派生：order.create → /order/create
• meta.http.method 优先；否则按 name 第二段动词推断（create/add → POST，get/list/query → GET，update/patch → PATCH，set/replace → PUT，delete/remove → DELETE，未知 → POST）
• meta.http.expose === false 排除该路由

输入装配

合并优先级：path > body > query

• GET / DELETE：query + path
• 其他 method：body + path

错误映射

所有 OmniError 自动映射为 {code, message, details?} JSON + 对应状态码；RateLimitError.retryAfterMs 自动转为 Retry-After header。

API

• createHttpAdapter(options) → { server, listen, close, toOpenAPI }
• buildOpenAPI(registry, opts?) → 直接拿 OpenAPI 文档对象
• deriveRoute(procedure) → 路由派生
• assembleInput(req) → 输入装配