#应用实例

import { bootstrap } from "vextjs";

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 } = await bootstrap();

// app: VextApp 实例
// serverHandle: HTTP 服务器句柄（用于获取监听地址等）
console.log(`服务器运行在 http://${app.config.host}:${app.config.port}`);

import { createApp, DEFAULT_CONFIG } from "vextjs";

const { app, internals } = createApp(config);

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

logger: VextLogger;

// 基本使用
app.logger.info("服务器启动成功");
app.logger.error({ userId: "123" }, "用户查询失败");
app.logger.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;

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

// 在服务中创建专属 logger
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;

// 标准调用（显式指定 HTTP 状态码）
throw(
  status: number,
  message: string,
  paramsOrCode?: Record<string, unknown> | number | string,
  code?: number | string,
): 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);

// 标准调用
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>;

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
export default class UserService {
  constructor(private app: VextApp) {}

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

// src/routes/users.ts
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
declare module "vextjs" {
  interface VextServices {
    user: import("../src/services/user").default;
    order: import("../src/services/order").default;
  }
}

cache: {
  invalidate(tag: string): Promise<void>;
  delete(key: string): Promise<void>;
  clear(): Promise<void>;
  stats(): { entries: number; hits: number; misses: number; hitRate: number };
};

// 商品更新后失效相关缓存
app.post("/products", {}, async (req, res) => {
  await db.createProduct(req.body);
  await app.cache.invalidate("products");
  res.json({ created: true }, 201);
});

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

adapter: VextAdapter;

// ❌ 直接在 app 上调用会抛出错误
app.get("/hello", handler);
// Error: [vextjs] app.get() cannot be called directly on the app instance.
// Use defineRoutes(app => { app.get(...) }) in route files.

// ✅ 通过 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 string, V>(key: K, value: V): void;

// 在插件中挂载
import { definePlugin } from "vextjs";
import Redis from "ioredis";

export default definePlugin({
  name: "redis",
  async setup(app) {
    const redis = new Redis(app.config.redis);
    app.extend("cache", redis);
    app.onClose(() => redis.quit());
  },
});

// types/vext.d.ts
declare module "vextjs" {
  interface VextApp {
    cache: import("ioredis").Redis;
  }
}

// 使用时有类型提示
app.cache.get("key"); // ✅ IDE 知道是 Redis 实例

use(middleware: VextMiddleware): void;

import { definePlugin, defineMiddleware } from "vextjs";

const securityHeaders = defineMiddleware(async (_req, res, next) => {
  res.setHeader("X-Content-Type-Options", "nosniff");
  res.setHeader("X-Frame-Options", "DENY");
  await next();
});

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

setValidator(validator: VextValidator): void;

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

export default definePlugin({
  name: "zod-validator",
  setup(app) {
    app.setValidator({
      compile(schema) {
        const zodSchema = z.object(schema);
        return (data) => {
          const result = zodSchema.safeParse(data);
          if (result.success) {
            return { valid: true, data: result.data };
          }
          return {
            valid: false,
            errors: result.error.issues.map((issue) => ({
              field: issue.path.join("."),
              message: issue.message,
            })),
          };
        };
      },
    });
  },
});

getValidator(): VextValidator;

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

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

import { definePlugin } from "vextjs";

export default definePlugin({
  name: "error-tracking",
  setup(app) {
    app.setThrow((originalThrow) => {
      return (status, message, paramsOrCode, code) => {
        // 上报错误到监控平台
        if (status >= 500) {
          errorTracker.captureError(new Error(message), { status });
        }
        // 调用原始实现
        return originalThrow(status, message, paramsOrCode, code);
      };
    });
  },
});

setLogger(wrapper: (original: VextLogger) => VextLogger): void;

import { definePlugin } from "vextjs";
import type { VextLogger } from "vextjs";

export default definePlugin({
  name: "otel-logger-bridge",
  setup(app) {
    app.setLogger((original) => ({
      info(...args: unknown[]) {
        otelBridge.emit("info", extractMsg(args));
        (original.info as (...a: unknown[]) => void)(...args);
      },
      warn(...args: unknown[]) {
        otelBridge.emit("warn", extractMsg(args));
        (original.warn as (...a: unknown[]) => void)(...args);
      },
      error(...args: unknown[]) {
        otelBridge.emit("error", extractMsg(args));
        (original.error as (...a: unknown[]) => void)(...args);
      },
      debug(...args: unknown[]) {
        (original.debug as (...a: unknown[]) => void)(...args);
      },
      fatal(...args: unknown[]) {
        otelBridge.emit("fatal", extractMsg(args));
        (original.fatal as (...a: unknown[]) => void)(...args);
      },
      child: (bindings) => original.child(bindings),
    }));
  },
});

setRateLimiter(limiter: VextRateLimiter): void;

import { definePlugin } from "vextjs";

export default definePlugin({
  name: "redis-rate-limit",
  async setup(app) {
    const redis = app.cache; // 假设 redis 插件已先加载

    app.setRateLimiter({
      async check(key) {
        const current = await redis.incr(`rl:${key}`);
        if (current === 1) {
          await redis.expire(`rl:${key}`, app.config.rateLimit.window);
        }
        const max = app.config.rateLimit.max;
        return {
          allowed: current <= max,
          remaining: Math.max(0, max - current),
          resetAt: Date.now() + app.config.rateLimit.window * 1000,
        };
      },
    });
  },
});

interface VextRateLimiter {
  check(key: string): Promise<{
    allowed: boolean;
    remaining: number;
    resetAt: number;
  }>;
}

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

import { definePlugin } from "vextjs";
import { nanoid } from "nanoid";

export default definePlugin({
  name: "nanoid-request-id",
  setup(app) {
    app.setRequestIdGenerator(() => nanoid(21));
  },
});

// src/config/default.ts
import { nanoid } from "nanoid";

export default {
  requestId: {
    generate: () => nanoid(),
  },
};

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

app.onReady(async () => {
  await warmupCache();
  app.logger.info("缓存预热完成");
});

app.onReady(() => {
  app.logger.info(`服务器运行在 http://${app.config.host}:${app.config.port}`);
});

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

// 数据库连接清理
app.onClose(async () => {
  await app.db.disconnect();
  app.logger.info("数据库连接已关闭");
});

// 定时任务取消
app.onClose(() => {
  clearInterval(healthCheckTimer);
});

// Redis 连接关闭
app.onClose(async () => {
  await app.cache.quit();
});

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

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

interface AppInternals {
  lockUse(): 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";

setupShutdown(app, serverHandle, internals);

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,
  VextRateLimiter,
  VextValidator,
} from "vextjs";

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

// src/plugins/database.ts
import { definePlugin } from "vextjs";
import { createPool } from "./db";

export default definePlugin({
  name: "database",
  async setup(app) {
    // 1. 创建数据库连接池
    const pool = await createPool(app.config.database);

    // 2. 挂载到 app
    app.extend("db", pool);

    // 3. 注册就绪钩子
    app.onReady(async () => {
      const result = await pool.query("SELECT 1");
      app.logger.info("数据库连接验证成功");
    });

    // 4. 注册关闭钩子
    app.onClose(async () => {
      await pool.end();
      app.logger.info("数据库连接池已关闭");
    });
  },
});

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

export default class UserService {
  private logger;

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

  async findById(id: string) {
    this.logger.info({ userId: id }, "查询用户");
    const user = await this.app.db.query("SELECT * FROM users WHERE id = ?", [
      id,
    ]);

    if (!user) {
      this.app.throw(404, "user.not_found");
    }

    return user;
  }

  async create(data: { name: string; email: string }) {
    this.logger.info({ email: data.email }, "创建用户");

    const existing = await this.app.db.query(
      "SELECT id FROM users WHERE email = ?",
      [data.email],
    );
    if (existing) {
      this.app.throw(409, "邮箱已注册", 10001);
    }

    return this.app.db.query("INSERT INTO users (name, email) VALUES (?, ?)", [
      data.name,
      data.email,
    ]);
  }
}

// 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: "用户列表",
        tags: ["用户"],
      },
    },
    async (req, res) => {
      const { page, limit } = 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" },
      },
      middlewares: ["auth"],
      docs: { summary: "创建用户" },
    },
    async (req, res) => {
      const user = await app.services.user.create(req.valid("body"));
      res.json(user, 201);
    },
  );
});