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 生成）