@svton/cli 1.2.0 → 1.2.2

package/templates/examples/queue/email.service.ts

@@ -0,0 +1,64 @@
+import { Injectable } from '@nestjs/common';
+import { QueueService } from '@svton/nestjs-queue';
+import { EmailData } from './email.processor';
+
+@Injectable()
+export class EmailService {
+  constructor(private readonly queueService: QueueService) {}
+
+  /**
+   * 发送单个邮件
+   */
+  async sendEmail(data: EmailData): Promise<void> {
+    await this.queueService.addJob('email', 'send', data);
+  }
+
+  /**
+   * 延迟发送邮件
+   */
+  async sendEmailDelayed(data: EmailData, delayMs: number): Promise<void> {
+    await this.queueService.addJob('email', 'send', data, {
+      delay: delayMs,
+    });
+  }
+
+  /**
+   * 发送邮件（带重试）
+   */
+  async sendEmailWithRetry(data: EmailData): Promise<void> {
+    await this.queueService.addJob('email', 'send', data, {
+      attempts: 3,
+      backoff: {
+        type: 'exponential',
+        delay: 1000,
+      },
+    });
+  }
+
+  /**
+   * 批量发送邮件
+   */
+  async sendBatchEmails(emails: EmailData[]): Promise<void> {
+    await this.queueService.addJob('email', 'sendBatch', { emails });
+  }
+
+  /**
+   * 定时发送邮件
+   */
+  async scheduleEmail(data: EmailData, cron: string): Promise<void> {
+    await this.queueService.addJob('email', 'send', data, {
+      repeat: {
+        cron, // 例如: '0 9 * * *' 每天 9 点
+      },
+    });
+  }
+
+  /**
+   * 高优先级邮件
+   */
+  async sendUrgentEmail(data: EmailData): Promise<void> {
+    await this.queueService.addJob('email', 'send', data, {
+      priority: 1, // 数字越小优先级越高
+    });
+  }
+}

package/templates/examples/rate-limit/README.md

@@ -0,0 +1,249 @@
+# 限流功能示例
+
+本示例展示如何使用 `@svton/nestjs-rate-limit` 模块实现接口限流。
+
+## 文件说明
+
+- `api.controller.ts` - API 控制器，展示不同的限流策略
+
+## 核心装饰器
+
+### @RateLimit - 接口限流
+
+```typescript
+@RateLimit({ ttl: 60, limit: 10 })
+@Get('api')
+async api() {
+  return { message: 'Success' };
+}
+```
+
+参数说明：
+- `ttl`：时间窗口（秒）
+- `limit`：时间窗口内最大请求数
+
+### @UseGuards(RateLimitGuard) - 启用限流
+
+```typescript
+@Controller('api')
+@UseGuards(RateLimitGuard)
+export class ApiController {
+  // 所有接口都会应用限流
+}
+```
+
+## 限流策略
+
+### 1. 普通接口限流
+
+适用于一般 API 接口：
+
+```typescript
+@RateLimit({ ttl: 60, limit: 10 })  // 每分钟 10 次
+```
+
+### 2. 严格限流
+
+适用于敏感操作：
+
+```typescript
+@RateLimit({ ttl: 60, limit: 3 })  // 每分钟 3 次
+```
+
+### 3. 防暴力破解
+
+适用于登录、注册等接口：
+
+```typescript
+@RateLimit({ ttl: 60, limit: 5 })  // 每分钟 5 次
+```
+
+### 4. 验证码限流
+
+防止验证码被刷：
+
+```typescript
+@RateLimit({ ttl: 60, limit: 1 })  // 每分钟 1 次
+```
+
+### 5. 搜索接口限流
+
+高频接口：
+
+```typescript
+@RateLimit({ ttl: 1, limit: 10 })  // 每秒 10 次
+```
+
+## 测试接口
+
+### 普通限流（每分钟 10 次）
+
+```bash
+# 快速请求 15 次，第 11 次开始会被限流
+for i in {1..15}; do
+  curl http://localhost:3000/examples/api/normal
+  echo ""
+done
+```
+
+### 严格限流（每分钟 3 次）
+
+```bash
+# 快速请求 5 次，第 4 次开始会被限流
+for i in {1..5}; do
+  curl http://localhost:3000/examples/api/strict
+  echo ""
+done
+```
+
+### 验证码限流（每分钟 1 次）
+
+```bash
+# 请求 2 次，第 2 次会被限流
+curl -X POST http://localhost:3000/examples/api/send-code
+curl -X POST http://localhost:3000/examples/api/send-code
+```
+
+## 限流响应
+
+当请求被限流时，会返回 429 状态码：
+
+```json
+{
+  "statusCode": 429,
+  "message": "Too Many Requests",
+  "error": "Rate limit exceeded"
+}
+```
+
+响应头会包含限流信息：
+
+```
+X-RateLimit-Limit: 10
+X-RateLimit-Remaining: 0
+X-RateLimit-Reset: 1234567890
+```
+
+## 环境变量配置
+
+在 `.env` 文件中配置：
+
+```env
+REDIS_HOST=localhost
+REDIS_PORT=6379
+REDIS_PASSWORD=
+```
+
+## 全局限流配置
+
+在 `app.module.ts` 中配置全局限流：
+
+```typescript
+RateLimitModule.forRoot({
+  redis: {
+    host: process.env.REDIS_HOST,
+    port: parseInt(process.env.REDIS_PORT),
+  },
+  global: {
+    ttl: 60,
+    limit: 100,
+  },
+});
+```
+
+## 自定义限流 Key
+
+默认使用 IP 地址作为限流 key，可以自定义：
+
+```typescript
+@RateLimit({
+  ttl: 60,
+  limit: 10,
+  keyGenerator: (req) => {
+    // 使用用户 ID 作为 key
+    return req.user?.id || req.ip;
+  },
+})
+```
+
+## 最佳实践
+
+1. **合理设置限流**：根据接口特点设置不同的限流策略
+2. **分级限流**：普通用户和 VIP 用户使用不同的限流规则
+3. **白名单机制**：内部服务或管理员不受限流限制
+4. **友好提示**：返回清晰的错误信息和重试时间
+5. **监控告警**：监控限流触发情况，及时发现异常
+
+## 常见场景
+
+### 登录接口
+
+```typescript
+@Post('login')
+@RateLimit({ ttl: 60, limit: 5 })  // 防暴力破解
+async login() { }
+```
+
+### 注册接口
+
+```typescript
+@Post('register')
+@RateLimit({ ttl: 3600, limit: 3 })  // 每小时 3 次
+async register() { }
+```
+
+### 发送验证码
+
+```typescript
+@Post('send-code')
+@RateLimit({ ttl: 60, limit: 1 })  // 每分钟 1 次
+async sendCode() { }
+```
+
+### 搜索接口
+
+```typescript
+@Get('search')
+@RateLimit({ ttl: 1, limit: 10 })  // 每秒 10 次
+async search() { }
+```
+
+### 文件上传
+
+```typescript
+@Post('upload')
+@RateLimit({ ttl: 60, limit: 5 })  // 每分钟 5 次
+async upload() { }
+```
+
+## 高级用法
+
+### 动态限流
+
+根据用户等级动态调整限流：
+
+```typescript
+@RateLimit({
+  ttl: 60,
+  limit: (req) => {
+    const user = req.user;
+    if (user?.vip) return 100;  // VIP 用户
+    return 10;  // 普通用户
+  },
+})
+```
+
+### 组合限流
+
+同时应用多个限流规则：
+
+```typescript
+@RateLimit({ ttl: 1, limit: 10 })    // 每秒 10 次
+@RateLimit({ ttl: 60, limit: 100 })  // 每分钟 100 次
+@Get('api')
+async api() { }
+```
+
+## 更多信息
+
+查看官方文档：https://751848178.github.io/svton/packages/nestjs-rate-limit

package/templates/examples/rate-limit/api.controller.ts

@@ -0,0 +1,113 @@
+import { Controller, Get, Post, UseGuards } from '@nestjs/common';
+import { RateLimit, RateLimitGuard } from '@svton/nestjs-rate-limit';
+
+@Controller('examples/api')
+@UseGuards(RateLimitGuard)
+export class ApiController {
+  /**
+   * 普通接口 - 每分钟 10 次
+   */
+  @Get('normal')
+  @RateLimit({ ttl: 60, limit: 10 })
+  normal() {
+    return {
+      message: 'Normal API',
+      timestamp: Date.now(),
+    };
+  }
+
+  /**
+   * 严格限流 - 每分钟 3 次
+   */
+  @Get('strict')
+  @RateLimit({ ttl: 60, limit: 3 })
+  strict() {
+    return {
+      message: 'Strict rate limit API',
+      timestamp: Date.now(),
+    };
+  }
+
+  /**
+   * 宽松限流 - 每分钟 100 次
+   */
+  @Get('loose')
+  @RateLimit({ ttl: 60, limit: 100 })
+  loose() {
+    return {
+      message: 'Loose rate limit API',
+      timestamp: Date.now(),
+    };
+  }
+
+  /**
+   * 短时限流 - 每 10 秒 5 次
+   */
+  @Get('short-window')
+  @RateLimit({ ttl: 10, limit: 5 })
+  shortWindow() {
+    return {
+      message: 'Short window rate limit API',
+      timestamp: Date.now(),
+    };
+  }
+
+  /**
+   * 长时限流 - 每小时 1000 次
+   */
+  @Get('long-window')
+  @RateLimit({ ttl: 3600, limit: 1000 })
+  longWindow() {
+    return {
+      message: 'Long window rate limit API',
+      timestamp: Date.now(),
+    };
+  }
+
+  /**
+   * 登录接口 - 每分钟 5 次（防暴力破解）
+   */
+  @Post('login')
+  @RateLimit({ ttl: 60, limit: 5 })
+  login() {
+    return {
+      message: 'Login API',
+      token: 'mock_token',
+    };
+  }
+
+  /**
+   * 发送验证码 - 每分钟 1 次
+   */
+  @Post('send-code')
+  @RateLimit({ ttl: 60, limit: 1 })
+  sendCode() {
+    return {
+      message: 'Verification code sent',
+      code: '123456', // 开发环境返回
+    };
+  }
+
+  /**
+   * 搜索接口 - 每秒 10 次
+   */
+  @Get('search')
+  @RateLimit({ ttl: 1, limit: 10 })
+  search() {
+    return {
+      message: 'Search API',
+      results: [],
+    };
+  }
+
+  /**
+   * 无限流接口（用于测试）
+   */
+  @Get('unlimited')
+  unlimited() {
+    return {
+      message: 'Unlimited API',
+      timestamp: Date.now(),
+    };
+  }
+}

package/templates/examples/sms/README.md

@@ -0,0 +1,121 @@
+# 短信功能示例
+
+本示例展示如何使用 `@svton/nestjs-sms` 模块发送短信。
+
+## 文件说明
+
+- `sms.service.ts` - 短信服务，封装发送逻辑
+- `verification.controller.ts` - 验证码控制器，提供发送和验证接口
+
+## 核心功能
+
+### 发送验证码
+
+```typescript
+await this.smsService.sendVerificationCode('13800138000', '123456');
+```
+
+### 发送通知短信
+
+```typescript
+await this.smsService.sendNotification('13800138000', {
+  message: '您的订单已发货',
+});
+```
+
+### 批量发送
+
+```typescript
+await this.smsService.sendBatch(
+  ['13800138000', '13800138001'],
+  'SMS_123456',
+  { code: '123456' },
+);
+```
+
+## 测试接口
+
+```bash
+# 发送验证码
+curl -X POST http://localhost:3000/examples/verification/send-code \
+  -H "Content-Type: application/json" \
+  -d '{"phoneNumber":"13800138000"}'
+
+# 验证验证码
+curl -X POST http://localhost:3000/examples/verification/verify-code \
+  -H "Content-Type: application/json" \
+  -d '{
+    "phoneNumber":"13800138000",
+    "code":"123456"
+  }'
+
+# 发送通知短信
+curl -X POST http://localhost:3000/examples/verification/send-notification \
+  -H "Content-Type: application/json" \
+  -d '{
+    "phoneNumber":"13800138000",
+    "message":"您的订单已发货"
+  }'
+```
+
+## 环境变量配置
+
+在 `.env` 文件中配置：
+
+```env
+SMS_PROVIDER=aliyun
+SMS_ACCESS_KEY_ID=your_access_key_id
+SMS_ACCESS_KEY_SECRET=your_access_key_secret
+SMS_SIGN_NAME=your_sign_name
+```
+
+## 短信模板配置
+
+需要在阿里云/腾讯云后台配置短信模板：
+
+1. 登录短信服务控制台
+2. 创建短信模板
+3. 等待审核通过
+4. 将模板 ID 替换到代码中的 `SMS_123456`
+
+## 最佳实践
+
+1. **频率限制**：同一手机号 1 分钟内只能发送一次
+2. **验证码有效期**：建议 5 分钟
+3. **使用 Redis**：生产环境使用 Redis 存储验证码
+4. **防刷机制**：添加图形验证码或滑块验证
+5. **日志记录**：记录发送日志，便于排查问题
+
+## 常见场景
+
+### 注册验证
+
+```typescript
+// 1. 发送验证码
+await this.smsService.sendVerificationCode(phoneNumber, code);
+
+// 2. 用户输入验证码
+// 3. 验证通过后创建账号
+```
+
+### 登录验证
+
+```typescript
+// 1. 发送验证码
+await this.smsService.sendVerificationCode(phoneNumber, code);
+
+// 2. 验证码验证通过后生成 token
+```
+
+### 订单通知
+
+```typescript
+await this.smsService.sendNotification(phoneNumber, {
+  orderNo: 'ORDER_001',
+  status: '已发货',
+});
+```
+
+## 更多信息
+
+查看官方文档：https://751848178.github.io/svton/packages/nestjs-sms

package/templates/examples/sms/sms.service.ts

@@ -0,0 +1,69 @@
+import { Injectable } from '@nestjs/common';
+import { SmsService as SvtonSmsService } from '@svton/nestjs-sms';
+
+@Injectable()
+export class SmsService {
+  constructor(private readonly smsService: SvtonSmsService) {}
+
+  /**
+   * 发送验证码短信
+   */
+  async sendVerificationCode(phoneNumber: string, code: string): Promise<void> {
+    await this.smsService.send({
+      phoneNumber,
+      templateCode: 'SMS_123456', // TODO: 替换为实际的模板 ID
+      templateParams: {
+        code,
+      },
+    });
+  }
+
+  /**
+   * 发送通知短信
+   */
+  async sendNotification(
+    phoneNumber: string,
+    params: Record<string, string>,
+  ): Promise<void> {
+    await this.smsService.send({
+      phoneNumber,
+      templateCode: 'SMS_234567', // TODO: 替换为实际的模板 ID
+      templateParams: params,
+    });
+  }
+
+  /**
+   * 批量发送短信
+   */
+  async sendBatch(
+    phoneNumbers: string[],
+    templateCode: string,
+    templateParams: Record<string, string>,
+  ): Promise<void> {
+    await Promise.all(
+      phoneNumbers.map((phoneNumber) =>
+        this.smsService.send({
+          phoneNumber,
+          templateCode,
+          templateParams,
+        }),
+      ),
+    );
+  }
+
+  /**
+   * 发送营销短信
+   */
+  async sendMarketing(
+    phoneNumber: string,
+    content: string,
+  ): Promise<void> {
+    await this.smsService.send({
+      phoneNumber,
+      templateCode: 'SMS_345678', // TODO: 替换为实际的模板 ID
+      templateParams: {
+        content,
+      },
+    });
+  }
+}

package/templates/examples/sms/verification.controller.ts

@@ -0,0 +1,100 @@
+import { Controller, Post, Body, HttpCode } from '@nestjs/common';
+import { SmsService } from './sms.service';
+
+interface SendCodeDto {
+  phoneNumber: string;
+}
+
+interface VerifyCodeDto {
+  phoneNumber: string;
+  code: string;
+}
+
+@Controller('examples/verification')
+export class VerificationController {
+  // 简单的内存存储，实际项目应使用 Redis
+  private verificationCodes = new Map<string, { code: string; expiresAt: number }>();
+
+  constructor(private readonly smsService: SmsService) {}
+
+  /**
+   * 发送验证码
+   */
+  @Post('send-code')
+  @HttpCode(200)
+  async sendCode(@Body() dto: SendCodeDto) {
+    // 生成 6 位验证码
+    const code = Math.floor(100000 + Math.random() * 900000).toString();
+
+    // 存储验证码（5 分钟有效期）
+    this.verificationCodes.set(dto.phoneNumber, {
+      code,
+      expiresAt: Date.now() + 5 * 60 * 1000,
+    });
+
+    // 发送短信
+    await this.smsService.sendVerificationCode(dto.phoneNumber, code);
+
+    return {
+      message: 'Verification code sent successfully',
+      // 开发环境返回验证码，生产环境不应返回
+      ...(process.env.NODE_ENV === 'development' && { code }),
+    };
+  }
+
+  /**
+   * 验证验证码
+   */
+  @Post('verify-code')
+  @HttpCode(200)
+  async verifyCode(@Body() dto: VerifyCodeDto) {
+    const stored = this.verificationCodes.get(dto.phoneNumber);
+
+    if (!stored) {
+      return {
+        success: false,
+        message: 'Verification code not found',
+      };
+    }
+
+    if (Date.now() > stored.expiresAt) {
+      this.verificationCodes.delete(dto.phoneNumber);
+      return {
+        success: false,
+        message: 'Verification code expired',
+      };
+    }
+
+    if (stored.code !== dto.code) {
+      return {
+        success: false,
+        message: 'Invalid verification code',
+      };
+    }
+
+    // 验证成功，删除验证码
+    this.verificationCodes.delete(dto.phoneNumber);
+
+    return {
+      success: true,
+      message: 'Verification successful',
+    };
+  }
+
+  /**
+   * 发送通知短信
+   */
+  @Post('send-notification')
+  @HttpCode(200)
+  async sendNotification(
+    @Body() dto: { phoneNumber: string; message: string },
+  ) {
+    await this.smsService.sendNotification(dto.phoneNumber, {
+      message: dto.message,
+    });
+
+    return {
+      message: 'Notification sent successfully',
+    };
+  }
+}