跳至主要內容

项目熟悉篇

游鹄君2026年3月6日大约 7 分钟phpopensourcephplaravel-fast-api-youhujun

一、项目整体定位与技术基线

  1. 项目名称：游鹄生态
  2. 核心框架：Laravel 13 + PHP 8.3
  3. 运行环境约束：【node.js22,imagick,redis,memcached,swoole,laravel-echo(websocket),supervisor,ES】
  4. 核心自研组件：
    • laravel-fast-api-youhujun：API 快速开发核心组件=>youhu-base微服务(开源)
    • php-tool-youhujun：工具集（开源）
    • youhu：游鹄生态核心=>youhu微服务(私有不开源)
    • yohushop：游鹄生态电商=>youhushop微服务(私有不开源)
    • xuehu-xueer-youhujun：雪鹄城堡专属AI交互组件=>xuehu微服务(私有不开源,提供私有AI模型训练,对话交互)

二、完整目录结构与职责说明

app/
├── Console/Commands/                     # 自定义命令      
│   ├── LaravelFastApi/V1/                # 基础组件包
├── Contracts/LaravelFastApi/V1/          # 契约 
├── DTOs/                         		  # 全局数据传输对象，与 Model 同步定义，全层通用 
│   ├── Api/V1/                           # 全局API微服务通信约束
│   ├── LaravelFastApi/V1/
│   ├── Traits
│   |	├── BaseDTOTrait
├── Events/								  # 事件 对应listeners
│   ├── Admin/                            # 通用后台事件
│   ├── Api/                              # 通用微服务API通信事件
│   ├── Phone/                            # 通用用户事件
│   ├── Common/V1/                        # 通用公共事件
│   ├── LaravelFastApi/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/
│   ├── Pub/V1/                           # 公共(三方对接,与业务无关)
├── Http/                                 
│   ├── Controllers/                      # 控制器
│   |   ├── LaravelShardMap/V1/
│   ├── Middleware                        # 中间件
|   |   ├── LaravelFastApi/V1/
│   └── Resources                         # api资源响应
│   |   ├── LaravelShardMap/V1/
├── Jobs/                                 # 队列(配置为redis)
|   ├── Common/V1/
|   ├── LaravelFastApi/V1/
│   ├── Middleware/
│   |   ├── RateLimited.php 
├── Listeners/                            # 事件监听 对应events
│   ├── Common/V1/模块/模块事件
│   |   |      |  |   ├── MS              # 事件兼容单体和微服务的方式
│   ├── Admin/CommonEvent/CommonEventListener 
│   ├── Api/CommonEvent/CommonEventListener  
│   ├── Phone/CommonEvent/CommonEventListener                         
│   ├── LaravelFastApi/V1/
├── Models/                               # 模型
│   ├── Builder/  							  
│   |   ├── ShardBuilder				  # 实现分库分表
│   ├── LaravelFastApi/V1/
│   ├── LaravelShardMap/V1/
│   ├── Traits/  
│   │   ├── WithCustomConnection.php      # 模型连接:核心
│   │   ├── WithInviteCode.php            # 型自动生成邀请码
│   │   ├── WithShardRouting.php          # 分库分库路由:核心
│   │   ├── WithSnowflakeId.php           # 雪花id处理:核心
│   │   ├── WithTimeStampFields.php       # 自动处理日期时间
├── Notifications/                        # 消息通知
│   ├── LaravelFastApi/V1/
├── Policies/							  # 结合Gate配置policy处理粒度权限
│   ├── LaravelFastApi/V1/
├── Providers/                            # 服务提供者
├── Rules/  							  # 自定义验证规则
│   ├── Common/                           # 公共业务
│   ├── LaravelFastApi/V1/
│   ├── Pub/                              # 与业务无关:核心
├── Services/  							  # 业务逻辑
│   ├── Contract/                         # 对应契约业务逻辑
│   │   ├── LaravelFastApi/V1/
│   ├── Facade/                           # 对应门面代理业务逻辑
│   │   ├── Common/V1/                    # 通用业务
│   │   ├── LaravelFastApi/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/                         # 定义通用错误码
│   │   ├── es/                           # 定义es配置
│   │   ├── event/                        # 定义通用事件码
│   │   ├── rule/                         # 定义通用异常
│   │   ├── phone/                        # 定义通用用户错误码和事件码
│   │   ├── redis/                        # 定义redis配置
│   ├── 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/
storage/logs/custom/                      # plog自定义日志函数生成日志位置
stubs/                                    # 开发环境下自定义开发模版
extensions/                               # 加密扩展存放
vendor/
│   ├── youhujun/                         # 游鹄生态组件包
│   │   ├── laravel-fast-api-youhujun/
│   │   ├── php-tool-youhujun/

开发规范

全局命名规范

PascalCase（大驼峰）：类名、控制器名、模型名、DTO 名，首字母全大写
camelCase（小驼峰）：变量、方法、普通属性，一眼就知道是内存里的业务对象
snake_case（下划线）：数据库字段、表名、ES 字段，和数据源强绑定
UPPER_SNAKE_CASE（全大写下划线）：常量、配置项

1. 命名规范

1.1 变量命名

  • 模型对象命名：首字母小写最后跟随Object后缀,例如 $userObject,$userInfoObject
  • 集合命名: 首字母小写最后跟随Collection后缀,例如 $userCollection,$userInfoCollection
  • 枚举命名: 首字母小写最后跟随Enum后缀,例如 $userEnum,$userInfoEnum
  • 常量命名: 全部大写,单词间用下划线分隔,例如 USER_INFO_COLLECTION,USER_INFO_ENUM
  • 函数命名: 首字母小写后面大写,例如 getUserInfo,getAdminRole
  • 类命名: 首字母大写,单词间用大写字母分隔,例如 UserInfo,UserInfoCollection
  • 接口命名: 首字母大写,单词间用大写字母分隔,例如 IUserInfo,IUserInfoCollection
  • 配置文件命名: 全部小写,单词间用下划线分隔,例如 user_info.php,user_info_collection.php
  • 数据库字段命名: 全部小写,单词间用下划线分隔,例如 user_uid,user_info_id

1.2 函数命名

  • 全局函数: 首字母小写,单词间用下划线分隔,例如 get_user_info,get_admin_role采用snake_case命名

  • 类方法: 首字母小写,单词间用驼峰命名,例如 getUserInfo,getAdminRole采用camelCase命名

批量处理数据

示例代码如下:
重点是使用cursor()方法,避免一次性加载所有数据到内存中,导致内存溢出.
注意示例UserInfo的处理,目的是一次查询多个UserInfo,而不是一次查询一个UserInfo.

$startTime = microtime(true);
$total = 0;
$indexName = config('common_es.indices.user.users');

User::queryByAllShard()
->select(['user_uid', 'account_status', 'invite_code', 'real_auth_status', 'level_id','account_name','phone','created_at', 'updated_at','deleted_at'])
->cursor()
->chunk(config('common.chunk_size.es_sync'))
->each(function ($chunk) use (&$total, $indexName) {
	$userCollection = $chunk;
	// 1. 先批量获取这批用户的所有ID
	$userUidArray = $chunk->pluck('user_uid')->toArray();

	// 2. 批量查询UserInfo（这里需要根据实际的UserInfo模型调整）
	// 假设UserInfo也有分片路由，需要按user_uid查询
	$userInfoCollection = UserInfo::queryByAllShard()
		->whereIn('user_uid', $userUidArray)
		->get()
		->keyBy('user_uid');
	$esDataArray = $userCollection->map(function ($userObject) use ($userInfoCollection) {
		$userInfoObject = $userInfoCollection->get($userObject->user_uid);

		return [
			'_id' => $userObject->user_uid,
			'user_uid' => $userObject->user_uid,
			'phone' => $userObject->phone,
			'account_name' => $userObject->account_name,
			'account_status' => $userObject->account_status,
			'invite_code' => $userObject->invite_code,
			'real_auth_status' => $userObject->real_auth_status,
			'level_id' => $userObject->level_id,
			'created_at' => $userObject->created_at?->toDateTimeString(),
			'updated_at' => $userObject->updated_at?->toDateTimeString(),
			'deleted_at' => $userObject->deleted_at?->toDateTimeString(),
			//userInfo
			'id_number' => $userInfoObject->id_number,
			'nick_name' => $userInfoObject->nick_name,
			'real_name' => $userInfoObject->real_name,
			'solar_birthday_at' => $userInfoObject->solar_birthday_at,
			'chinese_birthday_at' => $userInfoObject->chinese_birthday_at,
			'sex' => $userInfoObject->sex,
			'introduction' => $userInfoObject->introduction,
			// 'avatar'=>$userInfoObject->avatar,
			// 'ablum_uid'=>$userInfoObject->ablum_uid,
			// 'qrcode'=>$userInfoObject->qrcode,

		];
	})->toArray();

	//p($esDataArray);

	//$result = EsFacade::batchActDoc($indexName, $esData);
	// 统计处理总数
	$total += count($esDataArray);
});

$endTime = microtime(true);
$costTime = round($endTime - $startTime, 2);

DTO说明

1.为了项目的可维护性，我们需要对DTO进行统一管理.项目外接收参数统一用DTO对参数类型进行限定和校验.
2.业务内部参数定义流转,使用业务DTO传递,避免使用数组带来的混乱,提升项目可维护性.

项目功能

配套前后端完整项目，可联动部署使用：

vue3-element-admin-youhujun 后台管理端

uniappx-youhujun 移动端

|--系统设置
|--个人中心
|--|--菜单管理(树形)
|--|--平台配置
|--|--|--缓存配置
|--|--系统配置
|--|--|--参数配置
|--|--|--提示配置
|--|--|--三方平台配置
|--|--角色管理(权限分配)
|--|--地区管理(树形)
|--|--银行管理

|--业务设置
|--|--通用设置
|--|--|--结合设置
|--|--分类管理
|--|--|--产品分类(树形)
|--|--|--文章分类(树形)
|--|--|--标签管理(树形)
|--|--级别管理
|--|--|--级别条件
|--|--|--用户级别
|--|--业务平台
|--|--|--首页轮播

|--用户管理
|--|--管理员管理
|--|--用户管理
|--|--|--用户列表
|--|--|--等待认证

|--文章管理
|--|--公告管理
|--|--系统文章

|--图片空间
|--|--我的相册

|--日志管理
|--|--登录日志
|--|--|--手机登录
|--|--|--后台登录
|--|--事件日志
|--|--|--手机事件
|--|--|--后台事件

接口文档

提示

接口文档使用apipost生成,可以直接调试.

文档地址-https://docs.apipost.net/docs/64bfef32ac88000?locale=zh-cn

组件包发布以后在Documents目录下有一个laravel-fast-api-youhujun.json的文件,可以直接在apipost新建项目导入

ApiPost官网-https://www.apipost.cn

商业授权须知

本项目永久开源，个人学习、技术测试、非商业用途可自由使用，无任何费用。

任何组织或个人，禁止未经授权直接将本项目用于商业生产、盈利运营、对外交付。

商业授权方案：

  1. 一次性支付 100 万元人民币：获得终身商业使用权，由作者本人签发授权凭证，并提供核心代码加密解密支持。
  2. 年付订阅费 5 万元人民币：仅在订约有效期内提供技术支持和服务。
  3. 创业公司年付订阅费 2 万元人民币：创业优惠期最多三年，仅在订约有效期内提供技术支持和服务。

未经授权擅自商用，视为侵权，作者保留追究一切法律责任的权利。
商务洽谈、技术合作、授权申请唯一联系方式：

微信：youhujun88
邮箱：youhu8888@163.com

游鹄君的博客
Copyright © 2026 游鹄君