#应用实例

import { bootstrap } from 'vextjs';

bootstrap();

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

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

// 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);
      };
    });
  },
});

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);
  });
});