基礎開始示例
demo 地址
基礎開發示例已經開源,源碼地址:https://github.com/XueSiLf/demo-3.7.x
注意事項,請先看完這里,再往下繼續瀏覽。因為下面的 demo
中使用到了 php8
的注解特性,所以您需要先學習注解如何使用,可查看 php
官方文檔的 注解 文檔。如果您已經對注解用法非常熟悉了,可直接往下繼續瀏覽。
安裝
框架安裝
Linux(Centos/Ubuntu/MacOS) 下安裝
- 我們先把當前的
php
環境安裝好swoole
拓展,安裝swoole 擴展
步驟可查看 安裝 Swoole 章節,然后執行php --ri swoole
確保可以看到swoole
拓展版本為4.8.13
- 建立一個目錄,名為
Test
,執行composer require easyswoole/easyswoole=3.7.x
引入easyswoole
- 執行
php vendor/bin/easyswoole.php install
進行安裝,然后輸入Y
、Y
Docker 下安裝
docker run --name easyswoole \
-v /tmp/easyswoole:/var/www \
-p 9501:9501 -it \
--privileged -u root \
--entrypoint /bin/sh \
easyswoolexuesi2021/easyswoole:php8.1.22-alpine3.16-swoole4.8.13
cd /var/www
mkdir Test
cd Test
composer require easyswoole/easyswoole=3.7.x
php vendor/bin/easyswoole.php install # 然后輸入 `Y`、`Y`
組件引入
// 引入 IDE 代碼提示組件
composer require swoole/ide-helper
命名空間注冊
編輯 Test
根目錄下的 composer.json
文件,如果自動加載中沒有 App
命名空間,請在 autoload.psr-4
中加入 "App\\": "App/"
,然后執行 composer dumpautoload -o
進行名稱空間的更新。composer.json
文件大體結構如下:
{
"require": {
"easyswoole/easyswoole": "3.7.x",
"swoole/ide-helper": "^5.1"
},
"autoload": {
"psr-4": {
"App\\": "App/"
}
}
}
安裝后目錄結構
Test 項目部署目錄
├─App 應用目錄
│ ├─HttpController 控制器目錄(如果沒有,請自行創建)
├─Log 日志文件目錄(啟動后創建)
├─Temp 臨時文件目錄(啟動后創建)
├─vendor 第三方類庫目錄
├─bootstrap.php 框架 bootstrap 事件
├─composer.json Composer 架構
├─composer.lock Composer 鎖定
├─EasySwooleEvent.php 框架全局事件
├─easyswoole.php 框架管理腳本
├─dev.php 開發配置文件
├─produce.php 生產配置文件
連接池實現
配置項
創建配置文件 Test/Config/DATABASE.php
,加入以下配置信息,注意:請根據自己的 mysql
服務器信息填寫賬戶密碼。
<?php
/**
* This file is part of EasySwoole.
*
* @link http://www.fe88.cn
* @document http://www.fe88.cn
* @contact http://www.fe88.cn/Preface/contact.html
* @license https://github.com/easy-swoole/easyswoole/blob/3.x/LICENSE
*/
declare(strict_types=1);
return [
'DATABASE' => [
// 添加 MySQL 及對應的連接池配置
/*################ MYSQL CONFIG ##################*/
'MYSQL' => [
[
'name' => 'default', // 數據庫連接池名稱
'useMysqli' => false, // 是否是使用php-mysqli擴展
'host' => '127.0.0.1', // 數據庫地址
'port' => 3306, // 數據庫端口
'user' => 'easyswoole', // 數據庫用戶名
'password' => 'easyswoole', // 數據庫用戶密碼
'timeout' => 45, // 數據庫連接超時時間
'charset' => 'utf8', // 數據庫字符編碼
'database' => 'easyswoole_demo', // 數據庫名
'autoPing' => 5, // 自動 ping 客戶端鏈接的間隔
'strict_type' => false, // 不開啟嚴格模式
'fetch_mode' => false,
'returnCollection' => false, // 設置返回結果為 數組
// 配置 數據庫 連接池配置,配置詳細說明請看連接池組件 http://www.fe88.cn/Components/Pool/introduction.html
'intervalCheckTime' => 15 * 1000, // 設置 連接池定時器執行頻率
'maxIdleTime' => 10, // 設置 連接池對象最大閑置時間 (秒)
'maxObjectNum' => 20, // 設置 連接池最大數量
'minObjectNum' => 5, // 設置 連接池最小數量
'getObjectTimeout' => 3.0, // 設置 獲取連接池的超時時間
'loadAverageTime' => 0.001, // 設置負載閾值
]
]
]
];
修改 Test/EasySwooleEvent.php
文件,在 initialize
方法中添加如下內容,加載配置文件,
<?php
/**
* This file is part of EasySwoole.
*
* @link http://www.fe88.cn
* @document http://www.fe88.cn
* @contact http://www.fe88.cn/Preface/contact.html
* @license https://github.com/easy-swoole/easyswoole/blob/3.x/LICENSE
*/
namespace EasySwoole\EasySwoole;
use EasySwoole\EasySwoole\AbstractInterface\Event;
class EasySwooleEvent implements Event
{
public static function initialize()
{
date_default_timezone_set('Asia/Shanghai');
// 加載配置文件
Config::getInstance()->loadDir(EASYSWOOLE_ROOT . '/Config');
}
// ...
}
進行如上配置之后,我們需要在 MySQL
服務端創建一個名為 easyswoole_demo
的數據庫,選擇字符串編碼為 utf8mb4
,字符排序規則為 utf8mb4_general_ci
。
引入數據庫連接池組件 FastDb
執行以下命令用于實現數據庫連接池組件 FastDb 庫的引入。
composer require easyswoole/fast-db=2.x
注冊數據庫連接池
編輯 Test
項目根目錄下的 EasySwooleEvent.php
文件,在 initialize
或 mainServerCreate
事件函數中進行 FastDb
的連接池的注冊,內容如下:
<?php
namespace EasySwoole\EasySwoole;
use EasySwoole\EasySwoole\AbstractInterface\Event;
use EasySwoole\EasySwoole\Swoole\EventRegister;
use EasySwoole\FastDb\FastDb;
class EasySwooleEvent implements Event
{
public static function initialize()
{
date_default_timezone_set('Asia/Shanghai');
// 加載配置文件
Config::getInstance()->loadDir(EASYSWOOLE_ROOT . '/Config');
###### 注冊 mysql orm 連接池 ######
$mysqlConfigs = Config::getInstance()->getConf('DATABASE.MYSQL');
foreach ($mysqlConfigs as $mysqlConfig) {
$configObj = new \EasySwoole\FastDb\Config($mysqlConfig);
// 【可選操作】我們已經在 DATABASE.php 中進行了配置
# $configObj->setMaxObjectNum(20); // 配置連接池最大數量
FastDb::getInstance()->addDb($configObj);
}
}
public static function mainServerCreate(EventRegister $register)
{
// 或者 在此函數中注冊 和上面等價
###### 注冊 mysql orm 連接池 ######
// $mysqlConfigs = Config::getInstance()->getConf('DATABASE.MYSQL');
// foreach ($mysqlConfigs as $mysqlConfig) {
// $configObj = new \EasySwoole\FastDb\Config($mysqlConfig);
// 【可選操作】我們已經在 DATABASE.php 中進行了配置
# $configObj->setMaxObjectNum(20); // 配置連接池最大數量
// FastDb::getInstance()->addDb($configObj);
// }
}
}
在 initialize
事件中注冊數據庫連接池,使用這個 $config
可同時配置連接池大小等。
具體查看 FastDb 組件章節 的使用。
模型定義
管理員模型
新增管理員用戶表
在 easyswoole_demo
數據庫中執行如下 sql
腳本,創建管理員用戶表 admin_list
。
DROP TABLE IF EXISTS `admin_list`;
CREATE TABLE `admin_list` (
`adminId` int NOT NULL AUTO_INCREMENT,
`adminName` varchar(15) CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci DEFAULT NULL,
`adminAccount` varchar(18) CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci DEFAULT NULL,
`adminPassword` varchar(32) CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci DEFAULT NULL,
`adminSession` varchar(32) CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci DEFAULT NULL,
`adminLastLoginTime` int DEFAULT NULL,
`adminLastLoginIp` varchar(20) CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci DEFAULT NULL,
PRIMARY KEY (`adminId`) USING BTREE,
UNIQUE KEY `adminAccount` (`adminAccount`) USING BTREE,
KEY `adminSession` (`adminSession`) USING BTREE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
INSERT INTO `admin_list` VALUES (1, 'EasySwoole', 'easyswoole', 'e10adc3949ba59abbe56e057f20f883e', '', 1700891404, '127.0.0.1');
新增 model 文件
新建 App/Model/Admin/AdminModel.php
文件,編輯內容如下:
<?php
/**
* This file is part of EasySwoole.
*
* @link http://www.fe88.cn
* @document http://www.fe88.cn
* @contact http://www.fe88.cn/Preface/contact.html
* @license https://github.com/easy-swoole/easyswoole/blob/3.x/LICENSE
*/
declare(strict_types=1);
namespace App\Model\Admin;
use App\Model\BaseModel;
use EasySwoole\FastDb\Attributes\Property;
use EasySwoole\FastDb\Beans\Query;
/**
* Class AdminModel
*
* @property int $adminId
* @property string $adminName
* @property string $adminAccount
* @property string $adminPassword
* @property string $adminSession
* @property int $adminLastLoginTime
* @property string $adminLastLoginIp
*/
class AdminModel extends BaseModel
{
#[Property(isPrimaryKey: true)]
public int $adminId;
#[Property]
public string $adminName;
#[Property]
public string $adminAccount;
#[Property]
public string $adminPassword;
#[Property]
public string $adminSession;
#[Property]
public int $adminLastLoginTime;
#[Property]
public string $adminLastLoginIp;
protected string $primaryKey = 'adminId';
protected string $table = 'admin_list';
/**
* @getAll
*
* @param int $page
* @param null|string $keyword
* @param int $pageSize
*
* @return array[$total, $list]
*/
public function getAll(int $page = 1, ?string $keyword = null, int $pageSize = 10): array
{
$where = [];
if (!empty($keyword)) {
$where['adminAccount'] = ['%' . $keyword . '%', 'like'];
}
$this->queryLimit()->page($page, true, $pageSize)
->orderBy($this->primaryKey, 'DESC');
/** \EasySwoole\FastDb\Beans\ListResult $resultList */
$resultList = $this->where($where)->all();
$total = $resultList->totalCount();
$list = $resultList->list();
return ['total' => $total, 'list' => $list];
}
/**
* 登錄成功后請返回更新后的bean
*/
public function login(): ?AdminModel
{
$where = [
'adminAccount' => $this->adminAccount,
'adminPassword' => $this->adminPassword
];
return self::findRecord($where);
}
/**
* 以account進行查詢
*/
public function accountExist(array $field = ['*']): ?AdminModel
{
return self::findRecord(function (Query $query) use ($field) {
$query->fields($field)
->where('adminAccount', $this->adminAccount);
});
}
public function getOneBySession(array $field = ['*']): ?AdminModel
{
$this->queryLimit()->fields($field);
$this->where(['adminSession' => $this->adminSession]);
return $this->find();
}
public function logout()
{
$where = [$this->primaryKey => $this->adminId];
$update = ['adminSession' => ''];
return self::fastUpdate($where, $update);
}
}
針對上述類似 : ?AdminModel
,不懂這種函數返回值類型聲明的同學,請查看 函數返回值類型聲明,屬于 PHP 7
的新特性。
關于 Model
的定義可查看 FastDb 模型定義章節。
關于 IDE
自動提示,只要你在類上面注釋中加上 @property $adminId
,IDE
就可以自動提示類的這個屬性。
普通用戶模型
普通用戶模型和管理員模型同理。
建表
在數據庫中執行如下 sql
腳本,創建普通用戶表 user_list
。
DROP TABLE IF EXISTS `user_list`;
CREATE TABLE `user_list` (
`userId` int NOT NULL AUTO_INCREMENT,
`userName` varchar(32) CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci NOT NULL,
`userAccount` varchar(18) CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci NOT NULL,
`userPassword` varchar(32) CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci NOT NULL,
`phone` varchar(18) CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci NOT NULL,
`addTime` int unsigned DEFAULT '0',
`lastLoginIp` varchar(20) CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci DEFAULT NULL,
`lastLoginTime` int unsigned DEFAULT '0',
`userSession` varchar(32) CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci DEFAULT NULL,
`state` tinyint unsigned DEFAULT '0',
`money` int unsigned NOT NULL DEFAULT '0' COMMENT '用戶余額',
`frozenMoney` int unsigned NOT NULL DEFAULT '0' COMMENT '凍結余額',
PRIMARY KEY (`userId`) USING BTREE,
UNIQUE KEY `pk_userAccount` (`userAccount`) USING BTREE,
KEY `userSession` (`userSession`) USING BTREE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
INSERT INTO `user_list` VALUES (1, 'easyswoole', 'easyswoole', 'e10adc3949ba59abbe56e057f20f883e', '18888888888', 0, '127.0.0.1', 1700892578, '', 0, 0, 0);
新增 model 文件
新建 App/Model/User/UserModel.php
文件,編輯內容如下:
<?php
/**
* This file is part of EasySwoole.
*
* @link http://www.fe88.cn
* @document http://www.fe88.cn
* @contact http://www.fe88.cn/Preface/contact.html
* @license https://github.com/easy-swoole/easyswoole/blob/3.x/LICENSE
*/
declare(strict_types=1);
namespace App\Model\User;
use App\Model\BaseModel;
use EasySwoole\FastDb\Attributes\Property;
/**
* Class UserModel
*
* @property int $userId
* @property string $userName
* @property string $userAccount
* @property string $userPassword
* @property string $phone
* @property int $addTime
* @property string $lastLoginIp
* @property int $lastLoginTime
* @property string $userSession
* @property int $state
* @property int $money
* @property int $frozenMoney
*/
class UserModel extends BaseModel
{
protected string $table = 'user_list';
protected string $primaryKey = 'userId';
public const STATE_PROHIBIT = 0; // 禁用狀態
public const STATE_NORMAL = 1; // 正常狀態
#[Property(isPrimaryKey: true)]
public int $userId;
#[Property]
public string $userName;
#[Property]
public string $userAccount;
#[Property]
public string $userPassword;
#[Property]
public string $phone;
#[Property]
public int $addTime;
#[Property]
public ?string $lastLoginIp;
#[Property]
public ?int $lastLoginTime;
#[Property]
public ?string $userSession;
#[Property]
public int $state;
#[Property]
public int $money;
#[Property]
public int $frozenMoney;
/**
* @getAll
*
* @param int $page
* @param string|null $keyword
* @param int $pageSize
*
* @return array[total,list]
*/
public function getAll(int $page = 1, ?string $keyword = null, int $pageSize = 10): array
{
$where = [];
if (!empty($keyword)) {
$where['userAccount'] = ['%' . $keyword . '%', 'like'];
}
$this->queryLimit()->page($page, withTotalCount: true, pageSize: $pageSize)
->orderBy($this->primaryKey, 'DESC');
/** \EasySwoole\FastDb\Beans\ListResult $resultList */
$resultList = $this
->where($where)
->all();
$total = $resultList->totalCount();
$list = $resultList->list();
return ['total' => $total, 'list' => $list];
}
public function getOneByPhone(array $field = ['*']): ?UserModel
{
$this->queryLimit()->fields($field);
return $this->find(['phone' => $this->phone]);
}
/*
* 登錄成功后請返回更新后的bean
*/
public function login(): ?UserModel
{
return $this->find([
'userAccount' => $this->userAccount,
'userPassword' => $this->userPassword
]);
}
public function getOneBySession(array $field = ['*']): ?UserModel
{
$this->queryLimit()->fields($field);
return $this->find(['userSession' => $this->userSession]);
}
public function logout()
{
return $this->where([$this->primaryKey => $this->userId])->updateWithLimit(['userSession' => '']);
}
}
banner 模型
建表
在數據中執行如下 sql
腳本,創建 banner
表 banner_list
。
DROP TABLE IF EXISTS `banner_list`;
CREATE TABLE `banner_list` (
`bannerId` int NOT NULL AUTO_INCREMENT,
`bannerName` varchar(32) CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci DEFAULT NULL,
`bannerImg` varchar(255) CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci NOT NULL COMMENT 'banner圖片',
`bannerDescription` varchar(255) CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci DEFAULT NULL,
`bannerUrl` varchar(255) CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci DEFAULT NULL COMMENT '跳轉地址',
`state` tinyint DEFAULT NULL COMMENT '狀態0隱藏 1正常',
PRIMARY KEY (`bannerId`) USING BTREE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
INSERT INTO `banner_list` VALUES (1, '測試banner', 'asdadsasdasd.jpg', '測試的banner數據', 'www.fe88.cn', 1);
新增 model 文件
新建 App/Model/Admin/BannerModel.php
文件,編輯內容如下:
<?php
/**
* This file is part of EasySwoole.
*
* @link http://www.fe88.cn
* @document http://www.fe88.cn
* @contact http://www.fe88.cn/Preface/contact.html
* @license https://github.com/easy-swoole/easyswoole/blob/3.x/LICENSE
*/
declare(strict_types=1);
namespace App\Model\Admin;
use App\Model\BaseModel;
use EasySwoole\FastDb\Attributes\Property;
/**
* Class BannerModel
*
* @property int $bannerId
* @property string $bannerName
* @property string $bannerImg
* @property string $bannerDescription
* @property string $bannerUrl
* @property int $state
*/
class BannerModel extends BaseModel
{
protected string $table = 'banner_list';
protected string $primaryKey = 'bannerId';
#[Property(isPrimaryKey: true)]
public int $bannerId;
#[Property]
public string $bannerName;
#[Property]
public string $bannerImg;
#[Property]
public string $bannerDescription;
#[Property]
public string $bannerUrl;
#[Property]
public int $state;
public function getAll(int $page = 1, int $state = 1, ?string $keyword = null, int $pageSize = 10): array
{
$where = [];
if (!empty($keyword)) {
$where['bannerUrl'] = ['%' . $keyword . '%', 'like'];
}
$where['state'] = $state;
$this->queryLimit()->page($page, withTotalCount: true, pageSize: $pageSize)
->orderBy($this->primaryKey, 'DESC');
/** \EasySwoole\FastDb\Beans\ListResult $resultList */
$listResult = $this->where($where)->all();
$total = $listResult->totalCount();
$list = $listResult->list();
return ['total' => $total, 'list' => $list];
}
}
控制器定義
全局基礎控制器定義
新建 App/Httpcontroller/Base.php
文件,編輯內容如下:
<?php
/**
* This file is part of EasySwoole.
*
* @link http://www.fe88.cn
* @document http://www.fe88.cn
* @contact http://www.fe88.cn/Preface/contact.html
* @license https://github.com/easy-swoole/easyswoole/blob/3.x/LICENSE
*/
declare(strict_types=1);
namespace App\HttpController;
use EasySwoole\EasySwoole\ServerManager;
use EasySwoole\HttpAnnotation\AnnotationController;
class Base extends AnnotationController
{
public function index(): void
{
$this->actionNotFound('index');
}
/**
* 獲取用戶的真實IP
*
* @param string $headerName 代理服務器傳遞的標頭名稱
*
* @return string|null
*/
protected function clientRealIP(string $headerName = 'x-real-ip'): ?string
{
$server = ServerManager::getInstance()->getSwooleServer();
$client = $server->getClientInfo($this->request()->getSwooleRequest()->fd);
$clientAddress = $client['remote_ip'];
$xri = $this->request()->getHeaderLine($headerName);
$xff = $this->request()->getHeaderLine('x-forwarded-for');
if ($clientAddress === '127.0.0.1') {
if (!empty($xri)) { // 如果有 xri 則判定為前端有 NGINX 等代理
$clientAddress = $xri;
} elseif (!empty($xff)) { // 如果不存在 xri 則繼續判斷 xff
$clientAddress = $xff;
}
}
return $clientAddress;
}
protected function input(string $name, mixed $default = null)
{
$value = $this->request()->getRequestParam($name);
return $value ?? $default;
}
}
上述新增的基礎控制器 (Base.php) 里面的方法用于獲取用戶 ip
,以及獲取 api
參數。
上述新增的基礎控制器 (Base.php) 繼承了 \EasySwoole\HttpAnnotation\AnnotationController
,這個是注解支持控制器,具體使用可查看 注解控制器章節
api 基礎控制器定義
新建 App/Httpcontroller/Api/ApiBase.php
文件,編輯內容如下:
<?php
/**
* This file is part of EasySwoole.
*
* @link http://www.fe88.cn
* @document http://www.fe88.cn
* @contact http://www.fe88.cn/Preface/contact.html
* @license https://github.com/easy-swoole/easyswoole/blob/3.x/LICENSE
*/
declare(strict_types=1);
namespace App\HttpController\Api;
use App\HttpController\Base;
use EasySwoole\EasySwoole\Core;
use EasySwoole\EasySwoole\Trigger;
use EasySwoole\Http\Message\Status;
use EasySwoole\HttpAnnotation\Exception\ValidateFail;
abstract class ApiBase extends Base
{
public function index(): void
{
$this->actionNotFound('index');
}
protected function actionNotFound(?string $action): void
{
$this->writeJson(Status::CODE_NOT_FOUND);
}
public function onRequest(?string $action): ?bool
{
if (!parent::onRequest($action)) {
return false;
}
return true;
}
protected function onException(\Throwable $throwable): void
{
if ($throwable instanceof ValidateFail) {
$this->writeJson(400, null, $throwable->getMessage());
} else {
if (Core::getInstance()->runMode() === 'dev') {
$this->writeJson(500, null, $throwable->getMessage());
} else {
Trigger::getInstance()->throwable($throwable);
$this->writeJson(500, null, '系統內部錯誤,請稍后重試');
}
}
}
}
上述 api
基類控制器 (ApiBase.php),用于攔截注解異常,以及 api
異常時給用戶返回一個 json
格式錯誤信息。
公共基礎控制器定義
新建 App/Httpcontroller/Api/Common/CommonBase.php
文件,編輯內容如下:
<?php
/**
* This file is part of EasySwoole.
*
* @link http://www.fe88.cn
* @document http://www.fe88.cn
* @contact http://www.fe88.cn/Preface/contact.html
* @license https://github.com/easy-swoole/easyswoole/blob/3.x/LICENSE
*/
declare(strict_types=1);
namespace App\HttpController\Api\Common;
use App\HttpController\Api\ApiBase;
class CommonBase extends ApiBase
{
}
公共控制器
公共控制器放不需要登錄即可查看的控制器,例如 banner
列表查看:
新增 App/HttpController/Api/Common/Banner.php
文件,編輯內容如下:
<?php
/**
* This file is part of EasySwoole.
*
* @link http://www.fe88.cn
* @document http://www.fe88.cn
* @contact http://www.fe88.cn/Preface/contact.html
* @license https://github.com/easy-swoole/easyswoole/blob/3.x/LICENSE
*/
declare(strict_types=1);
namespace App\HttpController\Api\Common;
use App\Model\Admin\BannerModel;
use EasySwoole\Http\Message\Status;
use EasySwoole\HttpAnnotation\Attributes\Api;
use EasySwoole\HttpAnnotation\Attributes\Description;
use EasySwoole\HttpAnnotation\Attributes\Param;
use EasySwoole\HttpAnnotation\Enum\HttpMethod;
use EasySwoole\HttpAnnotation\Enum\ParamFrom;
use EasySwoole\HttpAnnotation\Validator\Integer;
use EasySwoole\HttpAnnotation\Validator\MaxLength;
use EasySwoole\HttpAnnotation\Validator\Optional;
use EasySwoole\HttpAnnotation\Validator\Required;
class Banner extends CommonBase
{
#[Api(
apiName: 'bannerGetOne',
allowMethod: HttpMethod::GET,
requestPath: '/api/common/banner/getOne',
requestParam: [
new Param(name: 'bannerId', from: ParamFrom::GET, validate: [
new Required(),
new Integer(),
], description: new Description('主鍵id')),
],
description: 'getOne'
)]
/**
* Author: XueSi <hui.huang8540@gmail.com>
* Time: 00:20
*/
public function getOne()
{
$param = $this->request()->getRequestParam();
$model = new BannerModel();
$bean = $model->find((int)$param['bannerId']);
if ($bean) {
$this->writeJson(Status::CODE_OK, $bean, 'success');
} else {
$this->writeJson(Status::CODE_BAD_REQUEST, [], 'fail');
}
}
#[Api(
apiName: 'bannerGetAll',
allowMethod: HttpMethod::GET,
requestPath: '/api/common/banner/getAll',
requestParam: [
new Param(name: 'page', from: ParamFrom::GET, validate: [
new Optional(),
new Integer(),
], description: new Description('頁數')),
new Param(name: 'limit', from: ParamFrom::GET, validate: [
new Optional(),
new Integer(),
], description: new Description('每頁總數')),
new Param(name: 'keyword', from: ParamFrom::GET, validate: [
new Optional(),
new MaxLength(32),
], description: new Description('關鍵字')),
],
description: 'getAll'
)]
/**
* Author: XueSi <hui.huang8540@gmail.com>
* Time: 00:20
*/
public function getAll()
{
$param = $this->request()->getRequestParam();
$page = (int)$this->input('page', 1);
$limit = (int)$this->input('limit', 20);
$model = new BannerModel();
$data = $model->getAll($page, 1, $param['keyword'] ?? null, $limit);
$this->writeJson(Status::CODE_OK, $data, 'success');
}
}
注意:可以看到,在上文 getAll
方法中,有個特殊的寫法 requestParam: [new Param(name: 'page', from: ParamFrom::GET, validate: [new Optional(), new Integer(),], description: new Description('頁數')),
這是 php8
支持的注解寫法,類似 Java
語言的注解,當使用這個注解之后,將會約束 page
參數必須是 int
,具體的驗證機制可查看 validate
驗證器 章節。框架中如何使用注解請查看 注解控制器章節
使用 php easyswoole.php server start
命令啟動框架服務之后,訪問鏈接:http://localhost:9501/api/common/banner/getAll
(示例訪問地址) 即可看到如下結果:{"code":200,"result":{"total":1,"list":[{"bannerId":1,"bannerName":"測試banner","bannerImg":"asdadsasdasd.jpg","bannerDescription":"測試的banner數據","bannerUrl":"www.fe88.cn","state":1}]},"msg":"success"}
(需要有數據才能看到具體輸出)。
管理員基礎控制器定義
新建 App/HttpController/Api/Admin/AdminBase.php
文件,編輯內容如下:
<?php
/**
* This file is part of EasySwoole.
*
* @link http://www.fe88.cn
* @document http://www.fe88.cn
* @contact http://www.fe88.cn/Preface/contact.html
* @license https://github.com/easy-swoole/easyswoole/blob/3.x/LICENSE
*/
declare(strict_types=1);
namespace App\HttpController\Api\Admin;
use App\Model\Admin\AdminModel;
use App\HttpController\Api\ApiBase;
use EasySwoole\Http\Message\Status;
class AdminBase extends ApiBase
{
// public 才會根據協程清除
public ?AdminModel $who;
// session 的 cookie頭
protected string $sessionKey = 'adminSession';
// 白名單
protected array $whiteList = [];
/**
* Author: XueSi <hui.huang8540@gmail.com>
* Time: 00:28
*/
public function onRequest(?string $action): ?bool
{
if (parent::onRequest($action)) {
// 白名單判斷
if (in_array($action, $this->whiteList)) {
return true;
}
// 獲取登錄信息
if (!$this->getWho()) {
$this->writeJson(Status::CODE_UNAUTHORIZED, '', '登錄已過期');
return false;
}
return true;
}
return false;
}
/**
* Author: XueSi <hui.huang8540@gmail.com>
* Time: 00:28
*/
protected function getWho(): ?AdminModel
{
if (isset($this->who) && $this->who instanceof AdminModel) {
return $this->who;
}
$sessionKey = $this->request()->getRequestParam($this->sessionKey);
if (empty($sessionKey)) {
$sessionKey = $this->request()->getCookieParams($this->sessionKey);
}
if (empty($sessionKey)) {
return null;
}
$adminModel = new AdminModel();
$adminModel->adminSession = $sessionKey;
$this->who = $adminModel->getOneBySession();
return $this->who;
}
}
管理員登錄控制器
新建 App/HttpController/Api/Admin/Auth.php
文件,編輯內容如下:
<?php
/**
* This file is part of EasySwoole.
*
* @link http://www.fe88.cn
* @document http://www.fe88.cn
* @contact http://www.fe88.cn/Preface/contact.html
* @license https://github.com/easy-swoole/easyswoole/blob/3.x/LICENSE
*/
declare(strict_types=1);
namespace App\HttpController\Api\Admin;
use App\Model\Admin\AdminModel;
use EasySwoole\FastDb\Exception\RuntimeError;
use EasySwoole\Http\Message\Status;
use EasySwoole\HttpAnnotation\Attributes\Api;
use EasySwoole\HttpAnnotation\Attributes\Description;
use EasySwoole\HttpAnnotation\Attributes\Param;
use EasySwoole\HttpAnnotation\Enum\HttpMethod;
use EasySwoole\HttpAnnotation\Enum\ParamFrom;
use EasySwoole\HttpAnnotation\Exception\Annotation;
use EasySwoole\HttpAnnotation\Validator\MaxLength;
use EasySwoole\HttpAnnotation\Validator\MinLength;
use EasySwoole\HttpAnnotation\Validator\Required;
class Auth extends AdminBase
{
protected array $whiteList = ['login'];
/**
* @return void
* @throws RuntimeError
* @throws Annotation
*/
#[Api(
apiName: 'login',
allowMethod: HttpMethod::GET,
requestPath: '/api/admin/auth/login',
requestParam: [
new Param(name: 'account', from: ParamFrom::GET, validate: [
new Required(),
new MaxLength(20)
], description: new Description('帳號')),
new Param(name: 'password', from: ParamFrom::GET, validate: [
new Required(),
new MinLength(6),
new MaxLength(16),
], description: new Description('密碼')),
],
description: '登陸,參數驗證注解寫法'
)]
/**
* Author: XueSi <hui.huang8540@gmail.com>
* Time: 00:31
*/
public function login()
{
$param = $this->request()->getRequestParam();
$model = new AdminModel();
$model->adminAccount = $param['account'];
$model->adminPassword = md5($param['password']);
if ($user = $model->login()) {
$sessionHash = md5(time() . $user->adminId);
$user->updateWithLimit([
'adminLastLoginTime' => time(),
'adminLastLoginIp' => $this->clientRealIP(),
'adminSession' => $sessionHash
]);
$rs = $user->toArray();
unset($rs['adminPassword']);
$rs['adminSession'] = $sessionHash;
$this->response()->setCookie('adminSession', $sessionHash, time() + 3600, '/');
$this->writeJson(Status::CODE_OK, $rs, 'success');
} else {
$this->writeJson(Status::CODE_BAD_REQUEST, '', '密碼錯誤');
}
}
#[Api(
apiName: 'logout',
allowMethod: HttpMethod::GET,
requestPath: '/api/admin/auth/logout',
requestParam: [
new Param(name: 'adminSession', from: ParamFrom::COOKIE, validate: [
new Required(),
], description: new Description('帳號')),
],
description: '退出登錄,參數注解寫法'
)]
/**
* Author: XueSi <hui.huang8540@gmail.com>
* Time: 00:32
*
* @throws Annotation
*/
public function logout()
{
$sessionKey = $this->request()->getRequestParam($this->sessionKey);
if (empty($sessionKey)) {
$sessionKey = $this->request()->getCookieParams('adminSession');
}
if (empty($sessionKey)) {
$this->writeJson(Status::CODE_UNAUTHORIZED, '', '尚未登錄');
return false;
}
$result = $this->getWho()->logout();
if ($result) {
$this->writeJson(Status::CODE_OK, '', '退出登錄成功');
} else {
$this->writeJson(Status::CODE_UNAUTHORIZED, '', 'fail');
}
}
#[Api(
apiName: 'getInfo',
allowMethod: HttpMethod::GET,
requestPath: '/api/admin/auth/getInfo',
description: '獲取管理員信息'
)]
/**
* Author: XueSi <hui.huang8540@gmail.com>
* Time: 00:34
*/
public function getInfo()
{
$this->writeJson(200, $this->getWho()->toArray(), 'success');
}
}
使用 php easyswoole.php server start
命令啟動框架服務之后,訪問鏈接:http://localhost:9501/api/admin/auth/login?account=easyswoole&password=123456
(示例訪問地址) 即可返回如下結果:``
{
"code": 200,
"result": {
"adminId": 1,
"adminName": "EasySwoole",
"adminAccount": "easyswoole",
"adminSession": "7262e8188ae9885e27e092538c08ca16",
"adminLastLoginTime": 1706271125,
"adminLastLoginIp": "127.0.0.1"
},
"msg": "success"
}
管理員用戶管理控制器
新增 App/httpController/Api/Admin/User.php
文件,編輯內容如下:
<?php
/**
* This file is part of EasySwoole.
*
* @link http://www.fe88.cn
* @document http://www.fe88.cn
* @contact http://www.fe88.cn/Preface/contact.html
* @license https://github.com/easy-swoole/easyswoole/blob/3.x/LICENSE
*/
declare(strict_types=1);
namespace App\HttpController\Api\Admin;
use App\Model\User\UserModel;
use EasySwoole\Http\Message\Status;
use EasySwoole\HttpAnnotation\Attributes\Api;
use EasySwoole\HttpAnnotation\Attributes\Description;
use EasySwoole\HttpAnnotation\Attributes\Param;
use EasySwoole\HttpAnnotation\Enum\HttpMethod;
use EasySwoole\HttpAnnotation\Enum\ParamFrom;
use EasySwoole\HttpAnnotation\Validator\InArray;
use EasySwoole\HttpAnnotation\Validator\Integer;
use EasySwoole\HttpAnnotation\Validator\IsPhoneNumber;
use EasySwoole\HttpAnnotation\Validator\MaxLength;
use EasySwoole\HttpAnnotation\Validator\MinLength;
use EasySwoole\HttpAnnotation\Validator\Optional;
use EasySwoole\HttpAnnotation\Validator\Required;
class User extends AdminBase
{
#[Api(
apiName: 'userGetAll',
allowMethod: HttpMethod::GET,
requestPath: '/api/admin/user/getAll',
requestParam: [
new Param(name: 'page', from: ParamFrom::GET, validate: [
new Optional(),
new Integer(),
], description: new Description('頁數')),
new Param(name: 'limit', from: ParamFrom::GET, validate: [
new Optional(),
new Integer(),
], description: new Description('每頁總數')),
new Param(name: 'keyword', from: ParamFrom::GET, validate: [
new Optional(),
new MaxLength(32),
], description: new Description('關鍵字')),
],
description: 'getAll'
)]
/**
* Author: XueSi <hui.huang8540@gmail.com>
* Time: 00:38
*/
public function getAll()
{
$page = (int)$this->input('page', 1);
$limit = (int)$this->input('limit', 20);
$model = new UserModel();
$data = $model->getAll($page, $this->input('keyword'), $limit);
$this->writeJson(Status::CODE_OK, $data, 'success');
}
#[Api(
apiName: 'userGetOne',
allowMethod: HttpMethod::GET,
requestPath: '/api/admin/user/getOne',
requestParam: [
new Param(name: 'userId', from: ParamFrom::GET, validate: [
new Required(),
new Integer(),
], description: new Description('戶id')),
],
description: 'getAll'
)]
/**
* Author: XueSi <hui.huang8540@gmail.com>
* Time: 00:40
*/
public function getOne()
{
$param = $this->request()->getRequestParam();
$model = new UserModel();
$rs = $model->find((int)$param['userId']);
if ($rs) {
$this->writeJson(Status::CODE_OK, $rs, 'success');
} else {
$this->writeJson(Status::CODE_BAD_REQUEST, [], 'fail');
}
}
#[Api(
apiName: 'addUser',
allowMethod: HttpMethod::GET,
requestPath: '/api/admin/user/add',
requestParam: [
new Param(name: 'userName', from: ParamFrom::GET, validate: [
new Optional(),
new MaxLength(32),
], description: new Description('用戶昵稱')),
new Param(name: 'userAccount', from: ParamFrom::GET, validate: [
new Required(),
new MaxLength(32),
], description: new Description('用戶名')),
new Param(name: 'userPassword', from: ParamFrom::GET, validate: [
new Required(),
new MinLength(6),
new MaxLength(18),
], description: new Description('用戶密碼')),
new Param(name: 'phone', from: ParamFrom::GET, validate: [
new Optional(),
new IsPhoneNumber(),
], description: new Description('手機號碼')),
new Param(name: 'state', from: ParamFrom::GET, validate: [
new Optional(),
new InArray([0, 1]),
], description: new Description('用戶狀態')),
],
description: 'add'
)]
/**
* Author: XueSi <hui.huang8540@gmail.com>
* Time: 00:44
*/
public function add()
{
$param = $this->request()->getRequestParam();
$model = new UserModel($param);
$model->userPassword = md5($param['userPassword']);
$rs = $model->insert();
if ($rs) {
$this->writeJson(Status::CODE_OK, $rs, 'success');
} else {
$this->writeJson(Status::CODE_BAD_REQUEST, [], 'add fail');
}
}
#[Api(
apiName: 'updateUser',
allowMethod: HttpMethod::GET,
requestPath: '/api/admin/user/update',
requestParam: [
new Param(name: 'userId', from: ParamFrom::GET, validate: [
new Required(),
new Integer(),
], description: new Description('用戶id')),
new Param(name: 'userPassword', from: ParamFrom::GET, validate: [
new Optional(),
new MinLength(6),
new MaxLength(18),
], description: new Description('會員密碼')),
new Param(name: 'userName', from: ParamFrom::GET, validate: [
new Optional(),
new MaxLength(32),
], description: new Description('會員名')),
new Param(name: 'state', from: ParamFrom::GET, validate: [
new Optional(),
new InArray([0, 1]),
], description: new Description('狀態')),
new Param(name: 'phone', from: ParamFrom::GET, validate: [
new Optional(),
new IsPhoneNumber(),
], description: new Description('手機號')),
],
description: 'update'
)]
/**
* Author: XueSi <hui.huang8540@gmail.com>
* Time: 00:50
*/
public function update()
{
$model = new UserModel();
$userId = $this->input('userId');
/**
* @var $userInfo UserModel
*/
$userInfo = $model->find((int)$userId);
if (!$userInfo) {
$this->writeJson(Status::CODE_BAD_REQUEST, [], '未找到該會員');
return false;
}
$password = $this->input('userPassword');
$update = [
'userName' => $this->input('userName', $userInfo->userName),
'userPassword' => $password ? md5($password) : $userInfo->userPassword,
'state' => $this->input('state', $userInfo->state),
'phone' => $this->input('phone', $userInfo->phone),
];
$rs = $userInfo->updateWithLimit($update);
if ($rs === 0 || $rs === 1) {
$this->writeJson(Status::CODE_OK, $rs, 'success');
} else {
$this->writeJson(Status::CODE_BAD_REQUEST, [], 'update fail');
}
}
#[Api(
apiName: 'deleteUser',
allowMethod: HttpMethod::GET,
requestPath: '/api/admin/user/delete',
requestParam: [
new Param(name: 'userId', from: ParamFrom::GET, validate: [
new Required(),
new Integer(),
], description: new Description('用戶id')),
],
description: 'delete'
)]
/**
* Author: XueSi <hui.huang8540@gmail.com>
* Time: 00:55
*/
public function delete()
{
$param = $this->request()->getRequestParam();
$model = new UserModel(['userId' => $param['userId']]);
$rs = $model->delete();
if ($rs) {
$this->writeJson(Status::CODE_OK, $rs, 'success');
} else {
$this->writeJson(Status::CODE_BAD_REQUEST, [], '刪除失敗');
}
}
}
后臺管理員登錄之后,可通過此文件的接口,去進行會員的增刪改查操作 (即 CURD)。
請求地址為:(示例訪問地址) http://127.0.0.1:9501/Api/Admin/User/getAll
(等方法)
普通用戶基礎控制器定義
新增 App/HttpController/Api/User/UserBase.php
文件,編輯內容如下:
<?php
/**
* This file is part of EasySwoole.
*
* @link http://www.fe88.cn
* @document http://www.fe88.cn
* @contact http://www.fe88.cn/Preface/contact.html
* @license https://github.com/easy-swoole/easyswoole/blob/3.x/LICENSE
*/
declare(strict_types=1);
namespace App\HttpController\Api\User;
use App\Model\User\UserModel;
use App\HttpController\Api\ApiBase;
use EasySwoole\Http\Message\Status;
class UserBase extends ApiBase
{
protected ?UserModel $who;
// session 的 cookie 頭
protected string $sessionKey = 'userSession';
// 白名單
protected array $whiteList = ['login', 'register'];
public function onRequest(?string $action): ?bool
{
if (parent::onRequest($action)) {
// 白名單判斷
if (in_array($action, $this->whiteList)) {
return true;
}
// 獲取登錄信息
if (!$data = $this->getWho()) {
$this->writeJson(Status::CODE_UNAUTHORIZED, '', '登錄已過期');
return false;
}
// 刷新 cookie 存活
$this->response()->setCookie($this->sessionKey, $data->userSession, time() + 3600, '/');
return true;
}
return false;
}
public function getWho(): ?UserModel
{
if (isset($this->who) && $this->who instanceof UserModel) {
return $this->who;
}
$sessionKey = $this->request()->getRequestParam($this->sessionKey);
if (empty($sessionKey)) {
$sessionKey = $this->request()->getCookieParams($this->sessionKey);
}
if (empty($sessionKey)) {
return null;
}
$userModel = new UserModel();
$userModel->userSession = $sessionKey;
$this->who = $userModel->getOneBySession();
return $this->who;
}
}
普通用戶登錄控制器
新增 App/HttpController/Api/User/Auth.php
文件,編輯內容如下:
<?php
/**
* This file is part of EasySwoole.
*
* @link http://www.fe88.cn
* @document http://www.fe88.cn
* @contact http://www.fe88.cn/Preface/contact.html
* @license https://github.com/easy-swoole/easyswoole/blob/3.x/LICENSE
*/
declare(strict_types=1);
namespace App\HttpController\Api\User;
use App\Model\User\UserModel;
use EasySwoole\Http\Message\Status;
use EasySwoole\HttpAnnotation\Attributes\Api;
use EasySwoole\HttpAnnotation\Attributes\Description;
use EasySwoole\HttpAnnotation\Attributes\Param;
use EasySwoole\HttpAnnotation\Enum\HttpMethod;
use EasySwoole\HttpAnnotation\Enum\ParamFrom;
use EasySwoole\HttpAnnotation\Validator\MaxLength;
use EasySwoole\HttpAnnotation\Validator\MinLength;
use EasySwoole\HttpAnnotation\Validator\Optional;
use EasySwoole\HttpAnnotation\Validator\Required;
class Auth extends UserBase
{
protected array $whiteList = ['login'];
#[Api(
apiName: 'login',
allowMethod: HttpMethod::GET,
requestPath: '/api/user/auth/login',
requestParam: [
new Param(name: 'userAccount', from: ParamFrom::GET, validate: [
new Required(),
new MaxLength(32)
], description: new Description('用戶名')),
new Param(name: 'userPassword', from: ParamFrom::GET, validate: [
new Required(),
new MinLength(6),
new MaxLength(18),
], description: new Description('密碼')),
],
description: 'login'
)]
/**
* Author: XueSi <hui.huang8540@gmail.com>
* Time: 00:31
*/
public function login()
{
$param = $this->request()->getRequestParam();
$model = new UserModel();
$model->userAccount = $param['userAccount'];
$model->userPassword = md5($param['userPassword']);
if ($userInfo = $model->login()) {
$sessionHash = md5(time() . $userInfo->userId);
$userInfo->updateWithLimit([
'lastLoginIp' => $this->clientRealIP(),
'lastLoginTime' => time(),
'userSession' => $sessionHash
]);
$rs = $userInfo->toArray();
unset($rs['userPassword']);
$rs['userSession'] = $sessionHash;
$this->response()->setCookie('userSession', $sessionHash, time() + 3600, '/');
$this->writeJson(Status::CODE_OK, $rs);
} else {
$this->writeJson(Status::CODE_BAD_REQUEST, '', '密碼錯誤');
}
}
#[Api(
apiName: 'logout',
allowMethod: HttpMethod::GET,
requestPath: '/api/user/auth/logout',
requestParam: [
new Param(name: 'userSession', from: ParamFrom::GET, validate: [
new Optional(),
], description: new Description('用戶會話')),
],
description: 'logout'
)]
/**
* Author: XueSi <hui.huang8540@gmail.com>
* Time: 01:07
*/
public function logout()
{
$sessionKey = $this->request()->getRequestParam('userSession');
if (empty($sessionKey)) {
$sessionKey = $this->request()->getCookieParams('userSession');
}
if (empty($sessionKey)) {
$this->writeJson(Status::CODE_UNAUTHORIZED, '', '尚未登錄');
return false;
}
$result = $this->getWho()->logout();
if ($result) {
$this->writeJson(Status::CODE_OK, '', '退出登錄成功');
} else {
$this->writeJson(Status::CODE_UNAUTHORIZED, '', 'fail');
}
}
#[Api(
apiName: 'getInfo',
allowMethod: HttpMethod::GET,
requestPath: '/api/user/auth/getInfo',
description: 'getInfo'
)]
/**
* Author: XueSi <hui.huang8540@gmail.com>
* Time: 01:10
*/
public function getInfo()
{
$this->writeJson(200, $this->getWho(), 'success');
}
}
訪問 http://localhost:9501/api/user/auth/login?userAccount=easyswoole&userPassword=456789
即可登錄成功。
接口訪問
上述 demo
中的所有接口均使用 GET
請求,可以在啟動 easyswoole
服務后可使用瀏覽器訪問如下 URL
進行體驗:
# Admin 管理員模塊
## auth 模塊
- login 登錄
- http://localhost:9501/api/admin/auth/login?account=easyswoole&password=123456
- logout
- http://localhost:9501/api/admin/auth/logout
- getInfo
- http://localhost:9501/api/admin/auth/getInfo
## user manager 會員管理模塊
- get all user
- http://localhost:9501/api/admin/user/getAll
- http://localhost:9501/api/admin/user/getAll?page=1&limit=2
- http://localhost:9501/api/admin/user/getAll?keyword=easyswoole
- get one user
- http://localhost:9501/api/admin/user/getOne?userId=1
- add user
- http://localhost:9501/api/admin/user/add?userName=EasySwoole1&userAccount=easyswoole1&userPassword=123456
- update user
- http://localhost:9501/api/admin/user/update?userId=1&userPassword=456789&userName=easyswoole&state=0&phone=18888888889
- delete user
- http://localhost:9501/api/admin/user/delete?userId=2
# Common 公共模塊
## banner 模塊
- get one banner 讀取一條banner
- http://localhost:9501/api/common/banner/getOne?bannerId=1
- get all banner
- http://localhost:9501/api/common/banner/getAll
- http://localhost:9501/api/common/banner/getAll?page=1&limit=2
- http://localhost:9501/api/common/banner/getAll?keyword=easyswoole
# User 會員模塊
- user login
- http://localhost:9501/api/user/auth/login?userAccount=easyswoole&userPassword=456789
- get user info
- http://localhost:9501/api/user/auth/getInfo
- logout
- http://localhost:9501/api/user/auth/logout