FendxPHP/FendxPHP_项目架构.md

**FendxPHP 项目架构（V1.0，2026-04-01）**

下面给你一份**真正可交付、超详细、结构标准、可直接放立项/评审材料**的

**FendxPHP 项目架构文档（完整版·正式可交付）**

我用最规范、最干净、可直接复制进 Word 的格式给你，不带多余废话。

**FendxPHP 企业级框架 项目架构文档**

文档版本：V1.0
编写日期：2026-04-01
适用版本：FendxPHP 正式版
运行环境：PHP 8.1 / 8.2 / 8.3
文档状态：正式定稿

**目 录**

1 文档概述
2 项目概述与定位
3 总体架构设计
4 分层架构详细说明
5 核心模块详细设计（超详细）
6 项目目录结构与工程组织
7 模块依赖关系
8 技术选型清单
9 非功能架构设计（性能/安全/可用/扩展/可维护）
10 部署架构方案
11 架构亮点与优势
12 术语说明
13 版本变更记录

**1 文档概述**

**1.1 编写目的**

本文档用于完整、正式、详细地描述 FendxPHP 企业级开发框架的**整体架构、分层结构、模块职责、模块交互、工程结构、技术栈、部署方案、非功能设计**。
用于架构评审、开发指导、测试依据、运维部署、项目交付与验收，统一团队技术规范。

**1.2 文档范围**

覆盖 FendxPHP 全部内容：

• 整体架构与分层

• 内核与所有业务组件

• 目录结构、模块划分、依赖关系

• 技术选型与第三方依赖

• 请求全生命周期流程

• 性能、安全、可用性、扩展性、可维护性设计

• 开发/测试/生产部署架构

**1.3 读者对象**

• 架构师

• PHP 后端开发工程师

• 测试工程师

• 运维工程师

• 项目管理人员

**2 项目概述与定位**

**2.1 项目名称**

FendxPHP 轻量化企业级 PHP 开发框架

**2.2 项目背景**

现有 PHP 框架普遍存在以下问题：

• 重型框架：启动慢、占用高、配置复杂、学习成本高

• 轻型框架：功能残缺，无企业级能力（事务、权限、缓存、安全、微服务）

• 无统一规范：请求、响应、异常、日志、数据库操作不统一

• 高并发、安全、可维护性不足

FendxPHP 旨在解决以上问题，提供一套**轻量、全功能、标准化、安全、高性能、易扩展**的企业级 PHP 开发框架。

**2.3 项目定位**

• 定位：企业级 API / 管理后台 / SaaS / 高并发接口 / 微服务架构

• 风格：全注解、少配置、约定大于配置

• 特性：标准化、插件化、全链路可追踪、高安全、高可用

• 目标：让 PHP 项目开发更快、更规范、更稳定、更好维护

**3 总体架构设计**

FendxPHP 采用 **五层纵向分层 + 横向插件化组件** 架构。
分层从上到下依次为：

\1. 业务应用层

\2. 组件服务层

\3. 内核引擎层

\4. 基础支撑层

\5. 启动与容器层

所有依赖**只能自上而下，禁止反向依赖、禁止循环依赖**，保证架构清晰、稳定、易维护。

**3.1 整体架构图（文字可直接写进文档）**

Plaintext 业务应用层   ↑ 组件服务层（Web、DB、缓存、权限、日志、任务、文件、微服务、监控）   ↑ 内核引擎层（IOC、AOP、上下文、配置、事件）   ↑ 基础支撑层（工具、加密、异常、数据转换）   ↑ 启动与容器层（入口、环境检查、配置加载、容器初始化）

**3.2 请求全生命周期标准流程**

\1. 请求进入入口文件

\2. 框架启动、环境检查、加载配置

\3. 容器初始化、扫描注解、完成Bean注册

\4. 路由匹配、定位目标Controller

\5. 请求参数解析、自动校验、XSS/SQL 危险字符过滤

\6. 执行拦截器责任链

\7. 进入Controller方法

\8. 调用Service业务逻辑

\9. 调用Dao/缓存/微服务组件

\10. 事务管理、异常捕获、日志记录

\11. 统一格式封装响应结果

\12. 日志输出、监控埋点、结束请求

**4 分层架构详细说明**

**4.1 启动与容器层**

职责：

• 框架唯一入口管理

• PHP版本/扩展检查

• 多环境识别（dev/test/pre/prod）

• 配置文件加载、敏感配置解密

• 类自动加载、注解扫描

• IOC容器初始化、Bean创建与依赖注入

• 优雅关闭、资源释放

**4.2 内核引擎层**

职责：

• IOC容器：Bean管理、依赖注入、生命周期管理

• AOP引擎：切面、通知、切点、代理、排序

• 全局上下文：请求隔离、TraceId、用户信息透传

• 配置中心：多环境、热加载、加解密、扩展接入配置中心

• 事件调度：同步/异步事件、监听、触发

**4.3 基础支撑层**

职责：
提供**无业务侵入、全项目通用**的基础能力：

• 字符串、数组、集合、分页工具

• 日期时间、格式化工具

• 加密工具：MD5、SHA256、AES、RSA、JWT

• 文件、上传、下载、IO工具

• HTTP客户端统一封装

• 全局异常基类、错误码、断言

• 数据拷贝、驼峰/下划线互转、类型转换

**4.4 组件服务层**

框架最核心、最完整的一层，包含所有企业级能力：

• Web 组件：路由、请求、响应、拦截器

• DB 组件：ORM、多数据源、事务

• 缓存组件：Redis、本地缓存、缓存注解、防穿透/击穿/雪崩

• 权限安全组件：认证、RBAC、接口权限、数据权限、安全防护

• 日志组件：分级、TraceId、异步、切割、清理

• 定时任务组件：Cron、分布式锁、任务管理

• 文件组件：本地/OSS/MinIO 统一存储、上传/下载/分片

• 微服务组件：注册、发现、配置、负载均衡、熔断、远程调用

• 监控组件：健康检查、QPS、RT、错误率、系统指标、告警

**4.5 业务应用层**

业务项目基于框架编写的内容：

• Controller：请求入口、参数接收、响应返回

• Service：业务逻辑、事务控制、服务编排

• Dao：数据访问、数据库操作

• Entity：数据库实体映射

• Validate：参数校验规则

• VO/DTO：展示对象、传输对象

• Job：定时任务实现

• Interceptor：自定义拦截器

**5 核心模块详细设计（超详细）**

下面是**可直接用于评审、最完整**的模块描述。

**5.1 启动管理模块**

• 检查PHP版本是否≥8.1

• 检查必需扩展是否安装（pdo、redis、json、mbstring等）

• 自动识别运行环境：dev/test/pre/prod

• 加载对应环境配置

• 注册类自动加载器

• 扫描注解、构建Bean定义

• 初始化IOC容器

• 注册异常捕获处理器

**5.2 IOC 容器模块**

• 支持注解：#[Controller]、#[Service]、#[Dao]、#[Inject]

• 自动构造函数注入

• 单例模式为默认，支持多例配置

• 循环依赖检测与提示

• Bean初始化、前置处理、后置处理、销毁

• 支持手动获取Bean

**5.3 AOP 切面模块**

支持五种通知：

• Before：方法执行前

• After：方法执行后（无论是否异常）

• Around：方法执行前后包裹

• AfterReturning：正常返回后

• AfterThrowing：异常抛出后

支持三类切点：

• 注解切点

• 方法名匹配切点

• 路由匹配切点

典型用途：
事务、日志、权限、缓存、限流、性能统计、接口签名校验。

**5.4 全局上下文模块**

• 每请求独立上下文，互不污染

• 全局唯一TraceId贯穿整个请求

• 存储：用户信息、请求Id、租户Id、请求耗时

• 协程/异步安全，可透传

• 支持日志自动输出TraceId

**5.5 配置管理模块**

• 支持 .php .env .yaml .yml

• 多环境自动切换

• 敏感配置加密存储，读取自动解密

• 支持配置热重载

• 可扩展接入 Nacos / Apollo

**5.6 Web 路由模块**

• 支持 GET/POST/PUT/PATCH/DELETE

• 注解式路由：#[GetRoute] #[PostRoute]

• 支持路径参数 /user/{id}

• 支持通配符 /file/**

• 支持路由分组、统一前缀

• 启动时检查重复路由

• 前缀树+哈希表实现O(1)匹配

**5.7 请求解析与校验模块**

• 自动获取：GET/POST/JSON/HEADER/COOKIE

• 自动封装到 DTO 对象

• 内置校验规则：
required、email、mobile、idCard、length、max、min、in、regex

• 支持自定义校验器

• 自动XSS过滤、SQL危险字符过滤

**5.8 统一响应模块**

固定结构：
code、msg、data
所有接口**完全统一**，前端无需适配多种格式。
支持：正常返回、错误返回、分页返回、列表返回。

**5.9 拦截器模块**

• 支持全局拦截、分组拦截、单接口拦截

• 三个生命周期：before、after、afterCompletion

• 支持排序、开关控制

• 典型用途：登录校验、权限判断、IP黑白名单、接口限流、请求日志

**5.10 ORM 模块**

• 注解：#[Table] #[Id] #[Column]

• 自动生成CRUD

• Lambda式条件构造，无硬编码SQL

• 支持分页、排序、in、not in、between、like

• 一对一、一对多、多对多关联查询

• 全部使用PDO预编译，彻底防SQL注入

**5.11 多数据源模块**

• 支持多库独立配置

• 使用注解 #[DataSource("db2")] 动态切换

• 支持读写分离、读库负载均衡

• 事务内保持同一个连接，保证事务安全

**5.12 事务管理模块**

• 注解 #[Transactional]

• 支持事务传播机制

• 支持事务隔离级别配置

• 异常自动回滚，正常自动提交

• 支持多数据源单库安全事务

**5.13 缓存组件**

两级架构：

• 一级缓存：Redis

• 二级缓存：本地内存（可选）

三大注解：

• #[Cacheable] 查询缓存

• #[CacheUpdate] 更新缓存

• #[CacheEvict] 删除缓存

防三大问题：

• 缓存穿透：空值缓存

• 缓存击穿：互斥锁

• 缓存雪崩：随机过期时间

**5.14 权限认证模块**

• 支持 Session / Token / JWT

• 登录自动续期

• 登录失败次数锁定，防暴力破解

• 支持Token黑名单强制踢人

**5.15 RBAC 权限模块**

标准权限体系：
用户 → 角色 → 权限

支持四级权限：

• 菜单权限

• 按钮权限

• 接口权限

• 数据行级权限

使用注解：
\#[RequiresPermission("user:list")]

**5.16 安全防护模块**

• XSS全局过滤

• SQL注入全面拦截

• CSRF令牌校验

• 接口限流（IP限流、接口限流）

• 敏感字段脱敏（手机号、身份证、银行卡）

**5.17 日志链路模块**

• 级别：DEBUG/INFO/WARN/ERROR

• 每条日志自动携带TraceId

• 异步写入，不阻塞业务

• 按天/按大小自动切割

• 自动清理过期日志

• 可对接ELK、Loki、Graylog

**5.18 定时任务模块**

• 注解 #[Scheduled(cron="* * * * *")]

• 支持固定频率、固定延迟

• 分布式锁保证多实例不重复执行

• 支持任务启停、手动触发、执行日志、失败重试

**5.19 文件服务模块**

统一接口，适配多种存储：

• 本地存储

• MinIO

• 阿里云OSS

• 腾讯云COS

支持：
单文件、多文件、分片上传、断点续传、文件大小校验、格式校验、签名下载、访问日志。

**5.20 微服务组件**

• 服务注册、服务发现

• 健康检查

• 配置中心、动态刷新

• 负载均衡：轮询、随机、权重

• 熔断、降级、限流、防雪崩

• 统一HTTP远程调用封装

**5.21 监控组件**

• 服务健康检查接口

• 接口指标：QPS、响应时间、错误率

• 系统指标：CPU、内存、磁盘、网络

• 支持自定义业务指标

• 多渠道告警：邮件、钉钉、企业微信

**6 项目目录结构（可直接照着建）**

**6.1 框架整体多模块结构**

Plaintext fendx-php-framework/ ├── fendx-dependencies/    # 统一Composer版本管理 ├── fendx-common/       # 公共工具、常量、枚举、异常 ├── fendx-core/        # 内核：IOC、AOP、上下文、配置 ├── fendx-web/        # Web：路由、请求、响应、拦截器 ├── fendx-db/         # 数据库：ORM、多数据源、事务 ├── fendx-cache/       # 缓存：Redis、注解、安全防护 ├── fendx-security/      # 权限、认证、安全、防护 ├── fendx-log/        # 日志、TraceId、异步日志 ├── fendx-job/        # 定时任务、分布式调度 ├── fendx-file/        # 文件服务、多存储适配 ├── fendx-cloud/       # 微服务：注册、配置、调用、熔断 ├── fendx-monitor/      # 监控、指标、健康检查、告警 ├── fendx-starter/      # 启动器、自动装配、入口 └── fendx-example/      # 示例项目（单体+微服务）

**6.2 业务项目标准目录（用户直接用）**

Plaintext app/ ├── Controller/    # 控制器 ├── Service/     # 业务逻辑 ├── Dao/       # 数据访问 ├── Entity/      # 数据库实体 ├── Validate/     # 参数校验 ├── Vo/        # 前端展示对象 ├── Dto/       # 内部传输对象 ├── Job/       # 定时任务 └── Interceptor/   # 拦截器 config/        # 配置文件 public/        # 入口目录 runtime/       # 日志、缓存、临时文件

**7 模块依赖关系**

• 所有模块 → 依赖 fendx-common

• web、db、cache、security、log、job、file、cloud、monitor → 依赖 fendx-core

• fendx-starter → 依赖所有组件模块

• fendx-example → 依赖 fendx-starter

依赖单向、无环、稳定、易维护、易替换、易升级。

**8 技术选型清单**

**8.1 基础环境**

• PHP：8.1 / 8.2 / 8.3

• Composer：2.x

• 服务器：Linux

• Web服务器：Nginx

**8.2 自研核心**

• IOC 容器（自研）

• AOP 切面引擎（自研）

• ORM 持久层（自研）

• 路由引擎（自研）

**8.3 第三方依赖（最小依赖）**

• PDO 数据库扩展

• Redis 扩展

• Guzzle HTTP客户端

• YAML 解析

• JWT 库

**8.4 数据库与中间件**

• MySQL、PostgreSQL、Oracle

• Redis

• Nacos、Consul

• MinIO、OSS

**8.5 测试与运维**

• PHPUnit

• Docker

• Kubernetes

• Prometheus + Grafana

**9 非功能架构设计**

**9.1 性能设计**

• 内核轻量化、低内存占用

• 减少反射、减少IO操作

• 异步日志、异步上传

• 连接池复用、缓存减少DB请求

• 路由O(1)匹配，无性能损耗

**9.2 可用性设计**

• 全局异常捕获，不崩溃

• 限流、熔断、降级，防雪崩

• 优雅关闭，不中断正在执行请求

• 多实例集群部署，无单点

**9.3 扩展性设计**

• 全部组件插件化、可插拔

• 提供SPI扩展点

• 支持自定义实现替换内置组件

• 支持自定义路由、ORM、缓存、权限

**9.4 安全性设计**

• 所有入口参数强制校验

• XSS、SQL注入、CSRF自动防护

• 敏感数据加密存储、加密传输

• 细粒度权限控制

• 操作日志、审计日志全记录

**9.5 可维护性设计**

• 统一代码规范

• 全链路TraceId追踪

• 监控+告警全覆盖

• 配置与代码分离

• 结构清晰、职责单一、易读易改

**10 部署架构方案**

**10.1 开发环境**

• PHP 8.1+

• Composer

• MySQL + Redis

• 内置Server直接启动

**10.2 测试环境**

• Nginx + PHP-FPM

• Docker 容器化

• 独立DB、Redis，环境完全隔离

• 自动化接口测试、安全扫描

**10.3 生产环境**

• 小型项目：单机部署

• 中型项目：多实例 + Nginx 负载均衡

• 大型微服务：Docker + K8s 编排，支持弹性伸缩、灰度发布、健康检查、自动自愈

**10.4 运维规范**

• 配置外置、敏感配置加密

• 日志自动切割、自动清理

• 监控全覆盖、异常实时告警

• 版本可灰度、可回滚

**11 架构亮点与优势**

• 超轻量、启动快、内存占用低

• 全注解、零XML、极少配置

• 企业级能力齐全，开箱即用

• 架构分层清晰、模块解耦、易维护

• 高并发、高安全、高可用

• 标准化强，团队协作成本极低

• 扩展性极强，支持单体→微服务平滑升级

**12 术语说明**

• IOC：控制反转，容器管理对象

• AOP：面向切面，统一横切逻辑

• RBAC：基于角色的权限控制

• TraceId：全链路追踪ID

• 熔断降级：服务高可用容错机制

• ORM：对象关系映射，数据库操作封装

**13 版本变更记录**

| 版本 | 日期       | 变更内容                     |
| ---- | ---------- | ---------------------------- |
| V1.0 | 2026-04-01 | 初始正式版，完整架构定型发布 |

 

如果你愿意，我可以**再给你配套一份：**
**《FendxPHP 架构设计图（文字版，可直接贴进Word做架构图）》**
要我给你补上吗？要我就直接发。

|（注：文档部分内容可能由 AI 生成）