2026年3月6日大约 3 分钟
一、项目整体定位与技术基线
- 项目名称：游鹄生态
- 核心框架：Laravel 12 + PHP 8
- 运行环境约束：【node.js22,imagick,redis,memcached,swoole,laravel-echo(websocket),supervisor,ES】
- 核心自研组件：
laravel-fast-api-youhujun：API 快速开发核心组件=>youhu-base微服务(开源)laravel-shard-map-youhujun：分库分表映射表组件=>shard-map微服务(开源)php-tool-youhujun：工具集（开源）youhu：游鹄生态核心=>youhu微服务(私有不开源)yohushop：游鹄生态电商=>youhushop微服务(私有不开源)xuehu-xueer-youhujun：雪鹄城堡专属AI交互组件=>xuehu微服务(私有不开源,提供私有AI模型训练,对话交互)
二、完整目录结构与职责说明
app/
├── Console/Commands/ # 自定义命令
│ ├── LaravelFastApi/V1/ # 基础组件包
│ ├── XueHu/V1/
├── Contracts/LaravelFastApi/V1/ # 契约
├── DTOs/ # 全局数据传输对象，与 Model 同步定义，全层通用
│ ├── Api/V1/ # 全局API微服务通信约束
│ ├── LaravelFastApi/V1/
│ ├── Traits
│ | ├── BaseDTOTrait
├── Events/ # 事件 对应listeners
│ ├── Admin/ # 通用后台事件
│ ├── Api/ # 通用微服务API通信事件
│ ├── Phone/ # 通用用户事件
│ ├── Common/V1/ # 通用公共事件
│ ├── LaravelFastApi/V1/
│ ├── LaravelShardMap/V1/
│ ├── YouHu/V1/
│ ├── YouHuShop/V1/
│ ├── XueHu/V1/
├── Exceptions/ # 自定义异常处理
│ ├── Admin/
│ │ ├── CommonException.php # 后台异常
│ ├── Api/
│ │ ├── CommonException.php # 微服务API通信异常
│ ├── Phone/
│ │ ├── CommonException.php # 用户异常
│ ├── Common/V1/
│ │ ├── CommonException.php # 通用(对接三方平台)
│ │ ├── RuleException.php # 自定义验证规则
├── Facades/ # 门面代理 对应Services/Facade
│ ├── Common/V1/ # 通用(业务处理)
│ ├── LaravelFastApi/V1/
│ ├── LaravelShardMap/V1/
│ ├── Pub/V1/ # 公共(三方对接,与业务无关)
│ ├── XueHu/V1/
│ ├── YouHu/V1/
│ ├── YouHuShop/V1/
├── Http/
│ ├── Controllers/ # 控制器
| | ├── LaravelFastApi/V1/
│ | ├── LaravelShardMap/V1/
│ | ├── XueHu/V1/
│ | ├── YouHu/V1/
│ | ├── YouHuShop/V1/
│ ├── Middleware # 中间件
| | ├── LaravelFastApi/V1/
│ | ├── LaravelShardMap/V1/
│ | ├── XueHu/V1/
│ | ├── YouHu/V1/
│ | ├── YouHuShop/V1/
│ └── Resources # api资源响应
| | ├── LaravelFastApi/V1/
│ | ├── LaravelShardMap/V1/
│ | ├── XueHu/V1/
│ | ├── YouHu/V1/
│ | ├── YouHuShop/V1/
├── Jobs/ # 队列(配置为redis)
| ├── LaravelFastApi/V1/
│ ├── LaravelShardMap/V1/
│ ├── XueHu/V1/
│ ├── YouHu/V1/
│ ├── YouHuShop/V1/
│ ├── Middleware/
│ | ├── RateLimited.php
├── Listeners/ # 事件监听 对应events
│ ├── Common/V1/模块/模块事件
│ | | | | ├── MS # 事件兼容单体和微服务的方式
│ ├── Admin/CommonEvent/CommonEventListener
│ ├── Api/CommonEvent/CommonEventListener
│ ├── Phone/CommonEvent/CommonEventListener
│ ├── LaravelFastApi/V1/
│ ├── YouHu/V1/
│ ├── YouHuShop/V1/
├── Models/ # 模型
│ ├── Builder/
│ | ├── ShardBuilder # 实现分库分表的分页
│ ├── LaravelFastApi/V1/
│ ├── LaravelShardMap/V1/
│ ├── Traits/
│ │ ├── Map/ # 包含同样的核心trait,专门给映射表使用
│ │ ├── WithCustomConnection.php # 模型连接:核心
│ │ ├── WithInviteCode.php # 型自动生成邀请码
│ │ ├── WithShardRouting.php # 分库分库路由:核心
│ │ ├── WithSnowflakeId.php # 雪花id处理:核心
│ │ ├── WithTimeStampFields.php # 自动处理日期时间
│ ├── YouHu/V1/
│ ├── XueHu/V1/
│ ├── YouHuShop/V1/
├── Notifications/ # 消息通知
│ ├── LaravelFastApi/V1/
│ ├── LaravelShardMap/V1/
│ ├── YouHu/V1/
│ ├── XueHu/V1/
│ ├── YouHuShop/V1/
├── Policies/ # 结合Gate配置policy处理粒度权限
│ ├── LaravelFastApi/V1/
│ ├── LaravelShardMap/V1/
│ ├── YouHu/V1/
│ ├── XueHu/V1/
│ ├── YouHuShop/V1/
├── Providers/ # 服务提供者
├── Rules/ # 自定义验证规则
│ ├── Common/ # 公共业务
│ ├── LaravelFastApi/V1/
│ ├── LaravelShardMap/V1/
│ ├── YouHu/V1/
│ ├── XueHu/V1/
│ ├── YouHuShop/V1/
│ ├── Pub/ # 与业务无关:核心
├── Services/ # 业务逻辑
│ ├── Contract/ # 对应契约业务逻辑
│ │ ├── LaravelFastApi/V1/
│ │ ├── YouHu/V1/
│ ├── Facade/ # 对应门面代理业务逻辑
│ │ ├── Common/V1/ # 通用业务
│ │ ├── LaravelFastApi/V1/
│ │ ├── XueHu/V1/
│ │ ├── YouHu/V1/
│ │ ├── YouHuShop/V1/
│ │ ├── Pub/V1/ # 公共一般是三方平台
│ │ ├── Traits/V1/
│ │ │ ├── AlwaysService.php # 对应树形分类查询trait
│ │ │ ├── QueryService.php # 对应列表查询trai
bootstrap/
├── app.php # 调度任务
├── providers.php # 注册应用服务提供者
config/
├── custom/ # 自定义配置:在各个组件包中定义而来
│ ├── common/ # 通用配置
│ │ ├── common.php
│ │ ├── admin/ # 定义通用后台错误码和事件码
│ │ ├── api/ # 注册微服务API通信的url
│ │ ├── code/ # 定义通用错误码
│ │ ├── event/ # 定义通用事件码
│ │ ├── rule/ # 定义通用异常
│ │ ├── phone/ # 定义通用用户错误码和事件码
│ ├── laravel-fast-api/ # 其他组件包也是照此配置
│ │ ├── admin/
│ │ │ ├── code/ # 自定义配置错误码结合Exception
│ │ │ ├── event/ # 自定义配置事件码结合Event
│ │ ├── phone/
│ │ │ ├── code/
│ │ │ ├── event/
│ │ ├── public/
│ │ │ ├── code/
│ │ │ ├── event/
│ │ │ ├── youhujun.php # 自定义组件包配置
│ ├── custom.php
cron/ # 结合调度任务存放sh脚本
database/ # 数据库
├── factories/ #数据工厂
├── seeders/ # 数据填充
│ ├── LaravelFastApi/ # 其他组件包同理
│ │ ├── LaravelFastApiSeeder.php # 组件包基础填充控制
│ ├── DatabaseSeeder.php # 生产环境执行
│ ├── DebugSeeder.php # 开发调试填充控制
│ ├── TruncateSeeder.php # 开发调试清空数据
routes/ # 路由定义
│ ├── api/
│ │ ├── laravel-fast-api/
│ │ ├── laravel-shard-map/
│ │ ├── xuehu/
│ │ ├── youhu/
│ │ ├── youhushop/
storage/logs/custom/ # plog自定义日志函数生成日志位置
stubs/ # 开发环境下自定义开发模版
vendor/
│ ├── youhujun/ # 游鹄生态组件包
│ │ ├── laravel-fast-api-youhujun/
│ │ ├── laravel-sahrd-map-youhujun/
│ │ ├── php-tool-youhujun/
│ │ ├── xuehu-xueer-youhujun/
│ │ ├── youhu/
│ │ ├── yohushop/