@faapi/faapi 0.0.0-canary.4ab8d97 → 0.0.0-canary.991c0b8

package/dist/index.d.ts

@@ -54,6 +54,17 @@ interface SseEvent {
 interface SseWriter {
     /** 推送一个 SSE 事件 */
     send(event: SseEvent): void;
+    /**
+     * 直接写入原始字节/字符串,不做任何 SSE 序列化
+     *
+     * 用于透传上游已有的 SSE 原文(如 LLM 中转平台逐 chunk 转发 OpenAI 响应)。
+     * 调用方负责保证内容符合 HTML5 SSE 规范;`send` 会再次加 `data: ` 前缀,
+     * 不适用于原文透传场景。
+     *
+     * 接受 string 或 Uint8Array(Buffer 是 Uint8Array 子类,自然兼容)。
+     * 与 `send` 一致:close/aborted 后静默忽略,不抛错。
+     */
+    sendRaw(chunk: string | Uint8Array): void;
     /** 推送一个 error 事件并关闭流（用于流式输出中报错的优雅终止） */
     sendError(error: unknown): void;
     /** 关闭流（多次调用安全） */
@@ -99,6 +110,14 @@ interface FaapiContext {
     headers: Headers;
     method: string;
     path: string;
+    /**
+     * 客户端 IP
+     *
+     * 优先 `x-forwarded-for` 第一个 IP（反向代理场景），回退到 socket.remoteAddress。
+     * IPv6 形式 `::ffff:1.2.3.4` 会被规整为 IPv4 形式 `1.2.3.4`。
+     * 无法获取时为空字符串。
+     */
+    ip: string;
     /** 解析后的所有 cookie 键值对 */
     cookies: Record<string, string>;
     /** 配置文件中的自定义业务配置（类型可通过 declare module '@faapi/faapi' 增强 FaapiContextConfig） */
@@ -111,6 +130,19 @@ interface FaapiContext {
      * 设置响应头
      */
     setHeader(key: string, value: string): void;
+    /**
+     * 设置 ETag 响应头
+     *
+     * handler 中基于业务数据（如 updatedAt / version / contentHash）设置 ETag：
+     * ```ts
+     * export function GET(ctx) {
+     *   const data = await fetchData();
+     *   ctx.setETag(`"${data.version}-${data.updatedAt}"`);
+     *   return data;
+     * }
+     * ```
+     */
+    setETag(value: string): void;
     /**
      * 返回 JSON 响应（handler 直接 return）
      *
@@ -264,22 +296,50 @@ interface CorsOptions {
  */
 declare function cors(options?: CorsOptions): FaapiMiddleware;
 
+type LoggerFn = (messageOrObj: string | Record<string, unknown>, message?: string) => void;
 interface LoggerOptions {
-    /** 自定义日志输出函数，默认 console.log */
-    log?: (message: string) => void;
+    /**
+     * 自定义日志函数
+     *
+     * - 传入 `console.log`（默认）：纯文本格式 `GET /api/users 200 12ms`
+     * - 传入 pino logger：结构化日志 `logger.info({ method, path, status, durationMs }, 'request completed')`
+     * - 传入 winston logger：`logger.info('GET /api/users 200 12ms', { method, path })`
+     */
+    log?: LoggerFn;
 }
 /**
  * 创建请求日志中间件（洋葱模型）
  *
- * 日志格式：GET /api/users 200 12ms
- * 错误格式：POST /api/users 400 45ms - Error: ...
+ * 日志格式（文本模式）：GET /api/users 200 12ms
+ * 错误格式（文本模式）：POST /api/users 400 45ms - Error: ...
+ *
+ * 结构化模式：传入 pino/winston 等 logger 实例时，会自动传递结构化字段。
  *
  * before/after 一体，闭包变量共享开始时间，无需污染 ctx。
  * 错误用 try/catch 捕获，记录后重新抛出（让上层处理）。
  * 成功时从 next() 返回的 Response 读取状态码。
+ *
+ * log 函数每次请求时读取（options.log ?? console.log），运行时替换 console.log 会生效。
  */
 declare function logger(options?: LoggerOptions): FaapiMiddleware;
 
+interface HelmetOptions {
+    contentSecurityPolicy?: string | false;
+    xFrameOptions?: 'DENY' | 'SAMEORIGIN' | false;
+    xContentTypeOptions?: boolean;
+    referrerPolicy?: string | false;
+    strictTransportSecurity?: string | false;
+    xDnsPrefetchControl?: boolean;
+    xDownloadOptions?: boolean;
+    xPermittedCrossDomainPolicies?: string | false;
+    crossOriginOpenerPolicy?: string | false;
+    crossOriginResourcePolicy?: string | false;
+    crossOriginEmbedderPolicy?: string | false;
+    originAgentCluster?: boolean;
+    xPoweredBy?: boolean;
+}
+declare function helmet(options?: HelmetOptions): FaapiMiddleware;
+
 declare const HTTP_METHODS: readonly ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"];
 type HttpMethod = (typeof HTTP_METHODS)[number];
 
@@ -296,7 +356,26 @@ interface RouteRecord {
     /** 路由对应的注入器映射表（从根到路由目录合并，构建时加载） */
     injectors?: InjectorMap;
 }
+/**
+ * WebSocket 路由记录
+ *
+ * 与 HTTP RouteRecord 类似，但不绑定 HTTP 方法（WS 是协议升级，不区分 GET/POST）。
+ * 一个 handler.ts 中导出 WS 即生成一条 WS 路由记录。
+ */
+interface WsRouteRecord {
+    urlPath: string;
+    filePath: string;
+    paramNames: string[];
+    isDynamic: boolean;
+    /** 是否为 catch-all 路由（[...slug]） */
+    isCatchAll?: boolean;
+    /** 路由对应的中间件集合（握手阶段执行，复用鉴权/CORS/日志） */
+    middlewares?: FaapiMiddleware[];
+    /** 路由对应的注入器映射表 */
+    injectors?: InjectorMap;
+}
 type RouteManifest = RouteRecord[];
+type WsRouteManifest = WsRouteRecord[];
 /**
  * 路由单个参数的 schema 描述
  *
@@ -315,6 +394,18 @@ interface RouteInputSchema {
     schemaName: string | null;
     properties: RouteParamSchema[];
 }
+/**
+ * 路由响应类型的 schema 描述
+ *
+ * 由 @faapi/schema 扩展包的 buildRouteSchemas 生成。
+ * output 为 null 表示无显式返回类型注解、void/Promise<void>、或解析失败降级。
+ */
+interface RouteOutputSchema {
+    /** 命名类型名(如 'UserResponse'),内联类型为 null */
+    schemaName: string | null;
+    /** 顶层属性列表 */
+    properties: RouteParamSchema[];
+}
 /**
  * 路由的完整 schema 描述
  *
@@ -327,6 +418,8 @@ interface RouteInfo {
     filePath: string;
     isDynamic: boolean;
     inputs: RouteInputSchema[];
+    /** 响应类型描述(null 表示无返回类型注解/void/解析失败) */
+    output: RouteOutputSchema | null;
 }
 
 /** HTTP 请求 handler 类型 */
@@ -344,8 +437,10 @@ type UpgradeHandler = (req: IncomingMessage, socket: Socket, head: Buffer) => vo
 interface PluginContext {
     /** 项目根目录 */
     rootDir: string;
-    /** 当前路由清单 */
+    /** 当前路由清单（setup 时的快照，reloadRoutes 后不会更新；需最新路由用 getRoutes()） */
     routes: RouteManifest;
+    /** 获取最新路由清单（reloadRoutes 后返回更新后的数组） */
+    getRoutes: () => RouteManifest;
     /** HTTP 服务器实例（未 listen） */
     server: Server;
     /** 自定义业务配置（faapi.config.ts 中的自定义 key） */
@@ -416,40 +511,31 @@ type PluginDeclaration = string | [string, unknown] | {
     options?: unknown;
 };
 
-/**
- * 统一响应格式化函数
- *
- * 当配置了 responseFormat 时，handler 返回的非 Response 值会经过此函数包装
- * 例如：{ code: 0, data, message: 'success' }
- */
-type ResponseFormatFn = (data: unknown, ctx: FaapiContext) => unknown;
-/**
- * 错误响应格式化函数
- *
- * 优先于内置 formatErrorResponse 处理错误。返回 Response 表示已处理；
- * 返回 null/undefined 表示不处理，由内置 formatErrorResponse 兜底。
- */
-type ErrorFormatFn = (error: unknown, ctx?: FaapiContext) => Response | null | undefined;
+interface Http2Options {
+    key?: string;
+    cert?: string;
+}
+
 /**
  * 生命周期钩子
  */
 interface LifecycleHooks {
-    /** 路由加载完成、服务器启动前调用（适合初始化数据库连接等） */
+    /** 服务器启动后调用（适合初始化数据库连接等） */
     onReady?: (ctx: LifecycleContext) => Promise<void> | void;
     /** 服务器关闭时调用（适合清理资源、优雅关闭） */
     onClose?: (ctx: LifecycleContext) => Promise<void> | void;
     /**
-     * 请求错误已被 errorFormat 处理为响应后调用（参考 Fastify onError 语义）
+     * 请求错误已被处理为响应后调用(参考 Fastify onError 语义)
      *
-     * 时机：handler 抛错 → errorFormat 生成错误响应（失败则由框架内置 formatErrorResponse 兜底）
+     * 时机:handler 抛错 → 全局中间件 try/catch(若有) → 框架内置 formatErrorResponse 兜底
      *      → 响应发出后 → onError 触发副作用
      *
-     * 职责：日志上报、告警、链路追踪等副作用。**不修改、不替换已生成的响应**。
-     * 自身抛错会被捕获并忽略，不影响响应已发送的事实。
+     * 职责:日志上报、告警、链路追踪等副作用。**不修改、不替换已生成的响应**。
+     * 自身抛错会被捕获并忽略,不影响响应已发送的事实。
      *
-     * 与 errorFormat 的区别：
-     * - errorFormat：把 error 翻译成 Response（主入口，决定响应内容）
-     * - onError：响应发出后的副作用（不能改响应）
+     * 与全局错误中间件的区别:
+     * - 全局错误中间件:把 error 翻译成 Response(主入口,决定响应内容)
+     * - onError:响应发出后的副作用(不能改响应)
      */
     onError?: (error: unknown, ctx: FaapiContext) => Promise<void> | void;
 }
@@ -471,7 +557,6 @@ interface LifecycleContext {
  * ```ts
  * import type { FaapiConfig } from '@faapi/faapi';
  * export default {
- *   port: 3000,
  *   cors: { origin: '*' },
  * } satisfies FaapiConfig;
  * ```
@@ -480,7 +565,6 @@ interface LifecycleContext {
  * ```ts
  * import type { FaapiConfig } from '@faapi/faapi';
  * export default {
- *   port: 3000,
  *   cors: { origin: '*' },
  *   // 自定义业务配置（任意 key）
  *   db: { host: 'localhost', port: 5432 },
@@ -488,20 +572,24 @@ interface LifecycleContext {
  * ```
  *
  * 环境覆盖通过 faapi.config.{NODE_ENV}.ts 实现（如 faapi.config.production.ts）
+ *
+ * 框架元信息通过环境变量配置（不放在 config 内）：
+ * - `PORT`：服务端口，默认 3000
+ * - `FAAPI_DIST`：产物输出目录，dev 固定为 `.faapi`（不可修改），prod 默认为 `dist`（可通过 `--dist` 修改）
  */
 interface FaapiConfig {
-    /** 服务端口，默认 3000（可被 --port / PORT 环境变量覆盖） */
-    port?: number;
-    /** 静态文件目录 */
-    staticDir?: string;
     /** CORS 配置，false 禁用 */
     cors?: CorsOptions | boolean;
-    /** 统一响应格式化函数 */
-    responseFormat?: ResponseFormatFn;
-    /** 错误响应格式化函数 */
-    errorFormat?: ErrorFormatFn;
     /** 生命周期钩子 */
     lifecycle?: LifecycleHooks;
+    /** 安全头配置，false 禁用 */
+    helmet?: HelmetOptions | boolean;
+    /** 请求体大小限制（字节），默认 10MB（10 * 1024 * 1024） */
+    bodyLimit?: number;
+    /** 日志中间件配置 */
+    logger?: LoggerOptions | boolean;
+    /** HTTP/2 配置，false 禁用（默认 http/1.1） */
+    http2?: Http2Options | boolean;
     /**
      * 全局中间件：对所有路由（HTTP + WebSocket 握手）生效
      *
@@ -664,6 +752,15 @@ interface WsContext {
  */
 type WsHandler = (ctx: WsContext) => WsEventHandlers | void;
 
+/**
+ * 清理所有 Program 缓存（watch 模式下文件变化时调用）
+ *
+ * 全量清理而非增量清理，理由：
+ * - 简单可靠，无状态一致性问题
+ * - 跨文件类型引用需要所有文件的 Program 同步更新
+ * - dev 模式文件量有限，全量重建在百毫秒级
+ */
+declare function invalidateProgramCache(): void;
 /**
  * 为指定文件创建 TypeScript Program（带缓存）
  *
@@ -725,6 +822,13 @@ type RuntimeType = {
     kind: 'record';
     key: RuntimeType;
     value: RuntimeType;
+} | {
+    kind: 'map';
+    key: RuntimeType;
+    value: RuntimeType;
+} | {
+    kind: 'set';
+    element: RuntimeType;
 } | {
     kind: 'ref';
     name: string;
@@ -744,7 +848,79 @@ interface PropertyType {
     name: string;
     type: RuntimeType;
     optional: boolean;
+    /**
+     * 字段级 JSDoc 约束标签（@max/@min/@maxLength 等）
+     *
+     * 来自字段 JSDoc 注释，由 generateZodSchema 转为 zod 链式调用。
+     * 约束与字段类型不匹配时在提取阶段抛 SchemaExtractionError。
+     */
+    constraints?: TypeConstraint[];
 }
+/**
+ * JSDoc 约束标签的运行时描述
+ *
+ * 由字段 JSDoc 注释提取，对应 zod schema 的链式约束方法。
+ * 仅在 PropertyType.constraints 中出现，不挂在嵌套类型（array 元素、tuple 元素等）上。
+ */
+type TypeConstraint = {
+    kind: 'max';
+    value: number;
+} | {
+    kind: 'min';
+    value: number;
+} | {
+    kind: 'int';
+} | {
+    kind: 'positive';
+} | {
+    kind: 'negative';
+} | {
+    kind: 'nonnegative';
+} | {
+    kind: 'nonpositive';
+} | {
+    kind: 'maxLength';
+    value: number;
+} | {
+    kind: 'minLength';
+    value: number;
+} | {
+    kind: 'length';
+    value: number;
+} | {
+    kind: 'regex';
+    pattern: string;
+    flags?: string;
+} | {
+    kind: 'email';
+} | {
+    kind: 'url';
+} | {
+    kind: 'uuid';
+};
+/**
+ * 将 TypeScript 类型节点解析为运行时类型描述
+ *
+ * 支持的类型：
+ * - 基础类型：string / number / boolean / null / undefined / any / unknown / void
+ * - bigint：不支持（HTTP/JSON 不能传输），AST 提取阶段抛 SchemaExtractionError
+ * - 字面量类型：'foo' / 42 / true
+ * - 数组类型：T[] / Array<T> / ReadonlyArray<T> / readonly T[]
+ * - 元组类型：[string, number] / [string, number?] / [string, ...number[]] / readonly [T, U]（按位置校验）
+ * - 对象类型：{ name: string; age?: number }（含 readonly 字段修饰符，忽略 readonly）
+ * - 联合类型：string | null
+ * - 交叉类型：A & B（按对象合并处理）
+ * - 引用类型：Date / 其他 interface（递归解析）
+ * - 工具类型：Record<K, V> / Partial<T> / Readonly<T>（best effort）
+ * - Pick<T, K> / Omit<T, K>：K 支持字面量联合、类型别名、keyof T
+ *
+ * readonly 是编译期约束，运行时不产生校验语义，所有 readonly 修饰符统一忽略。
+ *
+ * @param typeNode TypeScript 类型节点
+ * @param checker  类型 checker（用于解析引用类型）
+ * @param visited  防止递归循环
+ */
+declare function resolveTypeNode(typeNode: ts.TypeNode, checker?: ts.TypeChecker, visited?: Set<string>): RuntimeType;
 
 interface HandlerTypeInfo {
     name: string;
@@ -780,48 +956,240 @@ declare function extractTypeInfo(program: ts.Program, filePath: string, typeName
 declare function getInputTypeForMethod(method: string): 'query' | 'body';
 
 /**
- * 单个参数的 schema 描述（简化版，供扩展包消费）
+ * 单个路由的 schema 提取结果
+ *
+ * key 使用 urlPath（如 '/api/hello'）而非 filePath，因为 urlPath 在 dev/prod 完全一致，
+ * 无需 remapManifestKeys 桥接 .ts/.js 路径差异。
  */
-interface SchemaPropertyDescriptor {
-    name: string;
-    type: string;
-    required: boolean;
+interface RouteSchemaSource {
+    /** 路由 URL 路径（如 '/api/hello'），作为 schema key */
+    urlPath: string;
+    /** 源文件绝对路径（用于 generateSchemaFiles 按文件分组生成 zod.js） */
+    filePath: string;
+    schemaName: string;
+    typeInfo: HandlerTypeInfo | null;
+    /**
+     * 是否对 number/boolean 字段生成 z.preprocess 字符串转换（coerce）。
+     *
+     * - query/params：始终 coerce=true（URL 来源均为 string）
+     * - body：始终 coerce=false（JSON 解析已是天然 JS 类型）
+     * - form：coerce=true（form-urlencoded 来源均为 string），由本函数在提取时
+     *   检测到 handler 声明 `form` 参数时显式设置。schema 名仍为 `POSTBody`
+     *   （与 body 共享运行时 schema key），运行时 validateInput 无需感知 form/body 差异。
+     *
+     * 未设置时由 generateSchemaFileSource 回退到 schemaName 后缀正则推断（Query/Params → true）。
+     */
+    coerce?: boolean;
 }
 /**
- * 单个输入源的 schema 描述
+ * 从路由清单收集 schema 提取所需的原始数据
+ *
+ * dev 和 prd 共享的核心提取流程：
+ * 1. 按文件分组遍历路由
+ * 2. 对每个文件 createProgram + extractAllTypes 收集所有类型
+ * 3. 用 analyzeInjection + extractTypeInfo 提取每个路由的 schema 类型
+ * 4. 同时返回按文件分组的 allTypesMap 和合并后的全局 allTypes
+ *
+ * 调用方基于返回的 sources 和 allTypes 各自做最终转换：
+ * - dev：生成 JS 模块文件 → import 加载（用 allTypesByFile）
+ * - prd：生成 JS 模块代码 → SchemaModuleEntry[]（用 allTypesByFile）
  */
-interface InputSchemaDescriptor {
-    /** 输入源类型名（如 'Query'、'CreateUserBody'），无类型声明时 null */
-    schemaName: string | null;
-    /** 参数列表 */
-    properties: SchemaPropertyDescriptor[];
+declare function collectRouteSchemaSources(routes: RouteManifest, rootDir?: string): {
+    sources: RouteSchemaSource[];
+    /** 按文件分组的类型映射（prd writeSchemaModule 用） */
+    allTypesByFile: Map<string, Map<string, HandlerTypeInfo>>;
+    /** 合并后的全局类型映射（兼容旧调用方保留，新路径使用 allTypesByFile） */
+    mergedAllTypes: Map<string, HandlerTypeInfo>;
+};
+
+/**
+ * 加载 faapi 配置文件
+ *
+ * 统一读取 `<dist>/faapi-config.js` 产物：
+ * - dev 模式：`faapi dev` 启动时由 `compileConfig` 生成 `.faapi/faapi-config.js`
+ * - prod 模式：`faapi build` 时由 `compileConfig` 生成 `dist/faapi-config.js`
+ *
+ * 产物由 `compileConfig` 在构建阶段合并 env 后固化，运行时不读源码、不现场编译、不按 env 合并。
+ *
+ * - 产物存在 → import 并返回 default
+ * - 产物不存在但源码有配置文件 → 抛错（强制 rebuild）
+ * - 源码也无配置文件 → 返回 `null`（配置可选）
+ *
+ * @param rootDir 项目根目录
+ * @param dist 产物目录（如 'dist' 或 '.faapi'）
+ * @returns 配置对象，无配置文件时返回 null
+ */
+declare function loadConfig(rootDir: string, dist: string): Promise<Partial<FaapiConfig> | null>;
+
+declare const VALIDATION_ERROR = "VALIDATION_ERROR";
+declare const ROUTE_NOT_FOUND = "ROUTE_NOT_FOUND";
+declare const METHOD_NOT_ALLOWED = "METHOD_NOT_ALLOWED";
+declare const INTERNAL_ERROR = "INTERNAL_ERROR";
+declare const MODULE_LOAD_ERROR = "MODULE_LOAD_ERROR";
+type ErrorCode = typeof VALIDATION_ERROR | typeof ROUTE_NOT_FOUND | typeof METHOD_NOT_ALLOWED | typeof INTERNAL_ERROR | typeof MODULE_LOAD_ERROR;
+
+declare class FaapiError extends Error {
+    readonly code: ErrorCode;
+    readonly statusCode: number;
+    constructor(code: ErrorCode, message: string, statusCode: number);
+}
+
+declare class ValidationError extends FaapiError {
+    readonly issues: ValidationIssue[];
+    constructor(message: string, issues: ValidationIssue[]);
+}
+declare class RouteNotFoundError extends FaapiError {
+    constructor(path: string);
+}
+declare class MethodNotAllowedError extends FaapiError {
+    readonly allowedMethods: string[];
+    constructor(method: string, path: string, allowedMethods: string[]);
+}
+declare class InternalError extends FaapiError {
+    constructor(message: string);
+}
+declare class ModuleLoadError extends FaapiError {
+    constructor(filePath: string, reason: string);
 }
 /**
- * 查询指定路由 handler 的输入参数 schema
+ * 校验问题类型
  *
- * 复用 schemaRegistry 已有的类型提取结果，避免重复 AST 分析。
- * 在 schema 尚未注册时返回 undefined。
+ * 结构化错误信息,便于上层(全局错误中间件/前端)按 code 做不同处理,
+ * 不依赖字符串解析。message 仅为人类可读的兜底描述。
  *
- * @param filePath handler 文件绝对路径
- * @param method HTTP 方法（GET/POST 等）
- * @param inputType 输入源类型（query/body/params）
+ * code 与 HTTP 状态码的映射（由 ValidationError 推导）：
+ * - INVALID_FORMAT / MISSING_FIELD → 400 Bad Request
+ * - TYPE_MISMATCH / INVALID_VALUE / COERCE_FAILED → 422 Unprocessable Entity
  */
-declare function getSchemaProperties(filePath: string, method: string, inputType: 'query' | 'body' | 'params'): InputSchemaDescriptor | undefined;
+interface ValidationIssue {
+    /** 字段路径,如 'user.address.city' */
+    path: string;
+    /** 错误码,机器可读的契约 */
+    code: ValidationErrorCode;
+    /** 期望类型/值,如 'number' / '"admin" | "user"' */
+    expected: string;
+    /** 实际类型/值,如 'string' / 'undefined' */
+    received: string;
+    /** 人类可读的本地化消息(兜底,不保证稳定) */
+    message: string;
+}
+type ValidationErrorCode = 'TYPE_MISMATCH' | 'MISSING_FIELD' | 'INVALID_FORMAT' | 'INVALID_VALUE' | 'COERCE_FAILED';
 
 /**
- * 加载 faapi 配置文件
+ * 从 Request 对象创建 FaapiContext
+ * @param request Web Request 对象
+ * @param params 动态路由参数
+ * @param config 自定义业务配置（来自 faapi.config.ts）
+ * @param ip 客户端 IP（由调用方从 IncomingMessage 提取，HTTP/WS 握手均通过 utils/getClientIp）
+ */
+declare function createContext(request: Request, params: Record<string, string>, config?: Record<string, unknown>, ip?: string): FaapiContext;
+
+/**
+ * 调用路由 handler 并将返回值转为 Response
+ *
+ * 流程（洋葱模型）：
+ * 1. 中间件按洋葱模型执行：mw1.before → mw2.before → ... → handler → ... → mw2.after → mw1.after
+ * 2. 中间件不调用 next() 即拦截请求（必须返回 Response）
+ * 3. 中间件可用 try/catch 捕获内层错误
+ * 4. 最内层执行注入器（按需）→ handler
+ *
+ * 注入器与中间件解耦：
+ * - 注入器按 handler 参数名匹配，只执行需要的
+ * - 注入器可读取中间件塞进 ctx 的值
+ */
+declare function invokeHandler(handler: (...args: unknown[]) => unknown, ctx: FaapiContext, body?: unknown, middlewares?: FaapiMiddleware[], injectors?: InjectorMap): Promise<Response>;
+
+interface InjectOptions {
+    method?: string;
+    path?: string;
+    headers?: Record<string, string>;
+    query?: Record<string, string>;
+    body?: unknown;
+}
+interface InjectResponse {
+    status: number;
+    headers: Headers;
+    body: unknown;
+}
+interface CreateAppOptions {
+    /** 项目根目录，默认 process.cwd() */
+    rootDir?: string;
+    /** 产物输出目录（如 dist 或 .faapi），覆盖环境变量 FAAPI_DIST，默认 'dist' */
+    dist?: string;
+    /** 端口号，也可在 listen() 时传入；默认环境变量 PORT 或 3000 */
+    port?: number;
+}
+/** 应用基础接口（dev/prod 共用，不含 reloadRoutes） */
+interface AppBase {
+    /** Node.js Server 实例（listen 后可用，close 后置 null） */
+    server: Server | null;
+    /** 排序后的路由清单 */
+    routes: RouteManifest;
+    /** WebSocket 路由清单 */
+    wsRoutes: WsRouteManifest;
+    /** 项目根目录 */
+    rootDir: string;
+    /** 启动 HTTP server，打印路由表，执行 onReady 钩子 */
+    listen(port?: number): Promise<Server>;
+    /** 关闭 server，执行 onClose 钩子 */
+    close(): Promise<void>;
+    /**
+     * 无服务器测试注入
+     *
+     * 构建一个模拟请求直接走完整请求链路，不绑定端口。
+     * 需要在 listen() 之前调用（server 未启动时）。
+     */
+    inject(options?: InjectOptions): Promise<InjectResponse>;
+}
+
+/** dev 应用接口（AppBase + reloadRoutes 热替换） */
+interface DevApp extends AppBase {
+    /** 重新水合路由清单 + 清 schema 缓存 + 更新 server 路由引用（dev 热替换用） */
+    reloadRoutes(): Promise<void>;
+}
+/**
+ * dev 模式应用启动 API
  *
- * 查找顺序：
- * 1. 指定的 configPath
- * 2. faapi.config.ts / faapi.config.js（基础配置）
- * 3. faapi.config.{env}.ts / faapi.config.{env}.js（环境覆盖，深度合并）
+ * 在 createAppBase（共享逻辑）基础上增加 `reloadRoutes` 热替换能力，供 `faapi dev` watcher 调用。
  *
- * 环境由 NODE_ENV 或 FAAPI_ENV 决定，默认 'development'
+ * 与 createProdApp 的区别：
+ * - dev：含 reloadRoutes（重新扫描路由 + 重新生成 schema + 清缓存 + 更新 server 路由引用）
+ * - prod：精简，无 reloadRoutes（产物已固化，运行时不重建）
  *
- * @param rootDir 项目根目录
- * @param configPath 指定的配置文件路径（可选）
- * @returns 合并后的配置，如果无配置文件则返回 null
+ * 由 `devCommand` 直接调用，devCommand 持有 app 引用并传给 watcher。
+ *
+ * @example
+ * ```ts
+ * // devCommand 内部
+ * const app = await createDevApp();
+ * await app.listen();
+ * startWatcher({ rootDir, app, devDist });
+ * ```
+ */
+declare function createDevApp(options?: CreateAppOptions): Promise<DevApp>;
+
+/** prod 应用接口（AppBase，无 reloadRoutes） */
+type ProdApp = AppBase;
+
+/**
+ * prod 模式应用启动 API
+ *
+ * 直接返回 createAppBase 结果（共享逻辑），不含 dev 专用能力（reloadRoutes、缓存失效）。
+ * 产物在 `faapi build` 阶段已固化，运行时不重建。
+ *
+ * 框架采用零入口设计——用户无需编写 main.ts：
+ * - `faapi build` 自动生成 `dist/main.js` 启动入口，内部调用 `createProdApp()` + `listen()` 启动生产服务器
+ * - 用户自定义启动逻辑通过 `faapi.config.ts` 的 `lifecycle.onReady` / `onClose` 钩子实现
+ *
+ * 编程式调用场景（如自定义 CLI 启动器）也可直接调用：
+ *
+ * @example
+ * ```ts
+ * import { createProdApp } from '@faapi/faapi';
+ * const app = await createProdApp();
+ * await app.listen();
+ * ```
  */
-declare function loadConfig(rootDir: string, configPath?: string): Promise<Partial<FaapiConfig> | null>;
+declare function createProdApp(options?: CreateAppOptions): Promise<ProdApp>;
 
-export { type CorsOptions, type ErrorFormatFn, type FaapiConfig, type FaapiContext, type FaapiContextConfig, type FaapiMiddleware, type FaapiPlugin, type HandlerTypeInfo, type Injector, type InjectorMap, type InputSchemaDescriptor, type LifecycleContext, type LifecycleHooks, type LoggerOptions, type PluginContext, type PluginDeclaration, type PropertyType, type RequestHandler, type ResponseFormatFn, type RouteInfo, type RouteInputSchema, type RouteManifest, type RouteParamSchema, type RuntimeType, SchemaExtractionError, type SchemaPropertyDescriptor, type SseEvent, type SseWriter, type UpgradeHandler, type WsContext, type WsEventHandlers, type WsHandler, type WsSocket, cors, createProgram, extractTypeInfo, getInputTypeForMethod, getSchemaProperties, loadConfig, logger };
+export { type ProdApp as App, type CorsOptions, type CreateAppOptions, type DevApp, type FaapiConfig, type FaapiContext, type FaapiContextConfig, FaapiError, type FaapiMiddleware, type FaapiPlugin, type HandlerTypeInfo, type HelmetOptions, type InjectOptions, type InjectResponse, type Injector, type InjectorMap, InternalError, type LifecycleContext, type LifecycleHooks, type LoggerOptions, MethodNotAllowedError, ModuleLoadError, type PluginContext, type PluginDeclaration, type ProdApp, type PropertyType, type RequestHandler, type RouteInfo, type RouteInputSchema, type RouteManifest, RouteNotFoundError, type RouteOutputSchema, type RouteParamSchema, type RouteSchemaSource, type RuntimeType, SchemaExtractionError, type SseEvent, type SseWriter, type TypeConstraint, type UpgradeHandler, ValidationError, type ValidationErrorCode, type ValidationIssue, type WsContext, type WsEventHandlers, type WsHandler, type WsSocket, collectRouteSchemaSources, cors, createProdApp as createApp, createContext, createDevApp, createProdApp, createProgram, extractTypeInfo, getInputTypeForMethod, helmet, invalidateProgramCache, invokeHandler, loadConfig, logger, resolveTypeNode };