第四章 项目目录与文件组织
项目目录与文件组织是 WangStruct Framework 从总体架构进入实际工程开发的基础。本章将前面确定的六层架构落实到具体的项目目录、程序文件和加载关系中,使开发者能够按照统一规范创建项目、编写程序、开发组件和扩展功能。
一个成熟的开发框架,不仅需要明确有哪些功能模块,还必须明确这些功能应该放在哪个目录、由哪个文件负责、如何被框架加载,以及开发者如何在不修改核心程序的情况下增加新功能。
WangStruct Framework 的目录设计遵循三个原则:核心程序与应用程序分离,框架程序与扩展程序分离,程序代码与运行数据分离。
同时,目录组织不能过度复杂。每个目录都应当具有明确的职责,避免出现多个目录保存相同类型程序、文件职责重复以及程序加载关系混乱等问题。
本章建立一套完整的参考项目目录规范。该目录结构是后续工程实现的设计基准,实际开发时应当以确定后的接口和代码为准,不将尚未实现的文件视为已经存在的程序。
4.1 项目目录设计原则
WangStruct Framework 的项目目录既要满足传统软件框架的工程组织要求,也要支持动态结构、知识、能力和智能运行等功能的扩展。
目录设计不是简单地按照文件类型分类,而是按照程序职责、运行层次和开发边界进行组织。
4.1.1 核心程序独立
框架核心程序应当集中放在独立目录中,不与具体应用业务代码混合。
核心目录主要保存框架启动、容器管理、组件注册、生命周期管理和公共接口等程序。
开发者在开发应用时,原则上不需要修改核心目录中的程序。
当框架核心升级时,应用程序和扩展程序应当尽可能保持独立,减少升级对已有项目的影响。
4.1.2 应用程序独立
应用目录用于保存开发者自己的应用程序。
不同应用可以分别组织控制器、模型、服务、页面、业务对象和应用配置。
框架核心不应当直接包含某个应用的具体业务逻辑。
例如,设备管理应用、智能服务应用和智能个体应用可以使用同一个框架,但各自具有独立的应用目录。
4.1.3 配置文件独立
配置目录用于保存框架、应用、数据库、组件和运行环境的配置。
配置文件不应当与业务代码混合,也不应当将密码、密钥等敏感信息直接写入公开的示例配置文件。
框架配置负责确定程序如何运行,应用配置负责确定具体应用如何运行,组件配置负责确定具体组件如何工作。
4.1.4 扩展程序独立
第三方开发者开发的组件、插件和适配器应当放在扩展目录中。
扩展程序应当按照框架规定的注册规范接入,不应当直接修改核心程序。
这样可以使框架本身、应用程序和第三方扩展具有相对独立的升级和维护空间。
4.1.5 运行数据与程序代码分离
运行过程中产生的数据不能与程序文件混合保存。
例如,缓存文件、日志、临时文件、任务记录、上传文件和运行状态数据,应当统一放在运行数据目录或由外部存储服务管理。
这种分离可以降低程序升级时误删业务数据的风险,也便于进行数据备份、权限控制和运行维护。
4.2 项目根目录结构
WangStruct Framework 采用统一项目根目录组织框架程序、应用程序、配置文件、公共资源、扩展组件、运行数据和测试程序。
参考项目结构如下:
WangStruct/
│
├── framework/ # 框架核心与内置组件
│ ├── Core/ # 核心层
│ ├── Foundation/ # 基础服务层
│ ├── Components/ # 功能组件层
│ ├── Runtime/ # 智能运行层
│ ├── Contracts/ # 公共接口契约
│ └── Support/ # 框架内部辅助程序
│
├── applications/ # 应用程序
│ ├── Web/
│ ├── IntelligentService/
│ ├── Individual/
│ └── Machine/
│
├── config/ # 全局配置
│ ├── framework.php
│ ├── components.php
│ ├── services.php
│ └── environment.php
│
├── public/ # Web 公共入口与公开资源
│ ├── index.php
│ ├── assets/
│ └── uploads/
│
├── extensions/ # 第三方扩展
│ ├── Components/
│ ├── Adapters/
│ ├── Drivers/
│ └── Plugins/
│
├── resources/ # 模板、语言及静态资源
│ ├── views/
│ ├── languages/
│ └── assets/
│
├── storage/ # 运行数据
│ ├── cache/
│ ├── logs/
│ ├── sessions/
│ ├── temporary/
│ ├── uploads/
│ └── data/
│
├── tests/ # 测试程序
│ ├── Unit/
│ ├── Integration/
│ ├── Compatibility/
│ └── Fixtures/
│
├── vendor/ # 第三方依赖
│
├── bin/ # 命令行工具
│
├── docs/ # 开发文档
│
├── composer.json # PHP 参考实现的依赖与加载配置
├── composer.lock # PHP 依赖锁定文件
├── LICENSE # 许可文件
└── README.md # 项目说明
以上是完整的参考工程目录。它同时考虑了框架自身开发、应用开发、第三方扩展、测试和部署维护等需要。
需要注意,framework/ 是框架程序目录,applications/ 是具体应用目录,extensions/ 是第三方扩展目录。三者不能相互混用。
另外,vendor/、composer.json 和 composer.lock 属于 PHP 参考实现中的依赖管理组织方式,并不是要求 Python、C、C++、Java 或其他语言实现也必须采用 Composer。
4.3 框架核心目录
框架核心目录为:
framework/
该目录用于保存 WangStruct Framework 自身的核心程序、基础服务、功能组件、智能运行模块和公共接口。
核心目录按照总体架构划分为不同子目录。
4.3.1 Core 核心层目录
framework/
└── Core/
├── Framework.php
├── Application.php
├── Container.php
├── ComponentRegistry.php
├── ServiceRegistry.php
├── LifecycleManager.php
├── Bootstrap.php
└── Exception/
├── FrameworkException.php
├── ComponentException.php
└── ConfigurationException.php
主要文件职责如下:
| 文件 | 职责 |
|---|---|
| Framework.php | 框架主对象,统一管理框架运行 |
| Application.php | 应用实例与应用运行环境 |
| Container.php | 核心服务对象的注册和获取 |
| ComponentRegistry.php | 组件注册、查询和管理 |
| ServiceRegistry.php | 公共服务注册和调用 |
| LifecycleManager.php | 组件及服务生命周期管理 |
| Bootstrap.php | 框架启动过程组织 |
| Exception/ | 框架核心异常定义 |
其中,Framework.php 是核心运行管理对象,负责协调其他核心对象,但不直接处理具体业务。
Container.php 负责管理需要共享的服务对象,避免不同程序重复创建同一类基础服务。
ComponentRegistry.php 负责维护组件注册信息,记录组件名称、接口、版本和加载状态。
LifecycleManager.php 负责统一管理组件初始化、启动、关闭等过程。
核心层的文件命名采用与类名一致的方式。例如:
Container.php
ComponentRegistry.php
LifecycleManager.php
这种命名方式便于开发者根据类名定位对应文件,也有利于自动加载。
4.3.2 Foundation 基础服务目录
framework/
└── Foundation/
├── Config/
│ ├── ConfigManager.php
│ └── ConfigRepository.php
│
├── Loader/
│ └── Autoloader.php
│
├── Database/
│ ├── DatabaseManager.php
│ ├── Connection.php
│ └── QueryBuilder.php
│
├── Cache/
│ ├── CacheManager.php
│ └── CacheInterface.php
│
├── File/
│ └── FileManager.php
│
├── Log/
│ ├── Logger.php
│ └── LogManager.php
│
├── Http/
│ ├── Request.php
│ └── Response.php
│
├── Event/
│ ├── EventDispatcher.php
│ └── Event.php
│
└── Security/
├── Authentication.php
└── Authorization.php
基础服务目录按照技术职责组织。
例如,数据库服务集中放在 Database/,缓存服务集中放在 Cache/,日志服务集中放在 Log/。
开发者需要增加数据库驱动时,应当根据数据库接口规范增加相应实现,而不是直接修改所有使用数据库的功能组件。
基础服务目录的具体组织方式也体现了框架的技术开放原则:上层模块使用统一服务接口,底层可以采用不同技术实现。
4.3.3 Components 功能组件目录
framework/
└── Components/
├── Routing/
├── Controller/
├── Model/
├── View/
├── Structure/
├── Object/
├── Relationship/
├── Semantic/
├── Knowledge/
├── Capability/
├── Task/
└── Behavior/
每个功能组件应当具有相对独立的目录。
例如,结构管理组件可以进一步组织为:
framework/
└── Components/
└── Structure/
├── StructureManager.php
├── StructureDefinition.php
├── StructureElement.php
├── StructureValidator.php
├── StructureRepository.php
└── Contracts/
└── StructureInterface.php
这些文件的职责分别是:
-
StructureManager.php:结构管理入口,负责协调结构定义、注册和查询。 -
StructureDefinition.php:表示结构定义及其基本信息。 -
StructureElement.php:表示结构中的元素。 -
StructureValidator.php:检查结构定义是否合法。 -
StructureRepository.php:负责结构数据的存储和读取。 -
Contracts/StructureInterface.php:定义结构管理相关的公共接口。
这种组织方式使结构管理的不同职责能够独立维护。
对象管理、知识管理和能力管理也可以采用类似的目录组织方式,但不能为了追求目录形式一致而强制每个组件都创建没有实际职责的文件。
4.3.4 Runtime 智能运行目录
framework/
└── Runtime/
├── Requirement/
├── Understanding/
├── Decision/
├── Method/
├── Behavior/
├── Execution/
├── Feedback/
└── Evolution/
智能运行目录用于组织智能运行过程中的协调模块。
例如:
framework/
└── Runtime/
├── Requirement/
│ ├── RequirementManager.php
│ └── RequirementAnalyzer.php
│
├── Decision/
│ ├── DecisionManager.php
│ └── DecisionContext.php
│
├── Execution/
│ ├── ExecutionManager.php
│ └── ExecutionResult.php
│
└── Feedback/
├── FeedbackManager.php
└── FeedbackRecord.php
需求模块负责组织需求信息,决策模块负责管理决策过程,执行模块负责组织能力调用和执行结果,反馈模块负责记录运行结果和状态变化。
智能运行目录不应当重复实现功能组件层已经提供的管理功能。
例如,知识管理组件负责知识数据的存储和查询,智能运行模块只负责在任务过程中调用知识管理接口,不应当再建立一套独立的知识存储系统。
4.3.5 Contracts 公共接口目录
framework/
└── Contracts/
├── ComponentInterface.php
├── ServiceInterface.php
├── StorageInterface.php
├── StructureInterface.php
├── ObjectInterface.php
├── KnowledgeInterface.php
├── CapabilityInterface.php
└── ExtensionInterface.php
Contracts/ 用于集中管理框架公共接口契约。
公共接口应当保持稳定,并明确规定组件必须提供的功能。
例如,组件接口可以定义如下:
interface ComponentInterface
{
public function getName();
public function getVersion();
public function initialize($container);
public function start();
public function shutdown();
}
这个接口表达的是组件生命周期的基本约束。
实际实现时,还需要确定初始化失败时的处理方式、启动顺序、关闭顺序和组件状态管理规则。
公共接口目录不能与具体实现混合。接口规定组件需要具备什么能力,组件类则负责实现这些能力。
4.4 应用目录
应用目录为:
applications/
它是开发者创建具体项目功能的主要位置。
框架自身提供通用能力,但不预先规定所有应用必须使用相同的业务结构。
不同应用可以独立组织自己的控制器、服务、模型、对象、知识和能力。
4.4.1 应用目录组织
参考目录如下:
applications/
├── Web/
│ ├── Controllers/
│ ├── Models/
│ ├── Services/
│ ├── Views/
│ ├── Routes/
│ ├── Objects/
│ ├── Knowledge/
│ ├── Capabilities/
│ └── Application.php
│
├── IntelligentService/
│ ├── Controllers/
│ ├── Services/
│ ├── Objects/
│ ├── Knowledge/
│ ├── Capabilities/
│ ├── Requirements/
│ └── Application.php
│
├── Individual/
│ ├── Templates/
│ ├── Instances/
│ ├── Knowledge/
│ ├── Capabilities/
│ ├── Behaviors/
│ └── Application.php
│
└── Machine/
├── Devices/
├── Sensors/
├── Controllers/
├── Capabilities/
├── Drivers/
├── Safety/
└── Application.php
这几个应用目录只是说明框架能够支持的不同应用类型,并不意味着所有项目都必须创建这四个目录。
开发者可以根据实际项目只创建一个应用,也可以在同一项目中建立多个相互独立的应用。
4.4.2 应用目录职责
Controllers/ 保存请求控制器,负责接收请求和组织应用服务调用。
Models/ 保存应用数据模型,负责应用数据的组织和访问。
Services/ 保存应用业务服务,负责具体业务逻辑。
Views/ 保存应用页面和模板。
Routes/ 保存应用路由定义。
Objects/ 保存应用定义的对象类型和相关程序。
Knowledge/ 保存应用自己的知识定义和知识数据管理程序。
Capabilities/ 保存应用开发的能力程序及其注册描述。
Behaviors/ 保存智能个体或其他应用对象的行为定义。
Drivers/ 保存面向具体设备的驱动适配程序。
Safety/ 保存设备控制相关的安全约束程序。
应用目录的核心要求是:应用自己的功能由应用自己管理,不将具体业务代码写入框架核心。
4.4.3 开发者如何创建新应用
例如,开发者需要创建一个新的智能服务应用,可以在 applications/ 下创建:
applications/
└── MyService/
├── Controllers/
├── Services/
├── Objects/
├── Knowledge/
├── Capabilities/
├── Routes/
└── Application.php
然后根据框架的应用接口规范编写 Application.php,在应用配置中声明应用名称、启动入口和必要依赖。
应用创建不需要修改 framework/Core/ 中的程序。
框架通过应用注册和启动机制加载该应用。
具体的应用注册方法和启动代码,应当在后续应用开发章节中完整实现。
4.5 配置目录
配置目录为:
config/
配置文件负责控制框架、应用和组件的运行方式。
配置内容与程序代码分开保存,可以使开发者在不修改程序逻辑的情况下调整运行环境和功能参数。
4.5.1 全局配置文件
config/
├── framework.php
├── components.php
├── services.php
├── applications.php
├── environment.php
└── security.php
主要职责如下:
| 配置文件 | 主要职责 |
|---|---|
| framework.php | 框架基础参数 |
| components.php | 组件注册和加载配置 |
| services.php | 服务实现与服务映射 |
| applications.php | 应用注册和启动配置 |
| environment.php | 当前运行环境 |
| security.php | 安全相关配置 |
4.5.2 框架配置示例
<?php
return array(
'name' => 'WangStruct Framework',
'debug' => false,
'timezone' => 'Asia/Shanghai',
'default_application' => 'Web'
);
框架通过配置管理服务读取配置文件,其他模块不应当在多个位置重复硬编码同一配置参数。
4.5.3 组件配置示例
<?php
return array(
'Structure' => array(
'enabled' => true
),
'Knowledge' => array(
'enabled' => true
),
'Capability' => array(
'enabled' => true
)
);
以上示例用于说明组件启用配置的组织方式。
实际实现中还需要明确组件名称、版本、加载路径、依赖关系和初始化参数。
4.5.4 应用配置与环境配置分离
应用配置可以单独保存在应用目录,也可以由全局配置统一管理。
开发环境、测试环境和生产环境应当使用不同的环境配置。
例如:
config/
├── environments/
│ ├── development.php
│ ├── testing.php
│ └── production.php
数据库密码、API 密钥和其他敏感参数应当通过环境变量或安全配置机制提供,不应当直接写入公开代码仓库。
4.6 公共资源目录
公共资源目录由 public/ 和 resources/ 两部分构成。
二者不能混淆。
public/ 保存允许 Web 服务器直接访问的入口程序和公开资源。
resources/ 保存应用模板、语言文件和需要由程序读取或编译的资源。
4.6.1 public 目录
public/
├── index.php
├── assets/
│ ├── css/
│ ├── js/
│ ├── images/
│ └── fonts/
└── uploads/
index.php 是 Web 应用的统一入口。
用户请求进入 Web 服务器后,由该入口加载框架并启动应用。
assets/ 保存公开访问的 CSS、JavaScript、图片和字体等文件。
uploads/ 用于保存允许公开访问的上传文件。涉及隐私、内部资料或不应直接公开的文件,应当存放在受控目录,通过权限检查后的程序接口提供访问。
4.6.2 resources 目录
resources/
├── views/
├── languages/
└── assets/
views/ 保存模板文件。
languages/ 保存多语言资源。
assets/ 保存需要参与构建、编译或由程序管理的资源。
例如,Smarty 模板可以放在应用的 Views/ 或统一模板目录中,由视图组件负责定位和渲染。具体采用哪一种组织方式,需要在视图组件开发时统一确定,不能让同一个模板同时存在多个不明确的默认位置。
4.7 扩展目录
扩展目录为:
extensions/
它用于保存框架之外独立开发的组件、驱动、适配器和插件。
扩展目录与 framework/Components/ 的区别在于:
-
framework/Components/保存框架内置并由框架维护的组件; -
extensions/保存可独立安装、升级和移除的扩展程序。
4.7.1 扩展目录组织
extensions/
├── Components/
│ └── ExampleComponent/
│ ├── ExampleComponent.php
│ ├── Component.php
│ ├── config/
│ └── README.md
│
├── Adapters/
│ ├── Database/
│ ├── Communication/
│ └── Language/
│
├── Drivers/
│ ├── Device/
│ └── Sensor/
│
└── Plugins/
├── ExamplePlugin/
└── AnotherPlugin/
4.7.2 扩展组件文件职责
每个扩展应当具有自己的目录,并且至少需要包含组件入口、注册信息和必要配置。
例如:
extensions/
└── Components/
└── ExampleComponent/
├── Component.php
├── ExampleManager.php
├── config/
│ └── config.php
└── README.md
Component.php 负责实现框架规定的组件接口。
ExampleManager.php 保存扩展组件自身的功能程序。
config/config.php 保存扩展运行参数。
README.md 说明扩展的功能、安装条件、接口和使用方式。
4.7.3 第三方开发者扩展方式
第三方开发者应当按照以下方式开发扩展:
首先,在 extensions/ 下创建独立目录;然后实现框架规定的组件接口;接着声明组件名称、版本和依赖关系;最后通过框架组件注册机制完成接入。
第三方扩展不应当直接覆盖框架核心目录中的同名文件。
如果扩展需要替换已有功能,应当通过框架规定的接口绑定或适配器机制完成,而不是依赖修改核心源代码。
4.8 运行数据目录
运行数据目录为:
storage/
该目录保存框架运行过程中产生的非源代码数据。
4.8.1 目录组织
storage/
├── cache/
├── logs/
├── sessions/
├── temporary/
├── uploads/
└── data/
├── structures/
├── objects/
├── knowledge/
├── capabilities/
└── tasks/
4.8.2 主要目录职责
cache/ 保存缓存数据。
logs/ 保存系统日志、错误日志和运行记录。
sessions/ 保存会话数据。
temporary/ 保存临时文件和中间处理结果。
uploads/ 保存不适合直接公开访问的上传文件。
data/structures/ 可以用于保存动态结构定义。
data/objects/ 可以用于保存对象实例数据。
data/knowledge/ 可以用于保存知识数据。
data/capabilities/ 可以用于保存能力描述和相关注册数据。
data/tasks/ 可以用于保存任务状态和运行记录。
这里的 data/ 是文件存储实现的一种组织方式。实际项目也可以将结构、对象、知识和任务数据保存在数据库或外部存储系统中。
因此,目录名称不能被理解为框架强制要求所有数据都必须保存为本地文件。
4.8.3 运行数据安全要求
storage/ 不应当直接暴露给 Web 服务器公开访问。
应当限制目录读写权限,并根据运行环境配置访问控制。
生产环境中还应当建立必要的数据备份和恢复机制。
框架升级时,不能直接删除整个运行数据目录。
4.9 测试目录
测试目录为:
tests/
测试目录保存框架自身、功能组件、扩展组件和应用程序的测试代码。
测试程序不应当与生产程序混合。
4.9.1 测试目录结构
tests/
├── Unit/
│ ├── Core/
│ ├── Foundation/
│ ├── Components/
│ └── Runtime/
│
├── Integration/
│ ├── Framework/
│ ├── Database/
│ └── Application/
│
├── Compatibility/
│ ├── Interface/
│ ├── Component/
│ └── Version/
│
└── Fixtures/
├── Data/
└── Config/
4.9.2 单元测试
Unit/ 保存单个类或组件的独立测试。
例如:
tests/Unit/Components/Structure/
可以用于测试结构定义、属性验证、结构注册和结构查询等功能。
4.9.3 集成测试
Integration/ 用于测试多个模块组合后的运行结果。
例如,测试对象管理组件能否正确调用结构管理组件,并通过数据访问服务保存对象实例。
4.9.4 兼容性测试
Compatibility/ 用于测试接口版本、组件替换和不同技术实现之间的兼容情况。
对于跨语言实现,还需要验证实际通信、数据交换和错误处理,不能只检查 JSON 字段是否一致。
4.9.5 测试数据
Fixtures/ 保存测试使用的配置和数据。
测试数据必须与生产运行数据分离,避免测试过程误操作实际业务数据。
4.10 命令行工具与开发文档目录
除了核心程序和应用程序之外,框架还需要提供开发辅助工具与技术文档。
4.10.1 bin 目录
bin/
├── framework
├── component
├── cache
└── migrate
bin/ 用于保存命令行工具。
例如:
-
framework:框架命令行入口; -
component:组件创建和管理; -
cache:缓存管理; -
migrate:数据结构迁移。
这些是计划提供的命令行工具类别,具体命令和参数应当在实际实现时确定。
4.10.2 docs 目录
docs/
├── architecture/
├── development/
├── api/
├── components/
├── extensions/
└── deployment/
architecture/ 保存总体架构和模块关系文档。
development/ 保存开发规范。
api/ 保存公共接口说明。
components/ 保存内置组件文档。
extensions/ 保存第三方扩展开发文档。
deployment/ 保存安装、部署和维护文档。
开发文档应当与实际代码保持一致。公共接口发生变化时,相关 API 文档也应当同步更新。
4.11 命名规则与文件组织规范
目录结构确定之后,还需要统一目录、文件、类、接口、方法和配置项的命名方式。
命名规范的目的不是追求某一种风格,而是让不同开发者能够根据名称快速判断程序的职责和位置。
4.11.1 目录命名
目录名称采用具有明确含义的英文名称。
主要目录使用小写英文单词,多个单词组合时采用约定的统一方式。
例如:
framework/
applications/
extensions/
storage/
类职责目录可以使用首字母大写的名称:
Core/
Foundation/
Components/
Runtime/
同一项目中应保持一致,不应随意混用不同命名方式。
4.11.2 PHP 类文件命名
PHP 参考实现中,类文件名称与类名称保持一致。
例如:
Container.php
StructureManager.php
KnowledgeManager.php
CapabilityManager.php
对应类名称为:
class Container
{
}
class StructureManager
{
}
class KnowledgeManager
{
}
class CapabilityManager
{
}
4.11.3 接口命名
接口名称以职责为中心,并采用统一的命名约定。
例如:
ComponentInterface.php
StorageInterface.php
StructureInterface.php
CapabilityInterface.php
接口文件与具体实现文件应当分开组织。
4.11.4 方法命名
方法名称应当表达具体动作。
例如:
register()
initialize()
create()
find()
update()
delete()
execute()
shutdown()
同一类操作在不同组件中应尽量保持一致。
例如,组件注册统一使用 register(),对象创建统一使用 create(),执行能力统一使用 execute()。
如果某项操作具有特殊含义,则应当使用更明确的名称,避免仅仅为了统一而造成语义模糊。
4.11.5 配置项命名
配置项应当采用明确、稳定的英文名称。
例如:
return array(
'debug' => false,
'timezone' => 'Asia/Shanghai',
'cache_enabled' => true,
'storage_path' => 'storage/data'
);
同一配置参数不能在不同配置文件中使用多个不同名称表达相同含义。
4.11.6 文件职责唯一
一个文件应当围绕明确的程序职责组织。
例如:
-
StructureManager.php负责结构管理; -
StructureValidator.php负责结构校验; -
StructureRepository.php负责结构数据存储和读取。
不能将所有结构管理、数据库操作、对象创建和任务执行程序都写入一个大型文件。
同时,也不能为了拆分而将一个简单功能拆成大量没有独立意义的文件。
4.12 程序自动加载与文件加载关系
目录结构只有与加载机制结合,才能成为真正可运行的工程组织方式。
WangStruct Framework 需要建立统一的自动加载机制,使框架核心类、基础服务、功能组件、应用类和扩展类能够按照规定的命名空间或类名映射规则被加载。
4.12.1 PHP 参考实现的命名空间组织
PHP 参考实现可以采用命名空间与目录映射方式。
例如:
<?php
namespace WangStruct\Core;
class Container
{
}
对应文件:
framework/Core/Container.php
自动加载程序根据命名空间找到相应文件。
对于 PHP 参考实现,可以采用 PSR-4 风格的自动加载约定,但是否完全采用 Composer 管理,仍应以框架最终依赖方案为准。
4.12.2 自动加载映射示例
PHP 参考实现的命名空间映射可以设计为:
<?php
return array(
'WangStruct\\Core\\' =>
'framework/Core/',
'WangStruct\\Foundation\\' =>
'framework/Foundation/',
'WangStruct\\Components\\' =>
'framework/Components/',
'WangStruct\\Runtime\\' =>
'framework/Runtime/',
'WangStruct\\Applications\\' =>
'applications/',
'WangStruct\\Extensions\\' =>
'extensions/'
);
该映射表示不同命名空间对应的基础目录。
实际自动加载时,还需要处理命名空间分段与子目录之间的转换,并检查文件是否存在。
4.12.3 加载过程
框架启动时,首先加载自动加载程序,再创建核心容器,随后注册基础服务和组件。
其基本关系如下:
需要注意,自动加载只负责在程序需要某个类时定位并加载对应文件,不负责自动完成所有组件初始化和运行。
组件初始化、依赖检查和生命周期管理仍然由核心层负责。
4.13 开发者如何在指定位置创建和扩展程序
目录规范最终要能够指导实际开发者完成项目开发。
开发者应当根据程序所属职责选择目录,而不是将所有新程序都放入一个公共文件夹。
4.13.1 创建普通应用服务
例如,开发者需要增加一个设备查询服务,可以在应用目录创建:
applications/Web/Services/
└── DeviceService.php
该文件负责设备查询业务。
它可以调用框架的对象管理、数据访问和权限服务,但不应当直接修改框架核心程序。
4.13.2 创建动态结构
如果开发者需要增加一种新的设备结构,可以通过应用结构定义或独立扩展组件提供定义。
例如:
applications/Web/Objects/
└── Device.php
该程序负责提供应用所需要的设备结构或相关对象定义。
如果设备结构属于多个应用都需要使用的通用扩展,则应当考虑将其开发为独立组件,放在 extensions/Components/ 下,而不是直接写入某一个应用。
4.13.3 创建知识模块
如果某个应用需要独立管理专业知识,可以在:
applications/Web/Knowledge/
中组织对应知识定义和应用服务。
如果需要开发一个可以被多个应用使用的知识管理扩展,则应当放在:
extensions/Components/
中,并实现规定的知识组件接口。
4.13.4 创建能力程序
能力程序应当按照其所属范围确定位置。
只服务于一个应用的能力,放在该应用的 Capabilities/ 目录。
能够独立安装和复用的能力组件,放在扩展目录。
由其他语言编写的能力程序,则可以独立部署,通过框架规定的通信接口接入。
4.13.5 修改框架核心程序
只有在开发框架自身功能时,才应当修改:
framework/Core/
framework/Foundation/
framework/Components/
framework/Runtime/
framework/Contracts/
应用开发者原则上不应当直接修改这些目录。
如果开发者发现框架缺少某项功能,应当先判断它属于基础服务、功能组件、智能运行机制还是应用功能,再决定应当通过扩展实现,还是需要调整框架核心。
4.14 目录组织与部署安全要求
项目目录不仅影响程序开发,还直接影响部署和运行安全。
特别是 Web 项目,不能将整个项目根目录直接作为 Web 服务器公开目录。
4.14.1 公开目录限制
Web 服务器的公开根目录应当指向:
WangStruct/public/
而不是:
WangStruct/
这样可以避免配置文件、源代码、运行日志、数据库备份和内部数据被直接访问。
4.14.2 运行目录权限
storage/ 应当由运行程序按照需要进行读写。
不应当给予所有系统用户无限制的读写权限。
日志、缓存和上传文件应根据实际访问要求分别设置权限。
4.14.3 配置与敏感信息保护
生产环境中的数据库凭据、接口密钥和其他敏感参数应当单独管理。
公开仓库中只保留示例配置,实际运行配置由部署环境提供。
4.14.4 升级时保护应用与数据
框架升级不应当覆盖应用目录、扩展目录和运行数据目录中的用户内容。
因此,部署和升级机制应当将框架源代码、应用程序、第三方扩展和运行数据作为不同的管理对象。
4.15 本章小结
WangStruct Framework 通过统一的项目目录结构,将框架核心、基础服务、功能组件、智能运行模块、应用程序、配置、公共资源、扩展程序、运行数据和测试程序进行独立组织。
本章明确了各目录的用途、主要文件职责、命名规则、程序加载关系和开发者扩展位置。
其中,framework/ 是框架本身的程序目录,applications/ 是应用开发目录,extensions/ 是第三方扩展目录,config/ 是配置目录,public/ 是公开入口和资源目录,storage/ 是运行数据目录,tests/ 是测试目录。
这些目录共同构成 WangStruct Framework 的参考工程结构。
后续开发将以本章的目录规范为基础,进一步确定核心类、公共接口、组件注册机制、自动加载程序和框架启动程序,使目录结构真正转化为能够运行的工程代码。
本章的目录结构属于参考实现设计,尚需在核心接口与启动程序确定后进行最终核对。 尤其是 PHP 参考实现的命名空间映射、组件加载顺序、应用注册方式和数据存储路径,必须通过实际代码实现和测试验证,不能仅凭目录设计认定其已经具备运行能力。
