#应用实例

import { bootstrap } from "vextjs";

await bootstrap();

function bootstrap(rootDir?: string): Promise<BootstrapResult>;

interface BootstrapResult {
  app: VextApp;
  serverHandle: VextServerHandle;
  internals: AppInternals;
}

// src/index.ts
import { bootstrap } from "vextjs";

bootstrap().catch((err) => {
  console.error("启动失败:", err);
  process.exit(1);
});

const { app, serverHandle, internals } = await bootstrap();

// port 是实际监听端口；标准配置要求端口在 1–65535 之间
app.logger.info(
  { host: serverHandle.host, port: serverHandle.port },
  "HTTP 已监听",
);
// 需要手动结束时：await internals.shutdown(serverHandle, { skipExit: true });

import { createApp, DEFAULT_CONFIG } from "vextjs";

const { app, internals } = createApp(DEFAULT_CONFIG);
app.logger.info("仅创建了基础应用，尚未监听 HTTP");
await internals.shutdown(undefined, { skipExit: true });

function createApp(config: VextConfig): {
  app: VextApp;
  internals: AppInternals;
};

logger: VextRuntimeLogger;

// 基本使用
app.logger.info("服务器启动成功");
app.logger.error({ userId: "123" }, "用户查询失败");
app.logger.debug("调试信息");
app.logger.trace("详细排障信息");

// 运行时调整后续日志阈值
app.logger.getLevel(); // 当前配置/运行时设置的级别，默认 "info"
app.logger.setLevel("debug");

// 结构化日志（对象 + 消息）
app.logger.info({ event: "user_created", userId: "abc" }, "用户创建成功");

// 子 logger（携带额外上下文）
const serviceLogger = app.logger.child({ service: "UserService" });
serviceLogger.info("查询用户列表");
// → { service: 'UserService', requestId: '...', msg: '查询用户列表' }

// 纯消息
logger.info(msg: string, ...args: unknown[]): void;

// 对象 + 消息
logger.info(obj: Record<string, unknown>, msg?: string, ...args: unknown[]): void;

logger.error(err: Error, msg?: string, ...args: unknown[]): void;
logger.fatal(err: Error, msg?: string, ...args: unknown[]): void;

getLevel(): "trace" | "debug" | "info" | "warn" | "error" | "fatal" | "silent";
setLevel(level: "trace" | "debug" | "info" | "warn" | "error" | "fatal" | "silent"): void;

child(bindings: Record<string, unknown>): VextRuntimeLogger;

// 在服务中创建专属 logger
import type { VextApp, VextLogger } from "vextjs";

class UserService {
  private logger: VextLogger;

  constructor(app: VextApp) {
    this.logger = app.logger.child({ service: "UserService" });
  }

  async findById(id: string) {
    this.logger.info({ userId: id }, "查询用户");
    // → { service: 'UserService', userId: '123', requestId: '...', msg: '查询用户' }
  }
}

// 快捷方式（i18n key，status 从 i18n 配置读取，默认 400）
throw(messageKey: string): never;
throw(messageKey: string, params: Record<string, unknown>): never;

// 对象式完整入口
throw(options: {
  status: number;
  message: string;
  params?: Record<string, unknown>;
  code?: number | string;
  details?: unknown;
}): never;

// 标准调用（显式指定 HTTP 状态码）
throw(
  status: number,
  message: string,
  paramsOrCode?: Record<string, unknown> | number | string,
  codeOrDetails?: number | string | Record<string, unknown> | unknown[],
): never;

// 最简写法 — status 从 i18n 配置读取，默认 400
app.throw("balance.insufficient");

// 带 i18n 插值参数
app.throw("balance.insufficient", { balance: 50, required: 100 });

// i18n 配置中指定了 statusCode: 404 → 自动使用 404
app.throw("user.not_found");

// 简单错误
app.throw(404, "用户不存在");

// 带业务错误码（number）
app.throw(400, "邮箱已注册", 10001);

// 带业务错误码（string）
app.throw(401, "缺少认证令牌", "UNAUTHORIZED");

// 带 i18n 参数
app.throw(400, "balance.insufficient", { balance: 50 });

// 同时带 i18n 参数和业务码
app.throw(400, "balance.insufficient", { balance: 50 }, 20001);

// 第四参数为对象或数组时，作为 details 输出
app.throw(
  502,
  "payment.failed",
  { orderId },
  {
    provider: "stripe",
    providerCode: "card_declined",
  },
);

// 同时需要 code + details 时，使用对象式入口
app.throw({
  status: 502,
  message: "payment.failed",
  code: "PAYMENT_FAILED",
  details: { provider: "stripe", providerCode: "card_declined" },
});

// 标准调用
app.throw(404, "user.not_found");

// 快捷方式（效果相同，前提是 i18n 配置中 statusCode: 404）
app.throw("user.not_found");

// 中文环境 → { code: 404, message: '用户不存在' }
// 英文环境 → { code: 404, message: 'User not found' }

config: Readonly<VextConfig>;

import { defineRoutes } from "vextjs";

export default defineRoutes((app) => {
  app.get("/info", {}, async (_req, res) => {
    res.json({
      port: app.config.port,
      adapter: typeof app.config.adapter,
      corsEnabled: app.config.cors.enabled,
    });
  });
});

services: VextServices;

// src/services/user.ts
import type { VextApp } from "vextjs";

export default class UserService {
  constructor(private app: VextApp) {}

  async findById(id: string) {
    // ...
  }
}

// src/routes/users.ts
import { defineRoutes } from "vextjs";

export default defineRoutes((app) => {
  app.get("/:id", async (req, res) => {
    const user = await app.services.user.findById(req.params.id);
    res.json(user);
  });
});

// types/vext.d.ts
import "vextjs";

declare module "vextjs" {
  interface VextServices {
    user: import("../src/services/user.js").default;
  }
}

hooks: VextHooks;

type Off = () => void;

app.hooks.on(name, handler): Off;
app.hooks.has(name): boolean;

const off = app.hooks.on("validation:success", ({ req, route }) => {
  app.logger.info(
    { requestId: req.requestId, route: route.path },
    "validated request",
  );
});

app.hooks.on("response:before", ({ headers }) => ({
  headers: { ...headers, "x-powered-by": "vext" },
}));

off(); // 演示注销：之后不再收到 validation:success，另一个监听器仍保留

cache: {
  invalidate(tag: string): Promise<void>;
  delete(key: string): Promise<void>;
  clear(): Promise<void>;
  stats(): VextCacheStats;
};

// defineRoutes 内的片段，商品写入逻辑由应用实现
app.post("/products", {}, async (req, res) => {
  // 先完成商品写入，再失效相关缓存
  await app.cache.invalidate("products");
  res.json({ created: true }, 201);
});

// 查看缓存统计
app.get("/admin/cache-stats", {}, async (req, res) => {
  res.json(app.cache.stats());
});

db?: VextDatabase; // MonSQLize + Vext 补充的只读 client getter

const users = app.db?.collection("users");
const User = app.db?.model("users");
const Invoice = app.db?.use("billing").model("BillingInvoice");
const session = app.db?.client.startSession();

// 在插件、服务方法或 handler 中，按业务需要发起请求
const response = await app.fetch("https://example.com/api/status");
if (!response.ok) {
  app.throw(502, "上游请求失败");
}

adapter: VextAdapter;

// ❌ 直接在 app 上调用会抛出错误
app.get("/hello", handler);
// 框架会提示改用路由文件中的 defineRoutes

// ✅ 通过 defineRoutes 注册
export default defineRoutes((app) => {
  app.get("/hello", handler); // OK — 这里的 app 是 collector
});

// 三段式：(path, options, handler)
app.get(
  "/users",
  {
    validate: { query: { page: "number:1-" } },
  },
  handler,
);

// 两段式：(path, handler)
app.get("/health", handler);

extend<K extends keyof VextApp>(key: K, value: VextApp[K]): void;
extend<K extends string, V>(key: K extends keyof VextApp ? never : K, value: V): void;

// 在插件中挂载
import { defineAppExtensions, definePlugin } from "vextjs";

export const appExtensions = defineAppExtensions<{
  featureFlags: Map<string, boolean>;
}>();

export default definePlugin({
  name: "feature-flags",
  setup(app) {
    const flags = new Map<string, boolean>([["search", true]]);
    app.extend("featureFlags", flags);
    app.onClose(() => flags.clear());
  },
});

// types/vext.d.ts
import "vextjs";

declare module "vextjs" {
  interface VextApp {
    featureFlags: Map<string, boolean>;
  }
}

// 业务文件中：app.featureFlags.get("search")

use(middleware: VextMiddleware): void;

import { definePlugin, securityHeaders } from "vextjs";

export default definePlugin({
  name: "security",
  setup(app) {
    app.use(securityHeaders({ preset: "strict" }));
  },
});

setValidator(validator: VextValidator): void;

import { definePlugin } from "vextjs";
import { z } from "zod";

export default definePlugin({
  name: "zod-validator",
  setup(app) {
    const originalValidator = app.getValidator();

    app.setValidator({
      compile(schema) {
        const toVextResult = (result: ReturnType<z.ZodType["safeParse"]>) =>
          result.success
            ? { valid: true, data: result.data }
            : {
                valid: false,
                errors: result.error.issues.map((issue) => ({
                  field: issue.path.join("."),
                  message: issue.message,
                })),
              };

        if (schema instanceof z.ZodType) {
          return (data) => toVextResult(schema.safeParse(data));
        }

        const fields = Object.entries(schema);
        const zodFields = fields.filter(
          ([, value]) => value instanceof z.ZodType,
        );
        if (zodFields.length > 0 && zodFields.length !== fields.length) {
          throw new Error("同一个字段对象不能混用 Zod 与 schema-dsl 定义");
        }
        if (zodFields.length > 0) {
          const zodShape = Object.fromEntries(zodFields) as Record<
            string,
            z.ZodType
          >;
          const zodSchema = z.object(zodShape);
          return (data) => toVextResult(zodSchema.safeParse(data));
        }

        return originalValidator.compile(schema);
      },
    });
  },
});

// 使用上述插件的应用：src/services/message.ts
import { VextValidationError, type VextApp, type VextValidator } from "vextjs";
import { z } from "zod";

export default class MessageService {
  private validate: ReturnType<VextValidator["compile"]>;

  constructor(app: VextApp) {
    this.validate = app.getValidator().compile({ name: z.string().min(1) });
  }

  async accept(input: unknown) {
    const result = this.validate(input);
    if (!result.valid) {
      throw new VextValidationError(result.errors ?? []);
    }
    return result.data;
  }
}

getValidator(): VextValidator;

const validator = app.getValidator();
const validate = validator.compile({ name: "string:1-50" });
const result = validate({ name: "Alice" });
// { valid: true, data: { name: 'Alice' } }

import { VextValidationError, type VextApp, type VextValidator } from "vextjs";

export default class UserService {
  private validateCreateUser: ReturnType<VextValidator["compile"]>;

  constructor(private app: VextApp) {
    this.validateCreateUser = app.getValidator().compile({
      name: "string:1-50!",
      email: "email!",
    });
  }

  async createFromMessage(input: unknown) {
    const result = this.validateCreateUser(input);
    if (!result.valid) {
      throw new VextValidationError(result.errors ?? []);
    }
    return result.data;
  }
}

setThrow(wrapper: (original: VextApp['throw']) => VextApp['throw']): void;

import { definePlugin } from "vextjs";

export default definePlugin({
  name: "error-tracking",
  setup(app) {
    const logger = app.logger;
    app.setThrow(
      (originalThrow) =>
        new Proxy(originalThrow, {
          apply(target, thisArg, args) {
            logger.debug("app.throw called");
            return Reflect.apply(target, thisArg, args);
          },
        }),
    );
  },
});

setLogger(wrapper: (original: VextRuntimeLogger) => VextLoggerLike): void;

import { definePlugin } from "vextjs";

export default definePlugin({
  name: "info-log-counter",
  setup(app) {
    let infoCalls = 0;
    const logger = app.logger;
    app.setLogger((original) => ({
      info(...args: unknown[]) {
        infoCalls += 1;
        Reflect.apply(original.info, original, args);
      },
    }));
    app.onClose(() => logger.info({ infoCalls }, "info 调用次数"));
  },
});

setRateLimiter(limiter: VextRateLimiter): void;

import { definePlugin } from "vextjs";
import { distributedLimiter } from "../shared/rate-limiter.js";

export default definePlugin({
  name: "custom-rate-limit",
  setup(app) {
    app.setRateLimiter(distributedLimiter);
  },
});

interface VextRateLimiter {
  check(key: string): Promise<{
    allowed: boolean;
    remaining: number;
    resetAt: number; // 重置时刻的绝对 Unix 时间戳，单位秒
  }>;
}

setRequestIdGenerator(generate: () => string): void;

import { definePlugin } from "vextjs";
import { randomUUID } from "node:crypto";

export default definePlugin({
  name: "prefixed-request-id",
  setup(app) {
    app.setRequestIdGenerator(() => `api-${randomUUID()}`);
  },
});

// src/config/default.ts
import { randomUUID } from "node:crypto";

export default {
  requestId: {
    generate: () => `api-${randomUUID()}`,
  },
};

onReady(handler: () => Promise<void> | void): void;

const logger = app.logger;
app.onReady(async () => {
  // warmupCache 是应用提供的预热函数
  await warmupCache();
  logger.info("缓存预热完成");
});

app.onReady(() => {
  logger.info("应用已完成初始化");
});

onClose(handler: () => Promise<void> | void): void;

// 插件内的资源清理片段，定时器由本插件创建
const healthCheckTimer = setInterval(() => {}, 30_000);
app.onClose(() => {
  clearInterval(healthCheckTimer);
});

// 自有 Redis 连接可注册 async () => { await redis.quit(); }
// redis 应由本插件创建或按约定取得，避免重复关闭共享资源

// 注册顺序
app.onClose(closeDatabase); // 第一个注册
app.onClose(closeCache); // 第二个注册

// 执行顺序（LIFO）
// 1. closeCache()   ← 后注册的先执行
// 2. closeDatabase() ← 先注册的后执行

interface AppInternals {
  lockUse(): void;
  enterPluginSetup(): void;
  exitPluginSetup(): void;
  runReady(): Promise<void>;
  getGlobalMiddlewares(): VextMiddleware[];
  getRateLimiter(): VextRateLimiter | null;
  getRequestIdGenerator(): (() => string) | null;
  shutdown(
    serverHandle?: VextServerHandle,
    options?: { skipExit?: boolean },
  ): Promise<void>;
}

async shutdown(
  serverHandle?: VextServerHandle,
  options?: { skipExit?: boolean },
): Promise<void>;

import { DEFAULT_CONFIG } from "vextjs";

import { setupShutdown } from "vextjs";

const cleanupSignals = setupShutdown({
  internals,
  serverHandle,
  logger: app.logger,
  testMode: app.config._testMode,
});

import { definePlugin } from "vextjs";

export default definePlugin({
  name: "my-plugin",
  async setup(app) {
    // ...
  },
});

import { defineRoutes } from "vextjs";

export default defineRoutes((app) => {
  app.get("/hello", {}, async (_req, res) => {
    res.json({ message: "Hello!" });
  });
});

import { defineMiddleware, defineMiddlewareFactory } from "vextjs";

// 无配置中间件
export default defineMiddleware(async (req, res, next) => {
  // ...
  await next();
});

// 带配置的中间件工厂
export default defineMiddlewareFactory((options) => {
  return async (req, res, next) => {
    // 使用 options...
    await next();
  };
});

import type {
  VextApp,
  VextConfig,
  VextUserConfig,
  VextServices,
  VextLogger,
  VextRuntimeLogger,
  VextLoggerLike,
  VextCacheStats,
  VextFetch,
  VextHooks,
  VextRateLimiter,
  VextValidator,
} from "vextjs";

import type { AppInternals, BootstrapResult } from "vextjs";

// src/config/default.ts
import type { VextUserConfig } from "vextjs";

export default {
  port: 3000,
  host: "127.0.0.1",
  adapter: "native",
  frontend: { enabled: false },
  logger: { level: "info" },
} satisfies VextUserConfig;

// src/plugins/demo-users.ts
import { defineAppExtensions, definePlugin } from "vextjs";

export type DemoUser = { id: string; name: string; email: string };

export const appExtensions = defineAppExtensions<{
  demoUsers: Map<string, DemoUser>;
}>();

export default definePlugin({
  name: "demo-users",
  setup(app) {
    const users = new Map<string, DemoUser>([
      ["1", { id: "1", name: "Alice", email: "alice@example.com" }],
    ]);
    const logger = app.logger;
    app.extend("demoUsers", users);
    app.onReady(() => {
      logger.info({ count: users.size }, "用户存储已就绪");
    });
    app.onClose(() => {
      users.clear();
      logger.info({ count: users.size }, "用户存储已清理");
    });
  },
});

// src/services/user.ts
import { randomUUID } from "node:crypto";
import type { VextApp } from "vextjs";

export default class UserService {
  constructor(private app: VextApp) {}

  async findAll({ page, limit }: { page: number; limit: number }) {
    return [...this.app.demoUsers.values()].slice(
      (page - 1) * limit,
      page * limit,
    );
  }

  async findById(id: string) {
    const user = this.app.demoUsers.get(id);
    if (!user) {
      return this.app.throw(404, "用户不存在");
    }

    return user;
  }

  async create(data: { name: string; email: string }) {
    const existing = [...this.app.demoUsers.values()].some(
      (user) => user.email === data.email,
    );
    if (existing) {
      return this.app.throw(409, "邮箱已注册", 10001);
    }

    const user = { id: randomUUID(), ...data };
    this.app.demoUsers.set(user.id, user);
    return user;
  }
}

// src/routes/users.ts
import { defineRoutes } from "vextjs";

export default defineRoutes((app) => {
  app.get(
    "/list",
    {
      validate: {
        query: { page: "number:1-", limit: "number:1-100" },
      },
      docs: {
        summary: "用户列表",
      },
    },
    async (req, res) => {
      const { page = 1, limit = 20 } = req.valid("query");
      const users = await app.services.user.findAll({ page, limit });
      res.json(users);
    },
  );

  app.get(
    "/:id",
    {
      validate: { param: { id: "string:1-!" } },
      docs: { summary: "获取用户详情" },
    },
    async (req, res) => {
      const user = await app.services.user.findById(req.valid("param").id);
      res.json(user);
    },
  );

  app.post(
    "/",
    {
      validate: {
        body: { name: "string:1-50!", email: "email!" },
      },
      docs: { summary: "创建用户" },
    },
    async (req, res) => {
      const user = await app.services.user.create(req.valid("body"));
      res.json(user, 201);
    },
  );
});