领度 PHP 框架（LingDuCodePHP） 是一款零依赖、轻量、高性能的国产开源 PHP 框架，专为快速开发与 AI 辅助编程设计，无需 Composer 即可独立运行。

开源下载地址：https://gitee.com/lingdubingfeng/ling-du-php-framework

# LingDuCodePHP 框架特性文档

> 版本：2.0.0 | 永久性免费开源·支持个企商业使用  
> 官网：http://lingducode.cn  
> 许可证：Apache License 2.0

---

## 一、框架概述

LingDuCodePHP 是一款基于 PHP 8.0+ 的企业级 MVC 开发框架，采用零依赖设计，所有核心组件自研实现。框架以安全、高性能、易扩展为核心设计理念，内置丰富的企业级功能模块，适用于中大型 Web 应用、API 服务、后台管理系统等场景。

### 核心设计原则

- **零依赖** — 无 Composer 依赖，所有核心组件自研，部署零门槛
- **安全优先** — 全链路安全防护，从请求到响应的每个环节均有安全机制
- **模块化架构** — 模块/插件双扩展体系，功能即插即用
- **多驱动支持** — 缓存、队列、数据库、短信、存储等均支持多驱动切换
- **生产就绪** — 内置熔断、限流、链路追踪、健康检查等微服务治理能力

---

## 二、系统要求

| 项目 | 要求 |
|------|------|
| PHP 版本 | >= 8.0 |
| PDO 扩展 | 必须（pdo_mysql） |
| MBString 扩展 | 必须 |
| cURL 扩展 | 必须 |
| OpenSSL 扩展 | 必须 |
| FileInfo 扩展 | 必须 |
| GD 扩展 | 必须 |
| 数据库 | MySQL 5.7+ / PostgreSQL / SQLite / SQL Server |

---

## 三、目录结构

```
LingDuCodePHP/
├── app/                          # 应用目录
│   ├── admin/                    # 后台管理模块
│   │   ├── controller/           # 控制器
│   │   ├── middleware/           # 中间件
│   │   └── view/                 # 视图模板
│   ├── api/                      # API 接口模块
│   │   ├── controller/
│   │   └── middleware/
│   ├── common/                   # 公共模块
│   │   ├── controller/
│   │   ├── model/
│   │   ├── validate/
│   │   └── trait/
│   ├── index/                    # 前台模块
│   ├── install/                  # 安装向导
│   ├── user/                     # 用户中心模块
│   └── providers/                # 服务提供者
├── config/                       # 配置文件
│   ├── app.php                   # 应用配置
│   ├── database.php              # 数据库配置
│   ├── cache.php                 # 缓存配置
│   ├── route.php                 # 路由配置
│   ├── mail.php                  # 邮件配置
│   ├── sms.php                   # 短信配置
│   ├── upload.php                # 上传配置
│   ├── auth.php                  # 实名认证配置
│   ├── log.php                   # 日志配置
│   └── session.php               # 会话配置
├── framework/                    # 框架核心
│   ├── core/                     # 核心组件
│   ├── db/                       # 数据库层
│   ├── cache/                    # 缓存驱动
│   ├── queue/                    # 队列驱动
│   ├── rate/                     # 限流算法
│   ├── circuit/                  # 熔断器
│   ├── oauth/                    # OAuth 登录
│   ├── payment/                  # 支付集成
│   ├── mail/                     # 邮件驱动
│   ├── sms/                      # 短信驱动
│   ├── auth/                     # 实名认证
│   ├── filesystem/               # 文件存储
│   ├── template/                 # 模板引擎
│   ├── captcha/                  # 验证码
│   ├── crypt/                    # 加密组件
│   ├── cookie/                   # Cookie 管理
│   ├── session/                  # 会话管理
│   ├── pagination/               # 分页组件
│   ├── upload/                   # 文件上传
│   ├── notify/                   # 通知组件
│   ├── websocket/                # WebSocket
│   ├── pdf/                      # PDF 生成
│   ├── excel/                    # Excel 处理
│   ├── trace/                    # 链路追踪
│   ├── health/                   # 健康检查
│   ├── monitor/                  # 性能监控
│   ├── apidoc/                   # API 文档生成
│   ├── api/                      # API 资源
│   ├── console/                  # 命令行工具
│   ├── plugin/                   # 插件管理
│   ├── module/                   # 模块管理
│   ├── schedule/                 # 任务调度
│   ├── testing/                  # 测试组件
│   ├── exception/                # 异常类
│   └── helpers.php               # 全局辅助函数
├── lang/                         # 语言包
│   ├── zh-cn/
│   └── en/
├── public/                       # Web 根目录
│   ├── assets/                   # 静态资源
│   ├── admin.php                 # 后台入口
│   ├── api.php                   # API 入口
│   └── bootstrap.php             # 引导文件
├── lingdu.php                    # 命令行入口
└── .env.example                  # 环境变量示例
```

---

## 四、核心组件

### 4.1 MVC 架构

| 组件 | 类 | 说明 |
|------|-----|------|
| 控制器 | `framework\core\Controller` | 基础控制器，提供请求分发、视图渲染、CSRF 验证 |
| 模型 | `framework\core\Model` | ORM 模型，支持时间戳、软删除、类型转换、关联关系 |
| 视图 | `framework\core\View` | 模板渲染引擎 |
| 请求 | `framework\core\Request` | HTTP 请求封装，支持参数获取、文件上传、IP 解析 |
| 响应 | `framework\core\Response` | HTTP 响应封装，支持 JSON/重定向/流式输出 |

### 4.2 依赖注入容器

`framework\core\Container` — 支持：

- 自动依赖注入（构造函数 + 方法注入）
- 接口绑定实现
- 单例绑定
- **ReflectionUnionType** 处理（PHP 8 联合类型）
- **循环依赖检测**（在 `resolve()` 入口检测，避免无限递归）

```php
$container = new Container();
$container->bind(RepositoryInterface::class, RedisRepository::class);
$instance = $container->make(RepositoryInterface::class);
```

### 4.3 路由系统

`framework\core\Route` — 支持：

- GET / POST / PUT / DELETE / PATCH / ANY 注册
- 路由分组与中间件分配
- RESTful 资源路由
- 路径参数提取（`{id}` 语法）
- **路由缓存**（`RouteCache` 编译缓存，避免每次请求重新解析）
- 正则路由编译（`preg_quote` 安全转义）

```php
Route::get('/user/{id}', 'user.User/info');
Route::post('/user/create', 'user.User/create');
Route::group(['middleware' => 'auth'], function() {
    Route::get('/dashboard', 'admin.Index/index');
});
```

### 4.4 数据库与 ORM

**连接管理** `framework\db\ConnectionManager`

- 多数据库支持：MySQL / PostgreSQL / SQLite / SQL Server
- 读写分离：配置 `read` / `write` 主机
- 集群模式：多读主机负载均衡
- 连接池管理，最大连接数限制
- **SQLite 路径遍历防护**

**查询构建器** `framework\db\Builder`

- 链式调用：`where` / `orWhere` / `whereIn` / `join` / `order` / `limit`
- 聚合查询：`count` / `sum` / `avg` / `max` / `min`
- 事务支持：`startTrans` / `commit` / `rollback`
- 参数化查询，防 SQL 注入
- **表名/字段名反引号转义**（`str_replace('`', '``')`）

**ORM 模型** `framework\core\Model`

- 自动时间戳（`createtime` / `updatetime`）
- 软删除（`deletetime`）
- 类型转换（`$casts`）
- 批量赋值保护（`$fillable` / `$guarded`）
- 字段隐藏（`$hidden`，如 `password`）
- 数据获取器/修改器
- 关联关系：`hasOne` / `hasMany` / `belongsTo` / `belongsToMany`
- `inc()` / `dec()` 原子操作（检查主键存在性）
- `toArray()` 递归处理关联模型

**数据库迁移** `framework\db\Migration`

- Schema Builder：`createTable` / `addColumn` / `addIndex`
- 字段类型：`string` / `integer` / `bigInteger` / `decimal` / `text` / `datetime` / `enum` 等
- 迁移回滚与重置
- **列名/索引名反引号安全转义**

### 4.5 缓存系统

`framework\core\Cache` — 门面类，通过 `Cache::store()` 获取驱动实例。

**支持驱动：**

| 驱动 | 类 | 特性 |
|------|-----|------|
| File | `framework\cache\File` | 文件缓存，支持 TTL、文件锁、目录自动创建 |
| Redis | `framework\cache\Redis` | 类型前缀序列化（`i:`/`f:`/`b:`），保持浮点/布尔精度 |
| Memcache | `framework\cache\Memcache` | inc/dec 安全处理序列化值 |
| Memcached | `framework\cache\Memcached` | inc/dec 安全处理序列化值，`array_key_exists` 支持 null |
| APCu | `framework\cache\Apcu` | 本地内存缓存，`apcu_store` 返回值校验 |

**统一接口** `CacheInterface`：`get` / `set` / `delete` / `has` / `inc` / `dec` / `getMultiple` / `setMultiple`

### 4.6 验证器

`framework\core\Validator` — 支持：

- 内置规则：`required` / `email` / `mobile` / `url` / `ip` / `integer` / `numeric` / `min` / `max` / `between` / `date` / `dateFormat` / `in` / `notIn` / `regex` / `confirmed` / `same` / `different` / `unique`
- 自定义规则与消息
- 场景验证
- **`validated()` 支持点号规则**（如 `user.email`），构建嵌套数据结构
- 验证异常 `ValidationException`

```php
$validator = new Validator($data, [
    'username' => 'required|alpha_num|min:4|max:20',
    'email'    => 'required|email|unique:user',
    'password' => 'required|min:6|confirmed',
]);

if ($validator->fails()) {
    $errors = $validator->errors();
}
$validData = $validator->validated();
```

---

## 五、安全体系

### 5.1 安全组件

`framework\core\Security` — 全局安全工具类：

| 方法 | 功能 |
|------|------|
| `hashPassword()` | 密码哈希（bcrypt，自动加盐） |
| `verifyPassword()` | 密码验证（`hash_equals` 防时序攻击） |
| `generateToken()` | CSRF Token 生成（`random_bytes`） |
| `verifyCsrfToken()` | CSRF Token 验证（`hash_equals`） |
| `xssClean()` | XSS 过滤（`htmlspecialchars` + 实体编码） |
| `encrypt()` / `decrypt()` | AES-256-GCM 对称加密 |

### 5.2 CSRF 防护

- 表单自动注入 `_token` 隐藏域
- AJAX 请求通过 `X-CSRF-TOKEN` Header 传递
- 支持豁免路由配置
- Token 一次性使用，验证后即销毁

### 5.3 会话安全

- **Session ID 48位**，每字符6位熵值
- `use_strict_mode` 防止会话固定攻击
- `use_only_cookies` 禁止 URL 传递 Session ID
- `cookie_httponly` 禁止 JavaScript 访问
- `cookie_samesite=Lax` 防 CSRF
- 登录后 `session_regenerate_id(true)` 重新生成 ID
- 空闲超时 + 绝对超时双重过期机制

### 5.4 Cookie 安全

`framework\cookie\Cookie` — 支持：

- **Encrypt-then-MAC** 模式（先加密后签名，防篡改）
- 解密失败返回默认值，不抛异常
- `httponly` / `secure` / `samesite` 属性

### 5.5 加密组件

`framework\crypt\Crypt` — 支持：

- AES-256-GCM 认证加密
- PBKDF2 密钥派生
- 数组加密/解密（`encryptArray` / `decryptArray`）
- 密钥与 MAC 密钥分离

### 5.6 文件上传安全

`framework\upload\Upload` — 多层防护：

- 文件扩展名白名单
- 危险扩展名黑名单（php/phar/exe/asp/jsp/svg 等 30+ 种）
- MIME 类型校验
- 文件内容检测
- **路径遍历防护**（`/\.{2,}/` 正则 + `realpath` 校验）
- 文件名随机化 + SHA1 哈希校验
- 自动子目录（按日期 `Y/m/d`）

### 5.7 重定向安全

- 相对路径验证（`/` 开头且非 `//`）
- 绝对路径主机白名单（`app.allowed_hosts` 或 `app.url` 配置）
- **禁止 `$_SERVER['HTTP_HOST']` 直接使用**，防主机头注入

---

## 六、队列系统

`framework\core\Queue` — 统一队列管理，支持多驱动：

| 驱动 | 类 | 特性 |
|------|-----|------|
| Database | `framework\queue\DatabaseQueue` | 数据库表存储，零依赖 |
| Redis | `framework\queue\RedisQueue` | Redis List + Sorted Set，支持延迟队列 |
| RabbitMQ | `framework\queue\RabbitMQQueue` | AMQP 协议，DLX 死信队列，消息确认 |
| Kafka | `framework\queue\KafkaQueue` | Kafka 消费者组，rebalance 回调，nack 重试 |

**通用特性：**

- `work()` 守护进程模式，支持 `pcntl` 信号处理
- 内存使用监控，超限自动重启
- 任务失败重试与错误日志
- 延迟队列支持

```php
Queue::push('SendEmailJob', ['email' => 'user@example.com']);
Queue::later(60, 'ProcessDataJob', ['id' => 123]); // 延迟60秒
```

---

## 七、限流与熔断

### 7.1 限流算法

`framework\rate\RateLimiter` — 四种算法可选：

| 算法 | 类 | 适用场景 |
|------|-----|---------|
| 固定窗口 | `framework\rate\FixedWindow` | 简单限流，精度要求低 |
| 滑动窗口 | `framework\rate\SlidingWindow` | 精确限流，无边界突发 |
| 令牌桶 | `framework\rate\TokenBucket` | 允许突发流量，平均速率控制 |
| 漏桶 | `framework\rate\LeakyBucket` | 严格恒定速率输出 |

统一接口 `RateLimiterInterface`：`attempt()` / `hits()` / `available()` / `remaining()` / `clear()` / `availableIn()`

### 7.2 熔断器

`framework\circuit\CircuitBreaker` — 三态模型：

- **Closed（关闭）** — 正常请求，统计失败率
- **Open（打开）** — 快速失败，不执行请求
- **Half-Open（半开）** — 探测恢复，允许少量请求

配置项：失败阈值、恢复时间、探测请求数。`CircuitBreakerManager` 管理多个熔断器实例。

---

## 八、OAuth 第三方登录

`framework\oauth` — 支持：

| 平台 | 类 | 特性 |
|------|-----|------|
| 微信 | `WechatOAuth` | 网页授权，获取 openid/用户信息 |
| QQ | `QQOAuth` | OAuth 2.0，回调参数安全校验 |
| GitHub | `GitHubOAuth` | OAuth 2.0 标准流程 |
| 微博 | `WeiboOAuth` | OAuth 2.0 标准流程 |

**安全特性：**

- **强制 state 参数**，防 CSRF 攻击
- 回调校验 `strpos` 返回值，防逻辑绕过
- Access Token 安全存储

---

## 九、支付集成

`framework\payment` — 支持：

| 平台 | 类 | 特性 |
|------|-----|------|
| 支付宝 | `Alipay` | RSA2 签名/验签，异步通知，沙箱模式 |
| 微信支付 | `WechatPay` | HMAC-SHA256 签名，XML/JSON 双格式，企业付款 |

**安全特性：**

- **防重放攻击**（缓存幂等性校验）
- 金额验证（`bccomp` 精确比较）
- 异步通知签名验证
- XML 解析禁用外部实体（`LIBXML_NOENT` 已移除，`LIBXML_NONET` 启用）
- 请求体大小限制

---

## 十、邮件与短信

### 10.1 邮件

`framework\mail` — 支持：

| 组件 | 说明 |
|------|------|
| `Mailer` | 链式调用：`to()` / `subject()` / `body()` / `send()` |
| `Smtp` | SMTP 协议驱动，支持 SSL/TLS 加密 |
| `MailDriver` | 基础驱动，地址格式校验，`<>` 字符转义 |

**安全特性：**

- TLS 握手验证
- SMTP 状态重置（`finally` 块中 `reset()`）
- CRLF 注入防护

### 10.2 短信

`framework\sms` — 支持：

| 驱动 | 类 | 说明 |
|------|-----|------|
| 阿里云 | `Aliyun` | 阿里云短信服务 |
| 腾讯云 | `Tencent` | 腾讯云短信服务 |
| 短信宝 | `Smsbao` | 短信宝服务 |

统一接口 `SmsInterface`，通过 `Sms` 门面类调用。

---

## 十一、文件存储

`framework\filesystem` — 支持：

| 驱动 | 类 | 说明 |
|------|-----|------|
| 本地 | `LocalFilesystem` | 本地文件系统 |
| 阿里云 OSS | `AliyunOss` | 阿里云对象存储 |
| 腾讯云 COS | `TencentCos` | 腾讯云对象存储，HEAD 请求获取元数据 |
| 七牛云 | `QiniuStorage` | 七牛云对象存储，全 HTTPS |

统一接口 `FilesystemInterface`：`put` / `get` / `delete` / `exists` / `size` / `lastModified` / `mimeType` / `url`

---

## 十二、模板引擎

`framework\template\Engine` — 自研轻量模板引擎：

| 标签 | 语法 | 说明 |
|------|------|------|
| 变量输出 | `{$var}` | 自动 HTML 转义 |
| 条件判断 | `{if}...{elseif}...{else}...{/if}` | 条件分支 |
| 循环遍历 | `{foreach $list as $item}...{/foreach}` | 数组遍历 |
| 模板继承 | `{extend name='layout' /}` | 布局继承 |
| 模板块 | `{block name='content'}...{/block}` | 内容区块 |
| 包含文件 | `{include file='header' /}` | 子模板引入 |
| 原始输出 | `{$var|raw}` | 不转义输出 |
| 函数调用 | `{$var|date='Y-m-d'}` | 变量函数处理 |

**安全特性：**

- 默认 HTML 转义防 XSS
- `switch/case` 使用回调白名单防代码注入
- 变量名白名单校验
- `allow_php_tag` 默认关闭

---

## 十三、验证码

| 类型 | 类 | 说明 |
|------|-----|------|
| 图形验证码 | `framework\captcha\Captcha` | 随机字符 + 干扰线/噪点，`hash_equals` 验证 |
| 滑动验证码 | `framework\captcha\SliderCaptcha` | 滑块拼图验证，容差范围校验 |

**安全特性：**

- 验证码一次性使用，验证后立即销毁
- 验证码有效期限制
- `hash_equals` 防时序攻击

---

## 十四、实名认证

`framework\auth` — 支持：

| 驱动 | 类 | 说明 |
|------|-----|------|
| 阿里云 | `AliyunAuth` | 身份证二要素/三要素/人脸比对 |
| 腾讯云 | `TencentAuth` | 身份证核验 |

统一接口 `AuthInterface`：`verifyIdCard` / `verifyIdCardAndName` / `verifyIdCardNamePhoto`

**安全特性：**

- 所有验证请求使用 **POST 方法**（保护 PII 数据）
- 15位身份证号支持
- 身份证号脱敏显示

---

## 十五、WebSocket

`framework\websocket` — 支持：

| 组件 | 类 | 说明 |
|------|-----|------|
| 服务端 | `SocketServer` | TCP Socket 服务器，WebSocket 协议握手/帧编解码 |
| 驱动 | `WebSocketDriver` | 驱动抽象 |
| 接口 | `WebSocketInterface` | 统一接口 |

**功能：**

- WebSocket 协议握手（Sec-WebSocket-Key/Accept）
- 帧编码/解码（RFC 6455）
- 频道订阅/退订/广播
- 客户端管理

---

## 十六、链路追踪

`framework\trace` — 分布式链路追踪：

| 组件 | 类 | 说明 |
|------|-----|------|
| 追踪器 | `Tracer` | Span 栈管理，traceId/spanId 生成 |
| 跨度 | `Span` | 操作名、时间、状态、标签 |
| 中间件 | `TraceMiddleware` | 自动注入/提取 traceId |
| 存储 | `TraceStorage` | Redis 存储，SCAN 查询，`LOCK_EX` 写入 |

---

## 十七、健康检查

`framework\health\HealthCheck` — 支持检查项：

- 磁盘空间（`disk_total_space` / `disk_free_space`）
- 数据库连接（`Db::query('SELECT 1')`）
- 缓存读写（`Cache::store()` set/get/delete 循环）
- PHP 版本与扩展
- 内存使用

---

## 十八、任务调度

`framework\schedule\ScheduleManager` — 支持：

- Cron 表达式调度（5位标准格式）
- 频率快捷方法：`everyMinute()` / `hourly()` / `daily()` / `weekly()` / `monthly()`
- 定时执行：`dailyAt('08:30')` / `hourlyAt(15)`
- 命令调度 / 回调调度 / Shell 执行
- 守护进程模式（`startDaemon()` / `stopDaemon()`）
- 任务重叠保护（`withoutOverlapping()`）
- 超时控制（`timeout()`）

---

## 十九、命令行工具

`lingdu.php` — 内置 30+ 命令：

### 代码生成

| 命令 | 说明 |
|------|------|
| `make:controller` | 创建控制器 |
| `make:model` | 创建模型 |
| `make:middleware` | 创建中间件 |
| `make:validator` | 创建验证器 |
| `make:command` | 创建命令 |
| `make:migration` | 创建迁移文件 |
| `make:module` | 创建模块 |
| `make:plugin` | 创建插件 |
| `scaffold` | 根据数据库表生成 CRUD 代码 |

### 数据库

| 命令 | 说明 |
|------|------|
| `migrate` | 执行数据库迁移 |
| `migrate:rollback` | 回滚迁移 |
| `migrate:refresh` | 重置并重新迁移 |
| `migrate:status` | 查看迁移状态 |
| `db:seed` | 填充数据库 |

### 缓存

| 命令 | 说明 |
|------|------|
| `cache:clear` | 清除所有缓存 |
| `cache:config` / `config:cache` | 缓存配置文件 |
| `config:clear` | 清除配置缓存 |
| `cache:route` / `route:cache` | 缓存路由 |
| `route:clear` | 清除路由缓存 |
| `route:list` | 显示所有路由 |

### 插件与模块

| 命令 | 说明 |
|------|------|
| `plugin:install` | 安装插件 |
| `plugin:uninstall` | 卸载插件 |
| `plugin:list` | 显示所有插件 |
| `plugin:enable` / `plugin:disable` | 启用/禁用插件 |
| `module:list` | 显示所有模块 |
| `module:delete` | 删除模块 |

### 运行时

| 命令 | 说明 |
|------|------|
| `queue:work` | 启动队列工作进程 |
| `schedule:run` | 运行任务调度 |
| `test` | 运行测试 |
| `version` | 显示框架版本 |
| `help` | 显示帮助信息 |

---

## 二十、插件与模块体系

### 插件管理

`framework\plugin\PluginManager`

- 安装/卸载/启用/禁用插件
- 插件配置管理
- 插件路径获取
- **`validateName()` 防路径遍历**
- **`CURLOPT_FOLLOWLOCATION=false` 防 SSRF**

### 模块管理

`framework\module\ModuleManager`

- 创建/删除/启用/禁用模块
- 模块目录结构自动生成
- **`validateName()` 防路径遍历**

---

## 二十一、其他组件

### 21.1 分页

`framework\pagination\Paginator` — 支持：

- 页码参数安全校验（`perPage` 限制 1-100）
- 简洁分页 / 完整分页
- API 分页 JSON 响应

### 21.2 通知

`framework\notify`

| 组件 | 说明 |
|------|------|
| `Notify` | 通知发送，支持批量（每收件人独立主题） |
| `VerifyCode` | 验证码发送/验证，尝试次数限制，自动过期 |

### 21.3 API 资源

`framework\api\JsonResource` — RESTful API 响应格式化：

- 数据转换与字段筛选
- 分页元数据
- CRLF 过滤（`strtok`）

### 21.4 PDF 生成

`framework\pdf\Pdf` — 支持：

- HTML 转 PDF
- wkhtmltopdf 外部工具 / 内置 TcpdfGenerator 双引擎
- 页面尺寸/方向/边距配置
- **保存路径白名单**（仅允许 runtime / uploads 目录）

### 21.5 Excel 处理

`framework\excel\Excel` — Excel 文件读写

### 21.6 API 文档生成

`framework\apidoc\ApiDocGenerator` — 自动生成 API 文档：

- 扫描控制器注释（`@api` / `@apiParam` / `@apiSuccess`）
- 生成单页 HTML 文档
- **XSS 防护**（`escapeHtml()` JavaScript 函数 + `JSON_HEX_TAG`）

### 21.7 性能监控

`framework\monitor\PerformanceMonitor` — 运行时性能数据采集

### 21.8 国际化

`framework\core\Lang` — 多语言支持：

- 语言包文件（`lang/zh-cn/common.php` / `lang/en/common.php`）
- 自动语言检测
- 回退语言

### 21.9 事件系统

`framework\core\Event` — 观察者模式：

- 事件监听注册
- 字符串类名 / 闭包 / `__invoke` 支持
- 事件优先级
- **无 `handle` 方法的类名监听器安全跳过**

### 21.10 服务提供者

`framework\core\ServiceProvider` — 服务注册与延迟加载

### 21.11 门面模式

`framework\core\Facade` — 静态代理，简化组件调用：

```php
Cache::store()->get('key');
Db::name('user')->where('id', 1)->find();
Log::info('message');
Config::get('app.name');
```

---

## 二十二、异常体系

`framework\exception` — 细粒度异常分类：

| 异常类 | 说明 |
|--------|------|
| `AuthException` | 认证异常（401） |
| `ForbiddenException` | 授权异常（403） |
| `ValidationException` | 验证异常（422） |
| `CsrfException` | CSRF 验证失败（419） |
| `ThrottleException` | 限流异常（429） |
| `DatabaseConnectionException` | 数据库连接异常 |
| `FileUploadException` | 文件上传异常 |
| `ModelNotFoundException` | 模型未找到 |
| `SecurityException` | 安全异常 |
| `BusinessException` | 业务逻辑异常 |

全局异常处理器 `framework\core\ExceptionHandler` 统一捕获与响应。

---

## 二十三、辅助函数

`framework\helpers.php` — 全局便捷函数：

| 函数 | 说明 |
|------|------|
| `env($key, $default)` | 获取环境变量 |
| `config($key, $default)` | 获取配置值 |
| `cache($key, $default)` | 缓存快捷操作 |
| `session($key, $value)` | Session 快捷操作 |
| `redirect($url)` | HTTP 重定向（防 `//` 协议相对 URL） |
| `json($data, $code)` | JSON 响应 |
| `root_path($path)` | 项目根目录 |
| `app_path($path)` | 应用目录 |
| `runtime_path($path)` | 运行时目录 |
| `public_path($path)` | 公共目录 |
| `database_path($path)` | 数据库目录 |
| `format_bytes($bytes)` | 字节格式化 |

---

## 二十四、安装向导

`app\install` — 可视化安装：

1. **环境检测** — PHP 版本、扩展、目录权限
2. **数据库配置** — 主机/端口/数据库名/用户名/密码（正则校验，反引号转义）
3. **执行安装** — SQL 文件导入（事务包裹）、管理员创建、配置文件写入
4. **安全加固** — 生成 `install.lock`、创建 `.htaccess` 禁止访问安装目录、生成 `.env.example`

---

## 二十五、环境变量

`.env` 文件支持，关键配置项：

```env
APP_ENV=production
APP_DEBUG=false
APP_KEY=your-32-char-secret-key

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=lingdu
DB_USERNAME=root
DB_PASSWORD=
DB_PREFIX=ld_

CACHE_DRIVER=redis
QUEUE_DRIVER=database

MAIL_DRIVER=smtp
MAIL_HOST=smtp.example.com
MAIL_PORT=465
MAIL_ENCRYPTION=ssl

SMS_DRIVER=aliyun
```

所有敏感配置均通过 `env()` 函数读取，支持默认值。

---

## 二十六、内置应用模块

| 模块 | 入口 | 说明 |
|------|------|------|
| 后台管理 | `admin.php` | 管理员登录、RBAC 权限、系统配置、附件管理 |
| 用户中心 | `user.php` | 用户注册/登录、个人资料、密码修改、邮箱/手机绑定 |
| API 接口 | `api.php` | RESTful API，Token 认证，限流，CORS |
| 前台首页 | `index.php` | 前台展示 |
| 安装向导 | `install.php` | 系统安装 |

### RBAC 权限管理

- 管理员分组（`auth_group`）
- 权限规则树（`auth_rule`）
- 超级管理员（`is_super`）跳过权限检查
- 规则支持 `*` 通配符（全部权限）

---

## 二十七、技术亮点总结

| 维度 | 亮点 |
|------|------|
| 安全 | CSRF / XSS / SQL注入 / 路径遍历 / 主机头注入 / 时序攻击 / 重放攻击 / SSRF 全链路防护 |
| 性能 | 路由缓存 / 配置缓存 / OPcache 友好 / 连接池 / 原子操作 |
| 可靠性 | 熔断器 / 限流 / 队列重试 / 事务保护 / 健康检查 |
| 可观测 | 链路追踪 / 性能监控 / 结构化日志（RFC 5424 全8级别） |
| 扩展性 | 插件体系 / 模块体系 / 多驱动架构 / 服务提供者 / 事件系统 |
| 开发体验 | Scaffold 脚手架 / API 文档自动生成 / 命令行工具 / 安装向导 |