# 基于 Swoole 的极简 PHP 框架 · 产品方案

**作者**：吉祥法师

## 1. 文档目的与定位

本产品方案的唯一使命，是清晰阐明这个基于 Swoole 的 PHP 框架要解决什么核心问题、服务哪类用户、提供哪些关键能力，以及划定明确的边界。它作为项目立项和所有优先级决策的唯一事实来源，与配套的《技术方案》文档共同构成整个框架的完整蓝图。核心 Composer 包名已确定为 `magic/framework`。关于框架的生命周期管理、类加载机制以及可选包的生效链条，可参阅《技术方案》的对应章节。

这份文档不是为了罗列所有功能，而是为了在复杂的决策环境中，提供一个稳定的参照系。每当团队面临“这个功能要不要做”、“这个依赖要不要加”的分歧时，答案应从这份文档中寻找。它定义了框架的基因，确保所有开发行为都不偏离最初的战略方向。

## 2. 术语定义：“极简”的真实内涵

在本框架的语境下，“极简”绝非功能阉割或能力薄弱。它是一个经过精密设计的、多维度的价值主张，具体体现在以下四个层面。

**设计极度简单，但能力不简单。** 这意味着核心概念数量被压缩到最低限度，分层结构清晰透明，默认行为遵循最符合直觉的预期，几乎不需要查阅文档就能理解。然而，“简单”绝不等于“该有的没有”。一个现代 Web 框架所必需的路由、中间件、容器、可观测性、生产环境安全保障等核心能力，全部在其涵盖范围之内。这种设计哲学追求的是“少即是多”，用最精炼的概念解决最核心的问题。

**运行与依赖极度简单，供应链安全可控。** 整个框架的主运行路径仅依赖 PHP 和 Swoole 扩展，不堆砌深不见底的第三方依赖树。对 Composer 依赖的引入保持极其克制的态度，这意味着供应链管理、版本升级和安全审计的范围被大幅度缩小。对于一个需要长期维护的生产系统，这个特性直接降低了运营风险和技术债务。

**高性能，但不是通过玄学实现。** 在 Swoole 提供的常驻内存和协程模型下，框架的核心请求处理路径被设计为“无多余抽象”和“无过度反射”。这不是通过复杂的编译器优化或晦涩的黑魔法，而是通过保持代码路径的直接和透明来实现。这种设计不仅便于跑出稳定的吞吐量和低延迟，更关键的是，它让性能剖析和调优变得可预测、可操作。

**使用简单，上手门槛极低。** 从安装依赖到首次通过浏览器访问到 HTTP 响应，步骤被压缩到极致。核心概念和 API 面的学习，可以在一个页面篇幅的核心文档内完成。所有复杂的、进阶的能力，被精心封装在“进阶”章节中，不会污染初学者的一览无余的主路径。这不是一个需要啃上千页文档才能入门的框架，而是一个打开即可用、用起来就懂的框架。

**强调：“极简”不是“功能极简”或“玩具 Demo”。** 它意味着在保持核心概念极简的前提下，依然提供路由、中间件、容器、生产基线等一个真正可用的 Web 和常驻进程框架所必需的一切。它是在“胖框架”和“空框架”之间寻找的最优平衡点。

从实现视角看，常驻实现方式与标准 FPM 模式的关键区别，进程、Worker、协程以及 Composer 类加载的详细图文解释，以及可选包的双层加载机制和 Provider 的具体操作步骤，都统一在《技术方案》中进行阐述，确保产品设计与技术实现的连贯性。

## 3. 产品定位：一个清晰的市场角色

本框架是一款**面向常驻进程与协程模型的极简主义 PHP HTTP 框架**。它的核心哲学是：在保留“路由、中间件、依赖注入、可测试性”等所有现代 Web 框架必备能力的基础上，大刀阔斧地削减“全家桶式”的概念堆叠、隐晦的魔法操作和过重的运行时负担。它不是要做一个功能更少的框架，而是要做一个心智负担更低的框架，让用户用最少的核心概念，就能在 Swoole 上构建出稳定、可评审、值得信赖的 API 服务。

**质量档位被明确定义为“生产可用”和“企业可用”。** 这意味着它不是仅供演示或玩具项目使用。它需要能够长期稳定地运行在真实流量下，默认具备可运维性（如优雅退出、健康检查、日志关联ID）和可观测性，并满足常见的内部控制和安全性评审的基线文档与行为。这是一份严肃的承诺，也是所有开发的硬性目标。

一句话概括：Swoole 原生、体积小巧、心智负担低。它最适合的场景包括：自建微服务网关、内部 API 服务、BFF（Backend For Frontend）层、控制面服务，以及在合规压力下仍需保持精简技术栈的团队。

## 4. 目标用户画像：为谁而生

这款框架并非为所有 PHP 开发者设计，它有清晰的用户侧写。

- **有经验的 PHP 工程师**：他们需要协程带来的高并发 HTTP 处理能力，但同时不希望为了这个能力而背负整个 Laravel 那样的沉重运行时。他们追求高效的工具，而不是一个复杂的生态系统。
- **小团队后端**：负责开发 API 网关、内部 RPC 的 HTTP 适配层、Webhook 聚合器。这些场景对速度、稳定性和简洁性要求极高，但对 ORM、队列等全栈功能需求较少。
- **企业与基础设施团队**：他们需要部署的是一项“可审计、可发布、可回滚”的常驻服务。任何一次安全或运维评审都需要清晰的清单来核对。框架的简洁性和自文档化特性，对这种场景至关重要。
- **Swoole 学习者**：一个“结构清晰、依赖极少”的框架，是理解请求生命周期和协程环境下各种注意事项的最佳路径。它本身就是一个优秀的学习范例。

**非首要用户**是重度依赖 ORM、队列、视图层或 CMS 的一站式业务开发团队。对这类需求，更建议选用功能匹配的成熟全栈框架，或将成熟组件进行组合。

## 5. 核心价值主张：七个不可妥协的承诺

- **与 Swoole 同构**：框架的启动模型、全局单例和服务生命周期，在设计与心智模型上与 Swoole 保持一致。开发者不需要学习两套思维方式，所有的 Swoole 知识都可以直接复用。
- **设计与依赖极简**：对外暴露的核心类型和扩展点，可以通过少量文档章节完全覆盖。Composer 依赖面可控，从根本上降低了供应链风险。同时，它依然覆盖了现代 HTTP 服务的全部所需能力，完美实现“少依赖”与“多能力”的统一。
- **可演进**：模块化边界清晰，用户可以按需挂载不同的组件，而不是一上来就面对一个堆满插件的庞然大物。它随着你的业务共同成长，而不是一个你不得不去适应的庞然大物。
- **可运维**：常驻进程的标配功能一应俱全，包括优雅退出、请求超时、日志关联 ID、健康检查等。框架不仅考虑如何跑起来，更考虑如何跑得稳。
- **可托付**：每个版本都是可追溯的（语义化版本、清晰的变更日志），所有依赖项和许可证都可以被盘点。这满足了企业采购和开源治理的所有常见要求，是一份可以交付的信任。
- **高性能**：核心请求路径轻量、可度量。它不通过堆叠抽象来换取所谓的“伪简单”，基准测试和回归门禁将性能管理变成一项可量化的工程实践。
- **使用简单**：安装启动步骤少，默认配置即可跑通示例。日常写路由和 Handler 没有高门槛的仪式和约定。核心故事的快速启动，随核心功能一并提供，无需安装多个扩展包即可运行。重度能力组件化，按需注册。

## 6. 差异化优势：将目标变为可验证的工程实践

差异化优势不是宣称“功能比全栈框架还多”，而是在“极简”这条赛道上，把每一项可验证的事情做穿做透。这些优势被拆解为可写进路线图、可进行验收、可提交评审的硬性要求。

### 6.1 可验证的“极简” = 信任资产

- **依赖预算**：为核心包设定直接依赖的数量上限或白名单策略。每个新的 Composer 依赖，都必须附带一份用途说明文档或架构决策记录，避免自然膨胀。
- **启动路径可读**：维护一份从“进程入口”到“首次 onRequest”的完整走读表，每一行标注文件、类和职责。在版本发布前，必须与代码同步审计。
- **生产与企业可核对**：在文档目录下提供一份“生产部署清单”，与生产环境所需的安全检查、健康检查、信号处理和日志章节逐项对应，便于答审和复测。
- **性能可核查**：提供可脚本化的轻量级基准测试。大版本发布时，要对照性能变化趋势进行说明，杜绝玄学式的 QPS 宣称。
- **上手可复制**：README 中的 Quickstart 步骤必须与目录中的 `example/` 示例完全一致。新人按命令逐步操作，一定要能复现 HTTP 响应。

验收口径：对外能清晰地说出“依赖为什么少，少在哪里”；对内能顺着走读表完整读完启动链路。

### 6.2 首发场景做深（窄胜宽）

不追求“万能框架”。P0 和 P1 阶段，集中所有资源在 1-2 个高密度场景上做深做透，例如：内网 API 网关或 BFF 层。将中间件配置、超时策略、健康检查、故障排查方法，全部写成该场景下的“推荐组合包”，而不是散落在配置文档各处的零散键值对。

验收口径：官方示例和文档要提供一条清晰的“推荐路径”。新用户不需要在几十种可选方案中摸索，跟着走就能得到最佳实践。

### 6.3 契约与门禁（防止优势被迭代冲掉）

- **示例即契约**：`example/` 目录与 CI 系统联通。凡是破坏示例的核心行为变更，一律视为破坏性变更，必须同步修改示例和变更日志。
- **发布三连**：每次发布必须同时包含语义化版本、更新日志和迁移小节（如有 API 变更）。坚决不在静默中修改任何行为。
- **协程/常驻专项**：文档中承诺的阻塞 IO 说明、Worker 模型、探针、优雅退出方式，必须与自动化测试或演练的记录完全一致。

### 6.4 文档与选型边界（诚实定位）

在 README 的首屏就要诚实地告知所有潜在用户：“本框架不是通用全栈应用框架的替代品。它专注于‘设计极简 + 依赖极简 + 生产清单可勾选’的 Swoole 常驻 HTTP 服务。如果你需要完整的 ORM、队列或建站全家桶，应该选用体量匹配的成熟方案。” 诚实的边界能有效降低用户的误判率和团队的技术采纳成本。

- **高性能定位**：所谓高性能，是要参与“场景化、可回归”的性能验证，例如空路由、代表性业务 Handler。对比时要明确标注“同机、同 Swoole 版本与配置”的条件，避免唯 QPS 论。对于每一层新增的抽象，都保持高度克制。
- **使用简单定位**：“简单”体现为步骤少、概念少、默认行为已经足够好，而不是功能的阉割。所有进阶能力（如可观测性、安全加固、复杂路由）都是可选的，并且文档会进行清晰的分栏展示，避免将初学者挡在门外。

## 7. 生产可用 & 企业可用（定性要求）

这是框架能否被严肃采用的试金石。

### 7.1 生产可用（可靠性 & 可运维性）

- **进程模型可控**：支持多 Worker、优雅退出、并提供文档化的重载与滚动发布注意事项。不因为追求“设计与依赖的精简”而省略线上运维必须回答的问题。
- **健康检查**：提供分开的“就绪（readiness）”和“存活（liveness）”的健康检查路由与清晰语义，方便接驳 K8s 或负载均衡设备。
- **超时与边界**：请求处理超时、连接超时、上游超时等策略，全部可在配置层面表达。避免无上限的阻塞操作耗尽整个 Worker 进程。
- **故障可诊断**：默认提供结构化日志、请求关联 ID、以及清晰的错误分类（用户错误与系统错误）。生产环境绝不泄露堆栈细节或敏感信息。
- **回归护栏**：核心路径必须具备自动化测试和 CI 门禁，任何重大的行为变更都能被机器察觉。

### 7.2 企业可用（安全、合规与治理）

- **安全基线内化**：HTTPS 终端、代理头信任、Cookie 和会话管理（后续若引入），都有显式的安全默认值和文档说明，避免由于误配置导致的 IP 伪造或未加密传输。
- **供应链与许可**：管理好 `composer.lock` 文件、许可证声明、并在 CI 中集成依赖漏洞扫描。任何重大的第三方库变更，必须在变更日志中可见。
- **发布与兼容**：严格遵循语义化版本。任何破坏性变更，必须在文档和迁移说明中明确提示。长期维护策略在 README 或可核对的文档中声明。
- **审计友好**：关键配置项、安全相关的默认值、以及与 Swoole 版本的绑定关系，全部可追溯，便于安全评审和渗透测试的反复核查。

说明：“企业可用”指的是框架本身和其文档已经达到常见评审的基线水平，并非自带等保或 ISO 认证。行业专项合规要求，仍需由部署团队和应用层来补充实现。

## 8. 产品范围（MVP）

### 必须包含
- HTTP 服务端抽象，运行于 Swoole HTTP Server 之上。
- 路由注册与分组功能，支持前缀和中间件组。
- 中间件流水线，采用洋葱模型。
- 轻量容器：支持构造器注入和简易的接口绑定。
- 请求与响应对象封装，对常见的 JSON 和表单场景开箱即用。
- 配置加载，从环境变量和多文件中选择一种方式。
- 统一的异常到 HTTP 响应的映射机制。
- 生产基线：健康检查路由、优雅关闭协作点、请求关联 ID、生产环境错误脱敏策略。
- 扩展载入契约：提供显式的扩展注册入口，使官方可选包与用户模块遵循同一载入路径。

### 明确不包含（首版不做）
- 完整的 ORM 与数据库迁移工具链。
- 自带队列、异步任务编排、Cron 表达式调度。
- 模板引擎和会话依赖的 MVC 建站范式。
- 官方 Admin 系统或脚手架市场。

## 9. 非功能需求（与用户可感知）

- **高性能**：核心管道（解析、路由、中间件、发射响应）必须保持热路径可读、可 profile，坚决避免隐性的全量反射和无意义的对象分配。与 Swoole 协程模型保持一致，文档明确提示阻塞 IO 的代价。提供可复现的轻量级基准和回归阈值，大版本不能无故显著劣化。
- **使用简单**：上手路径极致简化，安装依赖、一条命令、一个示例响应，即可完成。API 面稳定直观，常见操作在快速启动指南中全覆盖。不强制用户继承深层基类或编写冗长配置。错误信息有行动指引。
- **安全默认**：不信任任何客户端输入。安全相关中间件，在达到“企业基线”所需的范围内，作为核心或首选文档模板提供。
- **可观测性**：请求级别的 trace 和 request id，结构化日志的字段约定。预留指标和分布式追踪的钩子接口，避免企业级观测栈对接时再来大改核心。
- **许可与依赖**：对外声明依赖策略，如 MIT 协议加最少的第三方包，降低法务评估成本。

## 10. 成功标准（可验收）

- **30 分钟入门测试**：新用户按文档，能够在 30 分钟内从空目录到实现一个可访问的 JSON API 服务（含健康检查路由）。
- **核心文档的简洁性**：核心概念文档不超过 5 个主标题，其余内容全部放入“进阶”部分。
- **官方示例即契约**：提供一个官方的示例应用，作为集成测试和教程蓝本，并与“示例即契约”的原则保持一致。
- **CI 通过率**：在声明的 PHP 和 Swoole 版本矩阵下，所有 CI 自动化测试均需通过。
- **生产与部署清单**：满足所有已由技术方案实现的生产和企业可用性条款，并提供“生产部署清单”。
- **差异化优势可验证**：能出具依赖说明、启动走读表、与首发场景一致的推荐路径文档。
- **基准可运行**：技术方案中声明的基准测试方案必须是可运行的，核心路径的任何变更都需自觉避免不合理的性能劣化。
- **无需查源码即可完成**：新的用户在完全不查看源码的情况下，仅依赖 Quickstart 指南，就能完成 30 分钟入门测试。

## 11. 路线图（建议）

- **P0 阶段（MVP）**：完成 MVP 所有功能，实现生产和企业基线，包含第 6 节最小差异化集。Quickstart 与性能基线能够跑通，依赖说明、走读表、生产清单和示例代码全部进入 CI。
- **P1 阶段**：强化优雅重载和发布指南，明确首发场景的推荐组合，落地可观测性钩子（指标和追踪），并在 CI 中增加可选的性能回归测试。
- **P2 阶段**：发布官方扩展包，包括验证器、限流器，以及与常见存储客户端的协程版对接说明。

## 12. 风险与对策（产品侧）

| 风险 | 对策 |
| :--- | :--- |
| 用户期望这是“另一个 Laravel” | 在文档首页明确其非目标和替代选型 |
| 协程下误用阻塞 IO | 在文档与示例中强调客户端选型，并提供检测告警建议 |
| 生态碎片化 | 稳定少量扩展点，避免出现上千种配置键 |
| 评审误读“极简”为“功能少、不可靠” | 通过明确定义、生产清单和全链路可核验的 CI 与变更记录来呈现 |
| 差异化在迭代中被稀释 | 坚守“示例即契约”的门禁和发布三连的规范 |
| “高性能/易用”停留在口号 | 通过“性能可核查”和“上手可复制”的工程化手段来落地 |

## 13. 文档与品牌

- Composer / Packagist 的项目名称为 `magic/framework`。对外名称、Slogan、以及与本仓库的定位边界，将在 README 首屏写清，避免被误读为“另一个全栈框架”。
- 面向企业的信息，包括安全披露渠道、版本支持周期、以及破坏性变更策略，将在 README 或 SECURITY.md 中公开。

本文件仅描述“做什么、为谁、做到哪一步”。所有实现结构、模块划分和依赖选型的细节，请参阅配套的《技术方案》。