4.2 PhalApi 2.x 升級指南

2018-07-28 21:14 更新

PhalApi 2.x 升級指南

PhalApi自2015年初正式開源以來,版本主要經(jīng)歷了 v1.0.0 ~ v1.4.1,其間,我們一直在致力于“接口,從簡單開始!”的同時,也致力框架的兼容性升級。但考慮到2.x版本是全新的實現(xiàn)機制和方式,經(jīng)過綜合和慎重考慮,2.x版本將不再支持向前兼容,即1.x版本不能完美升級到2.x版本。對此帶來的不便,我深表歉意。

為方便1.x版本的開發(fā)者更容易從概念上切換到2.x版本,以下是快速升級指南。

從石器農(nóng)耕到現(xiàn)代自動化

自2017年x月x日發(fā)布 v2.0.0 版本開始,PhalApi社區(qū)主要存在兩大系列版本,分別是:

  • PhalApi v1.x 版本 slogan:接口,從簡單開始!
  • PhalApi v2.x 版本 slogan:助你創(chuàng)造價值!

這兩系列版本,最大的差異在于,PhalApi v2.x 版本是:

  • 使用了composer
  • 引入了命名空間
  • 遵循psr-4規(guī)范

相比之下,PhalApi v1.x 版本則是:

  • 未使用composer,自主構建自動加載器PhalApi_Loader
  • 完全不使用命名空間
  • 遵循psr-0規(guī)范以及PEAR命名規(guī)范

使用composer的方式,更有利于可重用組件的管理,并且向國際化、向主流靠攏,同時也要求我們需要對PhalApi進行重新劃分與調(diào)整。而引入命名空間,則更是要求核心框架代碼、擴展類庫乃至應用項目開發(fā),都需要重新調(diào)整。

這是歷史發(fā)展的必然趨勢,因為composer和命名空間將會被越來越多的開發(fā)人員所熟悉。如果在1.x版本,我們是石器農(nóng)耕時代,那么2.x版本,我們迎來的將是現(xiàn)代自動化時代。

溫馨提示:關于composer,更多可訪問:Composer 中文網(wǎng) / Packagist 中國全量鏡像。

composer的使用方式

在1.x版本中,PhalApi更多是以自主研發(fā)的自動加載方式為主,這種方式原始、簡單,并且粗糙。在2.x版本中,PhalApi使用的是composer管理方式,這要求對已有的代碼倉庫進行重新劃分,并分為:項目、擴展類庫和核心框架這三部分。

  • 項目:可用于實際項目開發(fā),提供給開發(fā)人員使用。
  • 擴展類庫:由廣大開發(fā)人員共同維護、分享。
  • 核心框架:由PhalApi團隊核心人員長期維護,并接受貢獻者的merge request。

如何創(chuàng)建新項目?

如果需要使用PhalApi 2.x 版本開發(fā)新項目,可以直接使用phalapi/phalapi。

在composer方式下,當需要自動加載類和函數(shù)時,可使用autoload配置,參考:

{
    "autoload": {
        "files": [
            "src/app/functions.php"
            ],
        "psr-4": {
            "App\\": "src/app"
        }
    }
}

如何使用擴展類庫?

當需要使用擴展類庫時,你只需要簡單的告訴 Composer 需要依賴哪些包。在composer.json中添加相應的包名稱和版本信息,然后更新即可。以添加Task計劃任務擴展為例,首先修改composer.json并添加:

{
    "require": {
        "phalapi/task": "1.0.*"
    }
}

然后,進行composer更新:

$ composer update

如果擴展類庫還提供了直接可用的接口服務,這里則還需要配置psr-4,以便讓composer能正常自動加載對應的類文件,并且顯示在在線接口文檔。

如何升級框架?

借助composer,可輕松更新框架,同時也可以指定需要依賴的具體版本。例如,若希望從2.0.0升級到2.0.1版本,可以:

{
    "require": {
        "phalapi/kernal": "2.0.1"
    }
}

然后,進行composer更新即可。

命名空間下的差異

由于PhalApi 1.x 版本不使用命名空間,而PhalApi 2.x 版本使用了命名空間,因此會有所差異。主要有:

接口服務請求時的差異

1.x 版本的默認接口服務是Default.Index,對應文件./Demo/Api/Default.php;2.x 版本的默認接口服務是App.Site.Index,對應文件./src/app/Api/Site.php。

1.x 版本的接口服務的請求格式是:Class.Action;2.x 版本的接口服務的請求格式是:Namespace.Class.Action,比舊版本多了命名空間前綴,并且為了兼容原來的格式,缺省的命名空間是App。當命名空間和類名空間存在多組時,將會使用下劃線分割。以下是2.x版本的一些示例:

2.x 請求的service參數(shù) 對應的文件 執(zhí)行的類方法
./src/app/Api/Site.php App/Api/Site::Index()
?s=Site.Index ./src/app/Api/Site.php App/Api/Site::index()
?s=Weibo.Login ./src/Api/Weibo.php App/Api/Weibo::login()
?s=User.Weibo.Login ./src/user/Api/Weibo.php User/Api/Weibo::login()
?s=App_User.Third_Weibo.Login ./src/app/user/Api/Third/Weibo.php App/User/Api/Third/Weibo::login()

Model層自動匹配的表名差異

在1.x 版本中,默認表名的自動匹配規(guī)則是:取Model_后面部分的字符全部轉(zhuǎn)小寫。例如:

<?php
class Model_User extends PhalApi_Model_NotORM {
}

類Model_User自動匹配的表名為user。

在2.x 版本中,規(guī)則類似,但由于多了命名空間,默認表名的自動匹配規(guī)則是:取\Model\后面部分的字符全部轉(zhuǎn)小寫,將用下劃線分割。例如:

<?php
namespace App\Model\User;
use PhalApi\Model\NotORMModel as Model;


class Friends extends Model {
}

則類App\Model\User\Friends自動匹配的表名為user_friends。以下是2.x版本的一些示例:

2.x 的Model類名 對應的文件 自動匹配的表名
App\Model\User ./src/app/Model/User.php user
App\ModelUser\Friends ./src/app/Model/User/Friends.php user_friends
App\User\Model\Friends ./src/app/user/Model/Friends.php friends
App\User\Model\User\Friends ./src/app/user/Model/User/Friends.php user_friends

和1.x 版本相同的是,自動匹配的表名后面會自動加上表前綴。

當自動匹配的表名不能滿足實際開發(fā)需求時,1.x 和 2.x 版本均支持自定義表名。

可訪問的入口差異

在PhalApi 1.x 版本中,對外可訪問的入口主要有:

  • 不同項目的訪問入口,如:/Public/demo/index.php
  • 在線接口列表文檔,如:/Public/demo/listAllApis.php
  • 在線接口詳情文檔,如:/Public/demo/checkApiParams.php

如何訪問在線接口文檔?

鑒于PhalApi 1.x版本中的訪問入口過于分散,且在線接口文檔鏈接過于冗長,在PhalApi 2.x 版本中,我們同時對此進行了優(yōu)化。即精簡為:

  • 訪問入口默認只有一個,即:/public/index.php
  • 在線接口列表與接口詳情文檔,二合為一,鏈接改為:/public/docs.php

項目目錄結構的差異

在PhalApi 1.x中,項目目錄結構為:

.
│
├── PhalApi         //PhalApi框架,后期可以整包升級
├── Library         //PhalApi擴展類庫,可根據(jù)需要自由添加擴展
├── SDK             //PhalApi提供的SDK包,客戶可根據(jù)需要選用
│
│
├── Public          //對外訪問目錄,建議隱藏PHP實現(xiàn)
│   └── demo        //Demo服務訪問入口
│
│
├── Config          //項目接口公共配置,主要有:app.php, sys.php, dbs.php
├── Data            //項目接口公共數(shù)據(jù)
├── Language        //項目接口公共翻譯
├── Runtime         //項目接口運行文件目錄,用于存放日記,可軟鏈到別的區(qū)
│
│
└── Demo            //應用接口服務,名稱自取,可多組
    ├── Api             //接口響應層
    ├── Domain          //接口領域?qū)?    ├── Model           //接口持久層
    └── Tests           //接口單元測試

在PhalApi 2.x中,項目目錄結構為:

.
│?
├── config                  // 項目接口公共配置
│?? ├── app.php             // 項目配置
│?? ├── dbs.php             // 數(shù)據(jù)庫配置
│?? ├── di.php              // DI依賴注入配置
│?? └── sys.php             // 系統(tǒng)環(huán)境配置
│?
├── public                  // 對外訪問目錄,推薦將web根路徑設定在此目錄
│?? ├── docs.php            // 自動生成的在線接口文檔
│?? ├── examples            // 示例
│?? ├── index.php           // 接口服務統(tǒng)一訪問入口
│?? └── init.php            // 統(tǒng)一初始化文件
├── runtime                 // 項目運行時產(chǎn)生的文件目錄
│?
├── src                     // 項目PHP源代碼
│?? └── app                 // 默認使用此App命名空間,可創(chuàng)建多上命名空間
│??     ├── Api             // 接口響應控制層
│??     ├── Domain          // 接口領域業(yè)務層
│??     ├── functions.php   // 面向過程式的函數(shù)
│??     └── Model           // 接口數(shù)據(jù)模型層
├── tests                   // 單元測試
│?
├── bin                     // 腳本命令
├── data                    // 用于存放SQL建表基本語句
├── language                // 語言翻譯包
├── sdk                     // 客戶端SDK開發(fā)包,支持9+種語言
│?
├── composer.json           // composer.json文件
└── vendor                  // 依賴安裝包

主要區(qū)別在于,對于不放置PHP源代碼的目錄,全部改用小寫。

附錄:對照表

附錄1:類對照表

以下是PhalApi 2.x 與PhalApi 1.x 的類對照關系。

PhalApi v2.x PhalApi v1.x 備注
PhalApi\PhalApi PhalApi
PhalApi\Api PhalApi_Api
PhalApi\ApiFactory PhalApi_ApiFactory
PhalApi\Cache PhalApi_Cache
PhalApi\Cache\APCUCache PhalApi_Cache_APCU
PhalApi\Cache\FileCache PhalApi_Cache_File
PhalApi\Cache\MemcacheCache PhalApi_Cache_Memcache
PhalApi\Cache\MemcachedCache PhalApi_Cache_Memcached
PhalApi\Cache\MultiCache PhalApi_Cache_Multi
PhalApi\Cache\NoneCache PhalApi_Cache_None
PhalApi\Cache\RedisCache PhalApi_Cache_Redis
PhalApi\Config PhalApi_Config
PhalApi\Config\FileConfig PhalApi_Config_File
PhalApi\Config\YaconfConfig PhalApi_Config_Yaconf
PhalApi\Cookie PhalApi_Cookie
PhalApi\Cookie\MultiCookie PhalApi_Cookie_Multi
PhalApi\Crypt PhalApi_Crypt
PhalApi\Crypt\McryptCrypt PhalApi_Crypt_Mcrypt
PhalApi\Crypt\MultiMcryptCrypt PhalApi_Crypt_MultiMcrypt
PhalApi\Crypt\RSA\KeyGenerator PhalApi_Crypt_RSA_KeyGenerator
PhalApi\Crypt\RSA\MultiBase PhalApi_Crypt_RSA_MultiBase
PhalApi\Crypt\RSA\MultiPri2PubCrypt PhalApi_Crypt_RSA_MultiPri2Pub
PhalApi\Crypt\RSA\MultiPub2PriCrypt PhalApi_Crypt_RSA_MultiPub2Pri
PhalApi\Crypt\RSA\Pri2PubCrypt PhalApi_Crypt_RSA_Pri2Pub
PhalApi\Crypt\RSA\Pub2PriCrypt PhalApi_Crypt_RSA_Pub2Pri
PhalApi\CUrl PhalApi_CUrl
PhalApi\Database PhalApi_DB
PhalApi\Database\NotORMDatabase PhalApi_DB_NotORM 改用Database全稱
PhalApi\DependenceInjection PhalApi_DI 改用DependenceInjection全稱
PhalApi\Exception PhalApi_Exception
PhalApi\Exception\BadRequestException PhalApi_Exception_BadRequest
PhalApi\Exception\InternalServerErrorException PhalApi_Exception_InternalServerError
PhalApi\Exception\RedirectException PhalApi_Exception_Redirect
PhalApi\Filter PhalApi_Filter
PhalApi\Filter\NoneFilter PhalApi_Filter_None
PhalApi\Filter\SimpleMD5Filter PhalApi_Filter_SimpleMD5
PhalApi\Helper\ApiDesc PhalApi_Helper_ApiDesc 應用層不用關注
PhalApi\Helper\ApiList PhalApi_Helper_ApiList 應用層不用關注
PhalApi\Helper\ApiOnline PhalApi_Helper_ApiOnline 應用層不用關注
PhalApi\Helper\TestRunner PhalApi_Helper_TestRunner
PhalApi\Helper\Tracer PhalApi_Helper_Tracer
PhalApi\Loader PhalApi_Loader
PhalApi\Logger PhalApi_Logger
PhalApi\Logger\ExplorerLogger PhalApi_Logger_Explorer
PhalApi\Logger\FileLogger PhalApi_Logger_File
PhalApi\Model PhalApi_Model
PhalApi\Model\NotORMModel PhalApi_Model_NotORM
PhalApi\Model\Proxy PhalApi_ModelProxy
PhalApi\Model\Query PhalApi_ModelQuery
PhalApi\Request PhalApi_Request
PhalApi\Request\Formatter PhalApi_Request_Formatter
PhalApi\Request\Formatter\ArrayFormatter PhalApi_Request_Formatter_Array 應用層不用關注
PhalApi\Request\Formatter\BaseFormatter PhalApi_Request_Formatter_Base 應用層不用關注
PhalApi\Request\Formatter\BooleanFormatter PhalApi_Request_Formatter_Boolean 應用層不用關注
PhalApi\Request\Formatter\CallableFormatter PhalApi_Request_Formatter_Callable 應用層不用關注
PhalApi\Request\Formatter\CallbackFormatter PhalApi_Request_Formatter_Callback 應用層不用關注
PhalApi\Request\Formatter\DateFormatter PhalApi_Request_Formatter_Date 應用層不用關注
PhalApi\Request\Formatter\EnumFormatter PhalApi_Request_Formatter_Enum 應用層不用關注
PhalApi\Request\Formatter\FileFormatter PhalApi_Request_Formatter_File 應用層不用關注
PhalApi\Request\Formatter\FloatFormatter PhalApi_Request_Formatter_Float 應用層不用關注
PhalApi\Request\Formatter\IntFormatter PhalApi_Request_Formatter_Int 應用層不用關注
PhalApi\Request\Formatter\StringFormatter PhalApi_Request_Formatter_String 應用層不用關注
PhalApi\Request\Parser PhalApi_Request_Var 重命名為Parser,避免與關鍵字var沖突
PhalApi\Response PhalApi_Response
PhalApi\Response\ExplorerResponse PhalApi_Response_Explorer
PhalApi\Response\JsonResponse PhalApi_Response_Json
PhalApi\Response\JsonpResponse PhalApi_Response_JsonP 注意p字母為小寫
PhalApi\Response\XmlResponse PhalApi_Response_Xml
PhalApi\Tool PhalApi_Tool
PhalApi\Translator PhalApi_Translator

類名重命名規(guī)則

原來的類名遵循PEAR規(guī)范,現(xiàn)需要調(diào)整遵循PSR-4規(guī)范。如:

原來的:PhalApi_Filter


調(diào)整后:\PhalApi\Filter  

對于有繼承的情況,為了避免最后的關鍵字有沖突,統(tǒng)一在子類后面添加父類的名稱作為后續(xù)。如:

原來的:
PhalApi_COnfig_File
PhalApi_COnfig_Yaconf


調(diào)整后:
PhalApi\Config\FileConfig
PhalApi\Config\YaconfConfig

附錄2:函數(shù)對照表

以下是PhalApi 2.x 與PhalApi 1.x 的函數(shù)對照關系。

PhalApi v2.x PhalApi v1.x 備注
PhalApi\DI() DI()
PhalApi\SL() SL()
PhalApi\T() T()

函數(shù)名保持一致,但需要注意前面添加PhalApi命名空間前綴。

附錄3:腳本命令對照表

以下是PhalApi 2.x 與PhalApi 1.x 的腳本命令對照關系。

PhalApi v2.x PhalApi v1.x 備注
./bin/phalapi-buildsqls ./PhalApi/phalapi-buildsqls 生成SQL語句
./bin/phalapi-buildtest ./PhalApi/phalapi-buildtest 生成測試骨架代碼
暫未遷移 ./PhalApi/phalapibuildcode 創(chuàng)建項目代碼
暫未遷移 ./PhalApi/phalapi-buildapp 創(chuàng)建新項目,暫不需要遷移

附錄4:可訪問入口對照表

以下是PhalApi 2.x 與PhalApi 1.x 的可訪問入口對照關系。

PhalApi v2.x PhalApi v1.x 備注
./public/index.php ./Public/demo/index.php 可省略index.php文件
./public/docs.php ./Public/demo/listAllApis.php 在線接口列表文檔
./public/docs.php?detail=1 ./Public/demo/checkApiParams.php 在線接口詳情文檔,通過detail參數(shù)區(qū)分
./public/docs/ ./Public/demo/docs/ 離線文檔生成目錄
以上內(nèi)容是否對您有幫助:
在線筆記
App下載
App下載

掃描二維碼

下載編程獅App

公眾號
微信公眾號

編程獅公眾號