# SecurityCore 核心安全模块

SecurityCore 是应用的核心安全防护模块，提供系统级的安全防护功能，包括频率限制、超时控制、内容类型验证和维护模式管理，具备完整的监控日志和配置化设计能力。

## 频率限制功能

### Throttle()
频率限制装饰器，支持基于IP和用户的多层次限制策略，防止API滥用和暴力攻击。

### canActivate()
守卫检查方法，实现频率限制的核心逻辑，支持时间窗口和计数管理。

### getStats()
获取频率限制的实时统计信息，用于监控和调试。

### clearAllRecords()
清除所有频率限制记录，用于管理和重置。

### clearRecord()
清除指定键的频率限制记录，用于精确管理。

## 超时控制功能

### Timeout()
超时装饰器，为API接口添加超时控制，防止长时间运行的请求阻塞系统。

### intercept()
拦截器处理方法，实现超时控制逻辑和异常处理。

## 内容类型验证功能

### use()
中间件处理方法，验证POST/PUT请求的Content-Type头，确保API接收正确的数据格式。

### getSupportedTypes()
获取当前支持的Content-Type列表。

### addSupportedType()
动态添加支持的Content-Type类型。

### addExcludePath()
添加不需要验证Content-Type的路径规则。

## 维护模式管理功能

### use()
中间件处理方法，检查系统维护模式状态，在维护期间阻止用户访问。

### isMaintenanceEnabled()
检查维护模式是否启用。

### getMaintenanceInfo()
获取完整的维护配置信息，包括开始时间、结束时间和原因。

## 使用的项目内部依赖

### ThrottleConfig (本模块)
频率限制配置接口，定义限制次数、时间窗口、限制类型和错误消息。

### TimeoutConfig (本模块)
超时配置接口，定义超时时间、错误消息和日志记录选项。

### ThrottlePresets (本模块)
预定义的频率限制配置常量，包含登录、注册、验证码等常用场景的限制模板。

### TimeoutPresets (本模块)
预定义的超时配置常量，包含快速操作、文件处理、数据库查询等场景的超时模板。

### THROTTLE_KEY (本模块)
频率限制元数据键常量，用于装饰器元数据存储。

### TIMEOUT_KEY (本模块)
超时元数据键常量，用于装饰器元数据存储。

### @nestjs/common (来自 NestJS框架)
提供装饰器、异常处理、日志记录等核心功能支持。

### @nestjs/core (来自 NestJS框架)
提供反射器、全局守卫和拦截器注册功能。

### @nestjs/config (来自 NestJS框架)
提供配置服务，用于读取环境变量和应用配置。

### @nestjs/swagger (来自 NestJS框架)
提供API文档生成和响应模式定义功能。

### express (来自 Express框架)
提供HTTP请求响应对象的类型定义。

### rxjs (来自 RxJS库)
提供响应式编程操作符，用于超时控制和异常处理。

## 核心特性

### 多层次安全防护
- 频率限制：支持基于IP和用户的双重限制策略，防止API滥用和暴力攻击
- 超时控制：防止长时间运行请求占用系统资源，提升系统稳定性
- 内容验证：确保API接收符合规范的数据格式，防止格式错误
- 维护模式：提供系统维护期间的访问控制，支持优雅的服务中断

### 配置化设计
- 装饰器配置：支持方法级和类级的灵活配置方式，使用简单直观
- 预设模板：提供常用安全场景的预定义配置，开箱即用
- 环境变量：支持通过环境变量进行动态配置，适应不同部署环境
- 运行时调整：支持动态添加规则和排除路径，无需重启服务

### 监控和日志
- 详细日志：记录所有安全事件、异常情况和性能指标，便于问题排查
- 统计信息：提供频率限制的实时统计和历史数据，支持监控分析
- 错误追踪：完整的错误信息记录和上下文保存，提升调试效率
- 性能监控：记录请求处理时间和资源使用情况，优化系统性能

### 高可用设计
- 内存管理：自动清理过期记录，防止内存泄漏和资源浪费
- 异常处理：完善的异常捕获和恢复机制，保证系统稳定运行
- 资源清理：组件销毁时自动清理定时器和资源，避免资源泄漏
- 降级策略：配置缺失时的默认行为和安全降级，保证基本功能

## 潜在风险

### 内存使用风险
- 频率限制记录存储在内存中，高并发场景可能占用大量内存资源
- 大量并发请求时清理任务可能影响系统性能和响应时间
- 应用重启后所有限制记录会丢失，可能导致限制策略失效
- 建议监控内存使用情况，考虑使用Redis等外部存储方案

### 配置管理风险
- 错误的频率限制配置可能导致正常用户被误限，影响用户体验
- 维护模式配置错误可能导致服务长时间不可用，影响业务连续性
- 超时配置过短可能导致正常请求被误杀，过长则失去保护作用
- 建议提供配置验证机制和紧急恢复方案，定期检查配置合理性

### 单点故障风险
- 内存存储的限制记录在应用重启后会丢失，无法保持状态连续性
- 依赖单一应用实例的状态管理，不适合分布式部署和负载均衡
- 配置服务异常可能导致安全功能失效，存在安全隐患
- 建议在生产环境使用持久化存储和分布式状态管理方案

### 性能瓶颈风险
- 高频率的限制检查可能成为请求处理的性能瓶颈，影响系统吞吐量
- 复杂的正则表达式匹配可能影响中间件处理速度，增加延迟
- 频繁的日志记录在高并发场景下可能影响系统性能
- 建议进行性能测试和优化，使用缓存减少重复计算，合理设置日志级别