欢迎您访问程序员文章站本站旨在为大家提供分享程序员计算机编程知识！
您现在的位置是： 首页  >  IT编程

PhalApi 2.7 开发快速上手

程序员文章站 2023-12-29 12:36:16
PhalApi是一款国人制作的PHP纯后端框架。它的开发相当简单，同时也具备文档生成等特色功能。下面，我通过简单的几点，让你可以快速入门使用该框架的开发。 建议使用PHPStorm作为IDE，代码提示相当完全。由于PHP的热更新特性，修改过的PHP文件保存后立即生效，无需编译，无需重启服务器。 什么 ......

phalapi是一款国人制作的php纯后端框架。它的开发相当简单，同时也具备文档生成等特色功能。下面，我通过简单的几点，让你可以快速入门使用该框架的开发。
建议使用phpstorm作为ide，代码提示相当完全。由于php的热更新特性，修改过的php文件保存后立即生效，无需编译，无需重启服务器。

什么是phalapi

phalapi是一个轻量级的php接口框架。有别于传统的框架，它只面向后端接口的开发。
官网：https://www.phalapi.net
官方文档：http://docs.phalapi.net/#/v2.0/

安装phalapi

composer是php的包管理器（类似于java的maven、node的npm）。
composer的安装请参考https://pkg.phpcomposer.com/#how-to-install-composer，不要在英文官网直接下载安装包。
composer安装后请立即切换到国内源https://developer.aliyun.com/composer。
phar是php界的jar包，可以像jar包一样引入即用。
在项目目录下执行composer create-project phalapi/phalapi即可创建phalapi项目，项目路径为./phalapi。
若需要安装阿里云oss的sdk，则在项目路径下（注意cd到phalapi目录）按https://help.aliyun.com/document_detail/85580.html说明调用composer。

composer require aliyuncs/oss-sdk-php
composer install

phalapi提供了再封装的phalapi-oss阿里云oss包（https://github.com/vivlong/phalapi-aliyun-oss），也可以考虑使用

本地调试环境配置

建议使用傻瓜式一体化软件xampp搭建本地的调试环境。
修改xampp中apache的配置文件，找到这两行：

documentroot "x:/xampp/htdocs"
<directory "x:/xampp/htdocs">

将引号内目录修改到phalapi项目的public目录，注意使用左斜杠替换右斜杠、
修改后启动apache，则项目在localhost:80上启动。如需修改端口请参考apache配置文件的其他配置项。

更优雅的接口地址

默认的接口网址为类似于http://xxx.com/?s=app.user.login（?s后为接口全限定名），不够美观。开启uri路由匹配后可以实现http://xxx.com/user/login的接口路径，比较美观。（app字段可以省略）
开启方式：

  1. 在./config/sys.php修改enable_uri_match配置为true
  2. 撰写服务器rewrite规则。若使用nginx服务器，请直接参考官方文档示例（http://docs.phalapi.net/#/v2.0/how-to-request?id=开启uri路由匹配）。
    若使用apache服务器：
    • 在./public目录下新建规则文件.htaccess

    • 写入下列内容（即将所有404请求转发到index.php，作为一个controller）

      rewriteengine on
rewritecond %{request_filename} !-f
rewritecond %{request_filename} !-d
rewriterule ^(.*)$ index.php

    • 重启apache服务器

phalapi的adm三层模型

有别于软件开发领域常用的mvc三层模型，在后端纯接口开发中，view层显然没有任何意义。所以phalapi采用了创新的adm三层模型。

  • a - api接口层，只负责接受请求、调度domain层、发送响应
  • d - domain领域层，最关键，负责业务逻辑的处理
  • m - model数据层，只负责与数据库的交互。注意，它不仅描述object的基本信息，还要实现一些与会与数据库交互的方法。类似于javaee中的bean定义+dao层
    PhalApi 2.7 开发快速上手

api接口

三层模型所有的代码均在./src/app目录下。api、domain、model目录下默认生成了一些demo，可以删除。
在api目录下新建php类，假设为myclass.php。注意下列要求：

  • namespace app\api; - 命名空间。注意，必须限定到myclass.php所在目录。即如果myclass.php放在./src/app/api/mobile下，则namespace app\api\mobile。
  • use phalapi\api; - 要求使用api类。
  • class myclass extends api - 所有类都要继承自api类。
    在类中定义的一系列public的函数，就是一个个实际的接口（注意，不是类是接口，而是类的成员函数是接口！所以这个类是起到了接口分类的作用）
    接口的返回格式永远是json，形式为 {ret, data, msg}，其中ret是http状态码，msg是错误提示信息，而data就是我们的业务数据。在函数中return的关联数组会自动转化成json，注入data。例如
    PhalApi 2.7 开发快速上手
    下面介绍接口的调用网址，假设函数名为hello，类文件为myclass.php
myclass路径 接口url
./src/app/api/myclass.php xxx.com/myclass/hello
./src/app/api/mobile/myclass.php （正确）xxx.com/mobile_myclass/hello
./src/app/api/mobile/myclass.php （错误）xxx.com/mobile/myclass/hello

即若类文件在api目录下发生了层叠，则需要加入下划线分隔，而不是一直用斜杠。
下面介绍如何在api层获取和处理请求参数。

  • 重写public function getrules()方法，

    public function getrules() {
  return array(
    '[function name]' => array(
    '[param name]' => array('name' => '...', 'require' => ..., 'type' => '...', 'source' => '...', 'desc' => '...', 'min' => ..., 'max' => ...)
  );
}

    返回一个关联数组，键为该api类下的函数名称（即接口），值又是一个关联数组，键为参数名，值又是一个关联数组，用于进行该参数的配置，具体配置项可参考http://docs.phalapi.net/#/v2.0/api-params。下面介绍几个常用的：

    • name：string，前端请求时用的参数名
    • require：boolean，是否必须
    • type：参数类型，可以用string、int等
    • source：string, 参数源，可以用post、get（注意小写）等
    • desc：参数说明，该说明会出现在自动文档中
    • min和max（均可选）：当type是int时，可以起到后端参数校验的作用

  • 在接口对应函数的代码中取参数：

$param_var = $this->[param name]

取好参数，发给domain层的对应函数，获取返回值，发送响应给服务器端。这就是api层做的事。
一般来说，需要在头部use一下app\domain下的对应的domain，然后在需要时new一个domain对象来使用。

model模型

在model目录下新建php类，假设为user.php。通常的开发习惯是，数据库一张表对应一个model类，这样可以实现对表的描述（类似于mybatis与pojo的配合）。以mysql为例，注意下列要求：

  • namespace app\model; - 同样要严格限定到user.php目录
  • use phalapi\model\notormmodel as notorm; - 要求使用notorm类。notorm是phalapi内部的封装的mysql交互引擎
  • class user extends notorm - 模型类必须继承notorm
  • protected function gettablename($id) { 
    return 'user_score';
}
    重写protected function gettablename($id)方法（注意函数签名带参$id），返回值是该模型对应的表名。
    现在即可在user类下编写各个curd功能的函数，函数参数是进行sql查询需要参数。具体使用请参考官方文档http://docs.phalapi.net/#/v2.0/database-usage。整体风格是链式调用，例如：
    PhalApi 2.7 开发快速上手

首先要通过$this->getorm()获取notorm实例，然后组织相关sql关键字即可。
值得一提的是，notorm的功能非常的强大（起到了sql语句builder的作用，极大地避免了直接组织sql语句），它甚至可以接收关联数组为参数进行各种智能的insert、update等操作。具体使用请参考http://docs.phalapi.net/#/v2.0/database-usage，靠这里的一两句话是说不清道不明的。
如果有需要，notorm也支持执行原生sql语句。

domain领域

在domian领域下新建php类，假设为user.php。对于domain类，要求比较简单：

  • namespace app\domain\; - 你懂的
  • 没了。

domain类不要求use框架内部的类，也不要求定义的类继承相关类。
在user类下写相关业务函数即可。一般来说，此处函数的参数是api层请求需要的所有参数。
在业务函数中，调用model层中封装好的有关curd函数，完成业务逻辑。一般来说，需要在user.php头部use一下app\model下的对应的user的model，在进行curd操作时，new一个model对象来使用。

全局配置文件

在./config目录下的app.php、dbs.php、di.php、sys.php就是四大全局配置文件。
如何在./src中脚本的任意位置取出其中配置的键值对？phalapi用了依赖注入（di）和反射的功能，实现了看起来非常java的方式来获取。
例如在app.php中配置了如下内容：

'token' => array( 'salt' => 'imsalt', 'expire' => 7200)

要取盐值，则取法为\phalapi\di()->config->get('app.token.salt')。

即对于这四大配置文件，均用\phalapi\di()->config->get来访问，参数为配置项的全限定名。

这四大配置文件的作用是：

  • app.php - 用户自定义的相关配置均追加于此
  • dbs.php - 数据库相关配置
  • di.php - 依赖注入相关配置，当有新组件插入时需要修改
  • sys.php - 系统级配置，例如是否调试、uri匹配等

全局功能函数

如何定义一个在./src中任何位置都可以调用的功能函数？把这个函数的实现写在./src/functions.php中即可。在需要调用时，使用\app\[function name]来调用。

自动接口文档

不同于swagger的高侵入性，phalapi的自动接口文档系统非常的简单优雅。不仅方便前端阅读，还具备自解释性，利于后续后端的维护。和javadoc类似，它全部依靠多行注释完成。并且，多行注释内允许使用基本的html标签，如<b></b>来加粗等等。

注意，合法的多行注释格式如下，首行有两个星号。

/**
 *
 */

这样使用：

  • 在api层的每个类文件的use \phalapi\api;下行进行注释，用于说明该类的整体作用

  • 在getrules函数内进行的相关参数配置会自动反映到接口文档中

  • 在接口对应函数的正上方进行注释，用于说明该接口的作用。语法如下：

    PhalApi 2.7 开发快速上手

    • 第一行写接口名称
    • @desc后写接口描述（description）
    • @return后写接口返回值描述，@return [type] [name] [description]
    • 如果不想要该接口被自动文档扫描，则添加@ignore

若一切配置无误，则可以在http://xxx.com/docs.php阅读到自动生成的接口文档。

PhalApi 2.7 开发快速上手

接口文档网页还可以进行定制：

  • 修改./public/docs.php中的$projectname，可以修改左上角logo处的标题。
  • 如果需要公共说明（如图中的统一说明），则在./public/docs.php末尾添加php脚本闭标签（?>）后，可以书写html代码。由于该页面布局的原因，不建议将公共说明写在头部。

前端请求方式

  • 对于php后端，前端在发送post请求前必须设置如下请求头，否则后端收不到数据：

header: {'content-type': "application/x-www-form-urlencoded; charset=utf-8"}

​ get请求没有类似限制。

  • 前端用axios来post时，data为object，无需stringify

  • 前端收到的响应作res.data后即为如下结构的object:

{
    "ret": 200,
    "data": {
        ...
    },
    "msg": ""
}

​ ret为http状态码，msg为错误提示信息（当状态码非200时才有），data为业务数据

  • 在自动接口文档中，形如app.x_y.z的接口请求地址为http://xxx.com/x_y/z（如果配置了uri匹配）

开发实例

我们以一个简单的接口为例（获取表中分数最高的n个记录），展示一下phalapi下一个接口的开发过程
PhalApi 2.7 开发快速上手

  1. 这是一个公共接口，用于手机端。故在./src/app/api/mobile下新建php类文件other.php

  2. 进行namespace、use的基本配置，让other类继承api。编写类文件注释用于生成文档。注意此处use...as...别名的使用。
    PhalApi 2.7 开发快速上手

  3. 重写getrules方法，接受一个参数n，函数名是gettopn
    PhalApi 2.7 开发快速上手

  4. 写gettopn函数以及相关文档注释。注意，接口函数都不需要参数，而是在内部获取。
    PhalApi 2.7 开发快速上手

  5. 开始开发domain层。在./src/app/domain/mobile下新建php类文件other.php

  6. 进行namespace的配置，写业务逻辑代码（当n>5时视为n=5处理）。可以看到返回的是一个响应体。所以在api层是直接return的。注意此处同样使用了别名use \app\model\mobile\other as modelother;

    PhalApi 2.7 开发快速上手

  7. 显然该业务需要与数据库交互，所以需要开发model层。在./src/app/model/mobile下新建php类文件other.php

  8. 进行namespace和use配置，other类继承notorm类。重写gettablename($id)方法

  9. 实现gettopn($n)方法。注意，此处sql查询的结果会自动转为关联数组传到domain层，domain层再向上传到api层，api层响应时关联数组就自动变成json结构注入到响应体的data中了，多么美妙！

    PhalApi 2.7 开发快速上手

  10. 至此，一个接口开发完成。相应的文档也已经自动生成了。

系统日志

phalapi提供了一个简单日志系统。它将日志等级分类三级：error、info、debug。

保存目录：./runtime/log

调用方式：\phalapi\di()->logger->error/info/debug([日志内容], [上下文描述（可选）])

mysql数据库

mysql数据库需要在./config/dbs.php内配置。

phalapi支持实现多库集群、分库分表。具体请参考：

  • http://docs.phalapi.net/#/v2.0/database-connect
  • http://docs.phalapi.net/#/v2.0/database-multi
  • http://docs.phalapi.net/#/v2.0/database-other

服务端请求curl

如果有需要在服务器端利用服务器发送http请求（例如小程序开发中的code2session），phalapi为我们封装了curl库来实现，非常简单。参考http://docs.phalapi.net/#/v2.0/curl。

缓存体系

phalapi支持许多种缓存。
PhalApi 2.7 开发快速上手

此处用常用的redis说明。

  • 在./config/di.php中向$di注入redis依赖：
$redis_config = array('host' => '127.0.0.1', 'port' => 6379);
$di->cache = new phalapi\cache\rediscache($redis_config);
  • 之后，在需要使用redis的地方利用\phalapi\di()->cache->set/get/delete等等即可

cors跨域

利用跨域插件https://github.com/gongshunkai/phalapi-cors，配置相当简单。

restful

由于php只是apache/nginx上的插件，http服务是由它们提供的，所以若要实现严格的restful api，必须借助它们的支持。例如apache，需要对.htaccess文件进行配置，来转发/重定向请求，将restful的请求转化为传统的。

具体可参考这个实践：https://www.ctolib.com/luyuanxun-phalapi-restful.html

上线部署

php项目的部署非常简单，上传代码就完事了！将整个phalapi目录上传到服务器上，然后确保你在远端服务器上也进行了全文开头的操作：

  • apache默认文档路径指向./public
  • 配置好了rewrite规则

此刻，你的接口就部署完成了。当然，你应该考虑一下：

  • 真实上线，文档不能让别人随意看到！请备份后删除./public/docs.php
  • 删除无用的./sdk和./tests目录

【全文终，谢谢您的阅读！】

上一篇：

下一篇：

推荐阅读