Download the PHP package api-swoole/sapi without Composer

赞助商

• 感谢JetBrains对本项目的支持！

(一).开始

1.1下载与安装

需要确保运行环境达到了以下的要求：

• PHP >= 7.4
• Swoole PHP 扩展 >= 4.5.2
• Redis PHP 扩展 （如需使用 Redis 客户端）
• PDO PHP 扩展 （如需使用 MySQL 客户端）

1.2通过 Composer 创建项目

1.3启动

支持 HTTP 服务、WebSocket 服务、tcp服务,项目根目录./apiswoole.php执行命令。

(二).Hello World

2.1编写一个接口

在api-swoole框架中，业务主要代码在app目录中。里面各个命名空间对应一个子目录，项目的默认命名空间是App，创建项目后app目录中包含Common、Example、Ext三个子目录，Common目录存放函数的functions.php文件，Ext一般放置工具等。目录结构如下：

当项目需要新增接口时，先在./app/Example目录中新建hello.php文件，并用编辑器编辑代码。

2.2定义路由

在route/http.php路由文件中定义项目路由，第一个参数为定义的浏览器访问地址，第二个参数@前半部分为文件的完整命名空间，@ 后半部分为在类中调用的具体方法。

2.3启动项目

在项目根目录下执行如下命令以非守护模式启动。

默认情况下监听本地的HTTP和websocket的9501端口，在cmd中出现如下输出信息表示项目启动成功。

2.4访问接口

在浏览器地址栏中输入定义的路由地址，地址组成http://ip网址:端口/定义的路由。

http://127.0.0.1:9501/hello

请求成功返回数据默认json方式返回，包含默认的code、msg、data字段，data中数据为方法中返回的数据。

(三).反向代理（Nginx + Swoole 配置）

由于 Http\Server 对 HTTP 协议的支持并不完整，建议仅作为应用服务器，用于处理动态请求，并且在前端增加 Nginx 作为代理。（参考地址）

可以通过读取 $request->header['x-real-ip'] 来获取客户端的真实 IP

(四).配置

4.1配置文件

默认config文件夹下包含conf.php、db.php、events.php三个文件，conf.php放置项目的配置信息，http、tcp、udp、websocket等配置。db.php负责配置MySQL、Redis连接，events.php负责定义定制特定事件注册监听，现支持workerStart、open、close、task、finish 事件注册 。可以通过DI()->config->get('conf.ws')或者\Sapi\Di::one()->config->get('conf.ws')方式读取配置信息。

4.2参数说明

4.3配置读取示例

项目启动时在apiswoole.php已经默认注册服务。

例如配置信息为conf.php,结构为：

可以使用DI()->config->get('conf.tcp')读取配置文件

返回数组数据结构：

(五).日志

根据PSR规范中详尽定义了日志接口，日志记录在./storage/log目录中，按照每日生成对应日期.log日志文件。目前支持以下几种日志记录：

• error： 系统异常类日记
• info： 业务纪录类日记
• debug： 开发调试类日记
• notice： 系统提示类日记
• waring： 系统致命类日记

日志系统使用：

./storage/log/20220906.log目录下对应日志：

(六).HTTP/websocket服务器(参考地址)

WebSocket\Server 继承自 Http\Server，所以 Http\Server 提供的所有 API 和配置项都可以使用。请参考 Http\Server 章节。

• 设置了 onRequest 回调，WebSocket\Server 也可以同时作为 HTTP 服务器
• 未设置 onRequest 回调，WebSocket\Server 收到 HTTP 请求后会返回 HTTP 400 错误页面

如若只想实现websocket服务器，则在./config/conf.php配置中删除['request', \Sapi\Events::class, 'onRequest']即可。

6.1HTTP/websocket服务器配置

HTTP/websocket服务器配置选项在./config/conf.php 中。具体配置信息可以参考Swoole文档配置选项。

6.2HTTP路由

HTTP 服务器的路由构建文件位于./route/http.php中。声明具体的路由规则，第一个参数为定义的浏览器访问地址，第二个参数@ 前半部分为文件的完整命名空间，@后半部分为在类中调用的具体方法。

完整的URL地址组成http://ip网址:端口/定义的路由。

构建基本路由只需要一个 URI 与一个 闭包，提供了一个非常简单定义路由的方法：

6.3HTTP控制器

对应的控制器方法默认有两个参数 $request 和 $reponse，关于 Request 和 Response 对象完整的介绍请查看 Swoole 文档：Http\Request 、 Http\Response

6.4接口参数规则

接口参数规则通过继承Api类实现，具体的定义规则通过rule()方法。

• 一维下标是接口类的方法名。
• 二维下标是接口参数名称。
• 三维下标
  1. name对应客户端传入的值
  2. require表示值传入可选项,true必须传入，false非必须传入。
  3. type传入类型，支持int、string、float、bool、array、file
  4. source参数传入位置，支持get、post、header
  5. message接口参数提示信息

6.5websocket路由

websocket服务器的路由定义文件位于./route/websocket.php 中。声明具体的路由规则，第一个参数为定义的浏览器访问地址，第二个参数@前半部分为文件的完整命名空间，@后半部分为在类中调用的具体方法。

完整的URL地址组成ws://ip网址:端口。

6.6websocket控制器

对应的控制器方法默认有两个参数 $server 和 $msg，关于 $server对象完整的介绍请查看 Swoole 文档：WebSocket\Server。 $msg 是客户端发送的数据信息。

补充：websocket客户端消息传入格式

客户端发送的数据信息，默认需以json格式传送，必须包含id、path、data三个字段。

• id字段消息体的唯一标识。
• path字段是./route/websocket.php路由声明的访问地址。
• data字段是项目的具体消息参数，控制方法默认的$msg。

控制器代码部分示例：

6.7websocket接口参数规则

接口参数规则通过继承Api类实现，具体的定义规则通过rule()方法。

• 一维下标是接口类的方法名。
• 二维下标是接口参数名称。
• 三维下标
  1. name对应客户端传入的值
  2. require表示值传入可选项,true必须传入，false非必须传入。
  3. type传入类型，支持int、string、float、bool、array
  4. message接口参数提示信息

6.8http勾子函数

Api类内置了钩子函数userCheck,HTTP控制器均可继承Api类重载。例如可完成用户身份验证。

首先定义声明HttpBase.php文件。

然后继承HttpBase.php实现类重载，。

6.9websocket勾子函数

Api类内置了钩子函数userWsCheck,websocket控制器均可继承Api类重载。例如可完成用户身份验证。

首先定义声明WsBase.php文件。

然后继承WsBase.php实现类重载，。

(七).TCP/UDP服务器

Server 可以监听多个端口，每个端口都可以设置不同的协议处理方式，例如 80 端口处理 HTTP 协议，9500 端口处理 TCP 协议,9502 端口处理 UDP 协议。SSL/TLS 传输加密也可以只对特定的端口启用。参考Swoole官方文档(多端口监听)

7.1TCP服务器配置

TCP服务器配置选项在./config/conf.php中增加tcp 字段。具体配置信息可以参考Swoole文档TCP配置。

7.1UDP服务器配置

UDP服务器配置选项在./config/conf.php中增加udp 字段。具体配置信息可以参考Swoole文档UDP配置。

(八).数据库

Swoole 开发组采用 Hook 原生 PHP 函数的方式实现协程客户端，通过一行代码就可以让原来的同步 IO 的代码变成可以协程调度的异步 IO，即一键协程化。Swoole 提供的 Swoole\Server 类簇 都是自动做好的，不需要手动做，参考 enable_coroutine 。具体内容可参考Swoole官网一键协程化

框架数据库引入simple-swoole第三方拓展包具体详情可参考simple-swoole/db

8.1Redis

配置

Redis服务器配置选项在./config/db.php中。

使用

项目中使用Redis

8.2MySQL

8.2.1配置

MySQL服务器配置选项在./config/db.php中。

./app/Ext/Pool.php配置连接池：

8.2.2Medoo

simple-swoole集成了轻量级的 PHP 数据库框架 Medoo ，使用时需要继承 Simps\DB\BaseModel，所以使用方法和 Medoo 基本一致，具体请查看 Medoo 的文档

唯一不同的是事务相关操作，在 Medoo 中是使用 action( $callback ) 方法，而在本框架中也可以使用 action( $callback ) 方法，另外也支持以下方法

事务示例

8.2.3使用

项目中使用，数据库表结构：

(九).addProcess

添加一个用户自定义的工作进程。此函数通常用于创建一个特殊的工作进程，用于监控、上报或者其他特殊的任务。具体内容可参考Swoole官网 addProcess

注意事项：

• 创建的子进程可以调用 $server 对象提供的各个方法，如 getClientList/getClientInfo/stats
• 在 Worker/Task 进程中可以调用 $process 提供的方法与子进程进行通信
• 在用户自定义进程中可以调用 $server->sendMessage 与 Worker/Task 进程通信
• 用户进程内不能使用 Server->task/taskwait 接口
• 用户进程内可以使用 Server->send/close 等接口
• 用户进程内应当进行 while(true)(如下边的示例) 或 EventLoop 循环 (例如创建个定时器) ，否则用户进程会不停地退出重启

使用示例

添加一个用户自定义的工作进程，在./config/conf.php中增加process配置，如下：

控制器示例：

(十).订制事件注册

框架已默认埋点workerStart、open、close、task、finish 五个订制事件注册。可根据具体的业务特征在对应的事件回调增加处理业务代码。./confg/events.php，每个事件允许有多个回调