# echo_framework

**Repository Path**: cywymch/echo_framework

## Basic Information

- **Project Name**: echo_framework
- **Description**: No description available
- **Primary Language**: PHP
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-10-08
- **Last Updated**: 2026-10-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🚀 Echo 框架：为 PHP 开发者打造的“Spring Boot 式”全栈利器

> 如果你受够了 PHP 传统框架的繁琐配置，又向往 Spring Boot 的注解驱动、约定优于设计，那么 **Echo** 或许正是你的下一站。  
> 它基于 Yaf 扩展，融合 PHP 8 原生注解，集组件扫描、DI、声明式路由、事务、权限、日志、MyBatis 风格数据层于一体，让业务代码干净得不像 PHP。

---

## 一、Echo 是什么？

Echo 是一个**注解驱动的 PHP 全栈框架**，内核基于 **Yaf 扩展**（高性能路由分发），上层自研了一套完整的注解与容器体系。设计上大量借鉴 **Spring Boot** 的理念：

- ✅ PHP 8 Attribute 作为注解载体
- ✅ 组件扫描 + 依赖注入（按类型/按名称）
- ✅ 声明式路由、参数装配、参数校验
- ✅ 声明式事务（`@Transactional`）
- ✅ 声明式权限（`@PreAuthorize`）
- ✅ 声明式日志与操作审计
- ✅ 数据层在 Eloquent 之上叠加 **MyBits**（类 MyBatis 的 XML/注解 Mapper）

一句话：**约定优于配置，业务代码只关心业务逻辑，横切关注点全交给注解。**

---

## 二、目录结构，一眼就懂

```
echo_pro/
├── app/              # 业务代码
│   ├── controllers/  # 控制器（默认模块）
│   ├── modules/      # 多模块（Admin/Api...）
│   ├── services/     # 服务接口 + Impl 实现
│   ├── repository/   # 仓储接口 + Impl 实现
│   ├── models/       # Eloquent 模型
│   ├── dto/          # Request/Query/Resource 三类 DTO
│   ├── middleware/   # 中间件
│   └── Bootstrap.php # Yaf 引导
├── framework/        # 框架核心（注解、容器、处理器...）
├── conf/             # 配置文件（app.ini, database.php, jwt.ini...）
├── routes/           # 文件路由（可选）
├── resources/        # 视图 + MyBits XML 映射
├── storage/          # 缓存/日志
├── make.php          # 脚手架生成器
└── public/           # 入口
```

模块化、分层清晰，新手上手无压力。

---

## 三、请求生命周期（极简版）

1. `index.php` → `Kernel::run()`
2. 启动阶段：Yaf 初始化 → DI 容器 → 扫描所有注解组件并实例化（结果缓存）
3. 路由匹配：注解路由 + 文件路由合并，支持动态参数
4. 插件钩子依次执行：路由解析、签名校验、中间件、事务开启、日志计时
5. 控制器 action 执行 → 提交事务 / 记录日志 → 返回 JSON 响应

整个过程高效、自动化，你只需写控制器方法。

---

## 四、控制器与路由：告别路由配置文件

```php
use Framework\Attribute\Controller;
use Framework\Attribute\GetMapping;
use Framework\Attribute\PostMapping;
use Framework\Attribute\Transactional;
use Framework\Attribute\PreAuthorize;

#[Controller(prefix: '/api/v1/admin/article', middleware: 'auth')]
class ArticleController extends ControllerAbstract
{
    #[GetMapping('/index')]
    public function indexAction(): Response {
        return response(['data' => ...]);
    }

    #[PostMapping('/add')]
    #[Transactional]
    #[PreAuthorize("article@add", false, "新增文章")]
    public function addAction(#[RequestBody] #[Valid] ArticleDTORequest $dto): Response {
        // 业务逻辑，事务自动开启/提交
    }

    #[GetMapping('/show/{id}')]
    public function showAction(#[PathVariable] int $id): Response {
        // 路径参数自动绑定
    }
}
```

**特点**：
- 类级 `@Controller` 定义统一前缀和中间件
- 方法级 `@GetMapping/PostMapping/DeleteMapping/PatchMapping` 定义具体路径
- 参数自动装配：`@RequestBody` 解析 JSON，`@PathVariable` 取路径变量，`@RequestParam` 取查询参数
- `@Valid` 开启 DTO 校验，失败自动返回 422

---

## 五、依赖注入：像 Spring 一样丝滑

```php
#[Service]
class ArticleServiceImpl implements ArticleServiceInterface
{
    #[Autowired]                     // 按类型注入
    private ArticleRepositoryInterface $articleRepository;

    #[Autowired(name: 'cache')]      // 按名称注入
    private $cache;

    #[Value('${jwt.ttl:3600}')]      // 配置注入 + 默认值
    private int $ttl;
}
```

**约定优于配置**：接口 `XxxServiceInterface` 自动匹配实现类 `XxxServiceImpl`（Impl 结尾），无需手动绑定。

---

## 六、数据层：Eloquent  +  MyBits 双剑合璧

### ⑥ Eloquent 模型（熟悉的味道）

```php
#[Table('articles')]
#[Fillable(['title', 'content'])]
class Article extends Framework\Database\Model
{
    use SoftDeletes;
}
```

### ⑦ MyBits 映射器（复杂 SQL 好帮手）

```php
#[Mapper]
interface UserMapper
{
    #[Select("SELECT * FROM users WHERE id = #{id}")]
    public function queryById(int $id);

    #[QueryMapper('findUsers')]   // 指向 XML 动态 SQL
    public function findUsers(?string $username = null);
}
```

XML 中支持 `<if>`, `<where>`, `<foreach>` 等动态标签，与 MyBatis 几乎一致，复杂查询不再拼字符串。

---

## 七、安全与认证：开箱即用

- **JWT 认证**：中间件 `auth` 自动校验 `Authorization: Bearer`，用户信息注入容器。
- **权限控制**：`@PreAuthorize("资源@操作", false, "描述")` 自动拦截，无权限返回 403。
- **请求签名**：JSON 接口强制签名防重放，时间戳 10 分钟有效。
- **敏感配置**：JWT 密钥必须放在 `.env`，框架启动时校验，缺失即抛异常（fail‑closed）。

---

## 八、事务与日志：声明式，零侵入

```php
#[Transactional(connection: 'mysql2')]   // 支持多连接
#[Log(message: '更新文章', recordParams: true)]
#[OperationLog(description: '编辑', type: 'update')]
public function updateAction(#[RequestBody] ArticleDTORequest $dto): Response
{
    // 异常时自动回滚，成功自动提交
}
```

- 事务在 `preDispatch` 开启，`postDispatch` 提交，异常自动回滚。
- 日志自动记录入参、返回值、执行耗时，敏感字段自动脱敏。

---

## 九、DTO 三层设计，参数校验更优雅

- **Requests**（写入参数）
- **Queries**（查询/筛选）
- **Resources**（输出塑形）

```php
#[Dto]
class ArticleDTORequest extends DTOAbstract
{
    public function __construct(
        public ?int $id,
        #[Required] public ?string $title,
        #[MapFrom("cate_id")] public ?int $categoryId,
        #[Type("int")] public ?int $status,
    ) {}
}
```

配合 `@Valid` 注解，支持 `@NotBlank`、`@Length`、`@Min`、`@Choice` 等丰富校验规则，校验失败自动返回 422。

---

## 十、代码生成器：一键 CRUD，告别重复劳动

```bash
php make.php crud Article --module Admin
```

- 自动生成：**Controller + Service + Repository + 三类 DTO**（含标准五方法：列表、详情、新增、更新、删除）
- 自动添加 `auth` 中间件和 RESTful 路由前缀
- 已有文件默认跳过，支持 `--force` 覆盖
- 批量生成：`php make.php crud --all`

从此，80% 的增删改查工作只需一条命令。

---

## 十一、更多内置能力，满足企业级需求

| 能力 | 说明 |
|------|------|
| **限流** | 令牌桶算法（Redis Lua 原子实现） |
| **加密** | AES-256-GCM，随机 nonce + HKDF 派生密钥 |
| **上传** | 支持 Local/Ftp/AliOss，自动净化文件名 |
| **验证码** | 图形验证码，可集成登录流程 |
| **视图** | 支持 Twig/Smarty/Blade 模板引擎 |
| **门面** | Cache、Config、Request、Response 等门面模式 |
| **RPC** | 基于 Yar 的微服务调用，支持 Token 鉴权 |
| **多级缓存** | Composite 驱动组合 APCu + Redis，性能与可靠性兼得 |

---

## 十二、快速上手一个模块

1. **建表**：`ws_projects`（含 `created_at`/`updated_at`）
2. **建模型**：`app/models/Project.php`，标注 `#[Table]` 和 `#[Fillable]`
3. **生成脚手架**：`php make.php crud Project --module Admin`
4. **调整 DTO 字段和校验规则**
5. **控制器加 `@PreAuthorize`** 控制权限
6. 启动服务，访问 `GET /api/v1/admin/project/index`（带 Token）

所有文件已按分层约定生成，你只需填充业务逻辑。

---

## 十三、配置极简，环境分离

- `conf/` 下集中管理：数据库、缓存、JWT、中间件、日志等
- `.env` 存放敏感信息（`APP_DEBUG`、`JWT_SECRET_KEY`）
- 生产环境务必 `APP_DEBUG=false`

---

## 十四、适合谁？

- 从 Laravel/Yii 迁移，渴望更轻量、更高性能的开发者
- 喜欢 Spring Boot 注解风格，但不想换语言
- 需要构建中大型企业级 API，要求规范、可维护、高效率
- 团队希望统一开发范式，降低新成员上手成本

---

# Actuator 健康检查与监控

应用内置的健康检查与监控子系统（借鉴 Spring Boot Actuator），提供组件健康探测、请求指标采集、时序统计与图形化面板。

## 端点一览

| 端点 | 鉴权 | 说明 |
|---|---|---|
| `GET /actuator/health` | 摘要匿名 / 明细需令牌 | 健康检查。匿名仅返回整体状态（供负载均衡探针）；携带令牌返回各组件明细。HTTP 语义：UP→200，否则 503 |
| `GET /actuator/info` | 需令牌 | 应用元信息（名称/框架/PHP 版本/时区） |
| `GET /actuator/metrics` | 需令牌 | 指标快照：总量、错误率、平均耗时、状态码分布、延迟直方图、运行时长 |
| `GET /actuator/metrics/timeseries?minutes=60` | 需令牌 | 分钟级时序（近 2 小时上限），供图表演示 |
| `GET /actuator/metrics/routes?limit=20` | 需令牌 | Top 路由（按请求量排序） |
| `GET /actuator/metrics/slow` | 需令牌 | 慢请求清单（>1000ms，保留最近 50 条） |
| `GET /actuator/dashboard?token=xxx` | 需令牌 | 图形化监控面板（Chart.js 可视化，自动刷新） |

## 鉴权

令牌取自环境变量 `ACTUATOR_TOKEN`（写在 `.env`，勿入库）。两种传入方式：

```
# 请求头（推荐，供探针/脚本）
curl -H "X-Actuator-Token: <token>" http://host/actuator/metrics

# 查询参数（供浏览器打开面板）
http://host/actuator/dashboard?token=<token>
```

未配置令牌时，所有详情端点一律返回 403（fail-closed）。`/actuator/health` 的整体状态摘要保持匿名开放，便于负载均衡探针使用。

## 健康指示器

| 指示器 | 判定 | 故障级别 |
|---|---|---|
| database | `SELECT VERSION()` | DOWN（关键依赖） |
| redis | ping + version | DEGRADED（缓存层） |
| memcached | isAvailable + stats | DEGRADED |
| disk | 存储目录可写 + 剩余空间阈值 | 不可写→DOWN；空间不足→DEGRADED |
| runtime | PHP/Yaf 版本 + 内存水位 | 内存>90%→DEGRADED |
| server | 内存/CPU 实时采样 | 默认关闭；内存可用<1GB 或 CPU>80%→DEGRADED |

聚合规则：任一 DOWN→整体 DOWN；任一 DEGRADED→DEGRADED；否则 UP（UNKNOWN 不影响整体）。
在 `conf/actuator.php` 的 `indicators` 中可按组件开关。

`server` 指示器默认关闭：开启后 `/actuator/health` 会实时采集 CPU/内存数据，并经 `ServerStats::record` 写入 Redis，供面板 CPU/内存图展示；代价是 Linux/macOS 下 CPU 采样会额外阻塞约 200ms。

## 指标采集

- 采集点在 `Kernel::run()` 的 finally 钩子，请求结束时写入 Redis 计数器；
- 分钟级时序桶保留 2 小时（`actuator:m:{分钟时间戳}`），延迟分布六档桶；
- Top 路由按「方法 + 路径」聚合（忽略 query 参数），避免不同参数产生海量独立条目；
- 数据库查询指标由 Bootstrap 的 Eloquent 监听器累加（`QueryStats`），随请求落账；
- **静默保护**：监控写入全部包裹在异常捕获中，Redis 故障或指标异常绝不影响业务请求。

## 配置（conf/actuator.php）

```php
return [
    'enabled' => true,            // 总开关，false 时端点全部 404
    'indicators' => [...],        // 各指示器开关
    'disk' => ['path' => '', 'min_free_mb' => 100],
    'metrics' => ['enabled' => true, 'prefix' => 'actuator:'],
];
```

## 快速验证

```bash
# 健康探针
curl http://host/actuator/health

# 指标快照
curl -H "X-Actuator-Token: $TOKEN" http://host/actuator/metrics

# 打开监控面板
浏览器访问  http://host/actuator/dashboard?token=$TOKEN
```

## 相关文件

```
framework/Monitoring/
├── Health/
│   ├── HealthStatus.php          状态枚举（UP/DEGRADED/DOWN/UNKNOWN）
│   ├── HealthResult.php          单组件检查结果
│   ├── HealthIndicator.php       指示器契约
│   ├── HealthAggregator.php      聚合器
│   └── Indicator/                database/redis/memcached/disk/runtime
├── Info/InfoProvider.php         应用信息
└── Metrics/
    ├── MetricsCollector.php      指标采集器（计数器+时序+直方图+慢请求+Top路由）
    ├── SqlProfiler.php           SQL 语句分析器
    └── QueryStats.php            请求内查询统计
app/controllers/Actuator.php      端点控制器
resources/views/actuator/dashboard.tpl  监控面板模板
```
## 🎯 写在最后

Echo 不是一个玩具框架，它已经在多个生产项目中稳定运行。它把 PHP 的灵活性与 Java 生态的严谨设计融为一体，让 PHP 开发也能享受到“声明式编程”的优雅。

如果你正在寻找下一个 PHP 框架，不妨给 Echo 一个机会。  
**项目地址**：https://gitee.com/cywymch/echo_framework

欢迎 Star、Fork、提 Issue，一起让 PHP 更强大！

---

> 📌 本文仅介绍框架核心特性，详细文档请参阅项目 README。  
> 如有疑问，可加入社区讨论群（请查阅项目主页）。

**Echo —— 让 PHP 开发，如诗如歌。** 🎵