Class API<T, Raw, State>

constructor

• new API<
      T = DEFAULT_HANDLER,
      Raw = unknown,
      State extends Record<string, unknown> = Record<string, unknown>,
  >(
      method: "get" | "post" | "put" | "delete" | "patch",
      path: string,
      sourceFile: SourceResult,
      group?: string,
      prefix?: string,
  ): API<T, Raw, State>

  构造函数

  Type Parameters

  • T = DEFAULT_HANDLER
  • Raw = unknown
  • State extends Record<string, unknown> = Record<string, unknown>

  Parameters

  • method: "get" | "post" | "put" | "delete" | "patch"
  • path: string
  • sourceFile: SourceResult
  • Optionalgroup: string
  • Optionalprefix: string

  Returns API<T, Raw, State>

inited

key

options

pathTestRegExp

before

• before(...list: T[]): API<T, Raw, State>

  注册执行之前的钩子

  Parameters

  • ...list: T[]

  Returns API<T, Raw, State>

body

• body(schema: ZodType): API<T, Raw, State>

  Body 参数（原生 Zod schema）

  Parameters

  • schema: ZodType

  Returns API<T, Raw, State>

description

• description(description: string): API<T, Raw, State>

  API描述

  Parameters

  • description: string

  Returns API<T, Raw, State>

example

• example(example: IExample): API<T, Raw, State>

  API使用例子

  Parameters

  • example: IExample

  Returns API<T, Raw, State>

group

• group(group: string): API<T, Raw, State>

  API分组

  Parameters

  • group: string

  Returns API<T, Raw, State>

headers

• headers(schema: ZodType): API<T, Raw, State>

  Headers 参数（原生 Zod schema）

  Parameters

  • schema: ZodType

  Returns API<T, Raw, State>

init

• init(parent: ERest<unknown>): void

  Parameters

  • parent: ERest<unknown>

  Returns void

middlewares

• middlewares(...list: T[]): API<T, Raw, State>

  中间件

  Parameters

  • ...list: T[]

  Returns API<T, Raw, State>

mock

• mock(data?: Record<string, unknown>): API<T, Raw, State>

  Parameters

  • Optionaldata: Record<string, unknown>

  Returns API<T, Raw, State>

params

• params(schema: ZodType): API<T, Raw, State>

  Path 参数（原生 Zod schema）

  Parameters

  • schema: ZodType

  Returns API<T, Raw, State>

pathTest

• pathTest(
      method: "get" | "post" | "put" | "delete" | "patch",
      path: string,
  ): boolean

  检查URL是否符合API规则

  Parameters

  • method: "get" | "post" | "put" | "delete" | "patch"
  • path: string

  Returns boolean

query

• query(schema: ZodType): API<T, Raw, State>

  Query 参数（原生 Zod schema）

  Parameters

  • schema: ZodType

  Returns API<T, Raw, State>

register

• register(fn: Middleware<State>): this

  注册处理函数。

  handler 参数 (ctx, next) 由 TS 自动推导——ctx 是 erest 标准 Context （含 reply/params/query/body/state/$params 等），next 调用链下一个中间件。 无需手写类型标注：

  api.group('g').get('/path').register(async (ctx, next) => {
    ctx.reply.json({ ok: true });
    return next();
  });
  Copy

  Parameters

  • fn: Middleware<State>

  Returns this

registerTyped

• registerTyped<
      TQuery extends
          Readonly<
              {
                  [k: string]: $ZodType<
                      unknown,
                      unknown,
                      $ZodTypeInternals<unknown, unknown>,
                  >;
              },
          > = Record<string, never>,
      TBody extends
          Readonly<
              {
                  [k: string]: $ZodType<
                      unknown,
                      unknown,
                      $ZodTypeInternals<unknown, unknown>,
                  >;
              },
          > = Record<string, never>,
      TParams extends
          Readonly<
              {
                  [k: string]: $ZodType<
                      unknown,
                      unknown,
                      $ZodTypeInternals<unknown, unknown>,
                  >;
              },
          > = Record<string, never>,
      THeaders extends
          Readonly<
              {
                  [k: string]: $ZodType<
                      unknown,
                      unknown,
                      $ZodTypeInternals<unknown, unknown>,
                  >;
              },
          > = Record<string, never>,
      TResponse extends
          ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>> = ZodAny,
  >(
      schemas: {
          body?: ZodObject<TBody, $strip>;
          headers?: ZodObject<THeaders, $strip>;
          params?: ZodObject<TParams, $strip>;
          query?: ZodObject<TQuery, $strip>;
          response?: TResponse;
      },
      handler: (
          req: {
              body: $InferObjectOutput<TBody>;
              headers: $InferObjectOutput<THeaders>;
              params: $InferObjectOutput<TParams>;
              query: $InferObjectOutput<TQuery>;
          },
          ctx: Context<State, Raw>,
      ) => void | Promise<void> | output<TResponse> | Promise<output<TResponse>>,
  ): API<T, Raw, State>

  注册强类型处理函数 (基于 zod schema)。

  handler 签名为 (req, ctx)，与框架无关：

  • req.params / req.query / req.body / req.headers：分层校验后的参数，类型由 Zod schema 推导
  • ctx：框架无关的请求上下文（Context<State, Raw>），含 ctx.reply（响应接口 { status, json, send }）+ ctx.state（typed 跨中间件状态）+ ctx.reply.raw（原生逃生舱）

  同一份 handler 可被 Express / Koa / @leizm/web 三个框架复用，无需关心 ctx/res 差异。 校验由 adapter 的 checker 统一完成（注入到 req/ctx.$validated + $reply），handler 内不重复 parse。

  若提供 response schema 且 handler 有返回值，返回值会经 schema 校验（适合只读/纯计算型 handler）。

  Type Parameters

  • TQuery extends Readonly<
        {
            [k: string]: $ZodType<
                unknown,
                unknown,
                $ZodTypeInternals<unknown, unknown>,
            >;
        },
    > = Record<string, never>
  • TBody extends Readonly<
        {
            [k: string]: $ZodType<
                unknown,
                unknown,
                $ZodTypeInternals<unknown, unknown>,
            >;
        },
    > = Record<string, never>
  • TParams extends Readonly<
        {
            [k: string]: $ZodType<
                unknown,
                unknown,
                $ZodTypeInternals<unknown, unknown>,
            >;
        },
    > = Record<string, never>
  • THeaders extends Readonly<
        {
            [k: string]: $ZodType<
                unknown,
                unknown,
                $ZodTypeInternals<unknown, unknown>,
            >;
        },
    > = Record<string, never>
  • TResponse extends ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>> = ZodAny

  Parameters

  • schemas: {
        body?: ZodObject<TBody, $strip>;
        headers?: ZodObject<THeaders, $strip>;
        params?: ZodObject<TParams, $strip>;
        query?: ZodObject<TQuery, $strip>;
        response?: TResponse;
    }
  • handler: (
        req: {
            body: $InferObjectOutput<TBody>;
            headers: $InferObjectOutput<THeaders>;
            params: $InferObjectOutput<TParams>;
            query: $InferObjectOutput<TQuery>;
        },
        ctx: Context<State, Raw>,
    ) => void | Promise<void> | output<TResponse> | Promise<output<TResponse>>

  Returns API<T, Raw, State>

requiredOneOf

• requiredOneOf(list: string[]): API<T, Raw, State>

  多选一必填参数（Zod 之上的便利方法，无完美 Zod 等价）

  Parameters

  • list: string[]

  Returns API<T, Raw, State>

response

• response(response: TYPE_RESPONSE): API<T, Raw, State>

  输出结果对象

  Parameters

  • response: TYPE_RESPONSE

  Returns API<T, Raw, State>

title

• title(title: string): API<T, Raw, State>

  API标题

  Parameters

  • title: string

  Returns API<T, Raw, State>

Staticdefine

• define<
      T,
      Raw = unknown,
      State extends Record<string, unknown> = Record<string, unknown>,
  >(
      options: APIDefine<T>,
      sourceFile: SourceResult,
      group?: string,
      prefix?: string,
  ): API<T, Raw, State>

  Type Parameters

  • T
  • Raw = unknown
  • State extends Record<string, unknown> = Record<string, unknown>

  Parameters

  • options: APIDefine<T>
  • sourceFile: SourceResult
  • Optionalgroup: string
  • Optionalprefix: string

  Returns API<T, Raw, State>