上往建站提供服务器空间服务商，百度快照排名，网站托管，百度推广运营,致力于设计外包服务与源代码定制开发，360推广，搜狗推广,增加网站的能见度及访问量提升网络营销的效果,主营：网站公司,百度推广公司电话,官网搭建服务,网站服务企业排名,服务器空间,英文域名等业务，专业团队服务，效果好。

酒泉小程序制作【酒泉企业邮箱】酒泉网站外包、酒泉微信商城开发、酒泉网店美工、酒泉淘宝设计

酒泉，古称肃州，是甘肃省辖地级市，甘肃省人民政府批复确定的丝绸之路经济带甘肃段重要节点城市、省域副中心城市。截至2020年11月，辖1个区、2个县级市、4个县，总面积19.2万平方千米，2019年常住人口113.22万，城镇常住人口70.69万，有汉、蒙、哈萨克、回等40多个民族。 [1-3] 

酒泉地处中国西北地区、甘肃省西北部、河西走廊西端， 东接张掖市和内蒙古自治区，南接青海省，西接新疆维吾尔自治区，北接蒙古国，自古就是通往新疆和西域的交通要塞，是现代航天的摇篮，新中国石油工业和核工业的发祥地，全国重要的新能源基地。

酒泉为汉代河西四郡之一，丝绸之路的重镇，因“城下有泉”、“其水若酒”而得名。酒泉是敦煌艺术的故乡，创造了辉煌的历史文化。同时，由于大自然的运动和人类的活动，创造了奇异瑰丽的自然美景和雄伟壮丽的人文景观。先后荣获影响世界的中国文化旅游名城、中国最具国际影响力旅游目的地等荣誉称号。酒泉市境内有敦煌莫高窟、安西锁阳城、酒泉公园、敦煌雅丹国家地质公园等旅游景点。

到这里，大家有没发现一些有趣的规律，或者一种似曾相识的感觉？上面的示例和背后的原理，大家应该很容易理解，当出现Common_Response_XML类未找到时也能很容易明白错误的原因。但当把这些简单的知识点，隐藏于复杂的上下文场景中时，就会容易导致一些令人感到费解的问题。还记得初始化文件./Public/init.php与项目入口文件./Public/shop/index.php吗？还记得为什么有些资源服务需要在初始化文件中注册，而有些则需要在入口文件中注册？为了唤起记忆，这里稍微回顾一下在这两个文件中分别注册的部分资源。

初始化文件中的注册：

$loader = new PhalApi_Loader(API_ROOT, 'Library');// 配置DI()->config = new PhalApi_Config_File(API_ROOT . '/Config');// 数据操作 - 基于NotORMDI()->notorm = new PhalApi_DB_NotORM(DI()->config->get('dbs'), DI()->debug);

Shop项目入口文件中的注册：

//装载你的接口DI()->loader->addDirs('Shop');// 微信签名验证服务DI()->filter = 'Common_Request_WeiXinFilter';// XML返回DI()->response = 'Common_Response_XML';

细心的读者可以发现，在初始化文件中，使用的都是框架已经的类，因为框架本身的类会默认全部能自动被加载。而对于Shop项目中的类，则需要在项目入口文件中使用，这是因为只有手动添加了Shop目录后，该目录下的类文件才能被自动加载。如果在初始化文件中，使用了Shop项目中的类，则会导致类找不到，因为那时尚未加载对应的Shop目录。尤其使用的是类名延迟加载方式时，会把问题隐藏得更深而难以排查。

这里的经验法则是，先挂靠再使用，在初始化文件中使用框架提供的类，在项目入口文件中使用项目实现的类。如果确实需要在初始化文件中使用项目实现的类，怎么办呢？解决方案可以有多种，例如可以把这些公共的代码放置在扩展类库下，因为扩展类库目录会在初始化文件中默认添加。另一种方案是在初始化文件一开始也把项目目录添加进去，但这样该目录下的全部类都会被自动加载。最后还可以把这些公共的类统一放置在某一个与项目目录无关的目录下，再在初始化文件中进行添加。

虽然，开发人员会对初始化文件和入口文件这两者感到困惑，增加了学习成本，并且每次都需要先挂靠代码目录才能使用其中的类，也带来了一定的复杂性。但其原理是非常简单的，即需要把要用到的目录添加进来，再使用。而之所以这样设计，是为了更好的扩展性，可以同时开发多个项目，多个模块，多套接口服务。

3.3 自动生成的在线文档

在线接口文档，主要有两种：

• 接口列表文档 显示当前项目下全部可用的接口服务，以及各个接口服务的名称、说明信息，如果需要，也可以显示扩展类库下提供的接口服务。

• 接口详情文档 针对单个接口服务的文档说明，用于显示该接口服务的基本信息、接口说明、接口参数、返回结果以及异常情况等。

下面分别进行解释。

温馨提示：在线文档使用反射机制生成，若文档查看失败，请确保opcache已关闭。

3.3.1 在线接口列表文档

如何访问接口列表文档？

在创建项目后，便可以通过访问Public目录下该项目目录内的listAllApis.php文件来访问接口列表文档。例如前面创建的Shop项目，其访问链接为：

http://api.phalapi.net/shop/listAllApis.php

打开后，其文档显示的内容，类似如下：

图3-3 在线接口列表文档的访问效果

在左边，是全部接口服务类的列表，按接口类名称的字典顺序进行排序。页面右边，是各个接口服务类所提供的全部服务，包括了接口服务、接口名称、更多说明等。

接口列表文档的注释规范

在上面的访问效果中，有部分的信息提示了“//请使用@desc 注释”或“//请检测接口服务注释”等字样，这是因为接口列表文档的生成，除了依赖于源代码，更大程序上还依赖于规范的注释。

接口列表的注释比较简单，主要有：

• 接口服务类说明 对应接口类文件中文档注释的第一行注释说明。例如，上面提示的“//请检测接口服务注释(Api_Welcome) ”，可以修改对应类文件的注释来调整。

// $ vim ./Shop/Api/Welcome.php<?php/**
 * Hello Wolrd示例类
 */class Api_Welcome extends PhalApi_Api {

• 序号 自动生成，不需要注释。把接口服务名称Class.Action按字典排序后从小到大依次编号。

• 接口服务 自动生成，通过反射自动获取接口类的全部可访问的方法，并提取可用的接口服务，即对应service参数的接口服务名称。

• 接口名称 接口中文名称，不带任何注解的注释，通常为接口类成员函数的第一行注释。如上面提示的“//请使用@desc 注释”，可以通过类成员函数的注释来调整。

  /**
   * 欢迎光临
   */public function say() {

• 更多说明 对应接口类成员函数的@desc注释。如上面提示的“//请使用@desc 注释”，可以添加@desc注释来调整。

  /**
   * 欢迎光临
   * @desc 简单的Hello Wolrd返回
   */public function say() {

按上面的注释规范调整好后，刷新刚才的接口列表页面，可以看到在线文档已经实时同步更新。

图3-4 调整后的在线接口文档

显示扩展类库的接口服务

查看listAllApis.php文件的源代码，可以看到默认情况下，已添加了若干个扩展类库的接口服务显示，包括User扩展、Auth扩展、七牛扩展。

//$ vim ./Public/shop/listAllApis.php$libraryPaths = array(    'Library/User/User',    // User扩展
    'Library/Auth/Auth',    // Auth扩展
    'Library/Qiniu/CDN',    // 七牛扩展);// 初始化require_once implode(D_S, array($root, '..', 'init.php'));// 处理项目DI()->loader->addDirs($apiDirName);

如果需要显示其他扩展类库下的接口服务，则需要将对应的项目目录参考上面的写法添加进来。添加好后，记得要在checkApiParams.php文件中同步添加。

顺便提一下，框架的一致性，在这里也得到了体现。那就是任何类的使用，都应先挂靠再使用。在添加了扩展类库的目录后，在线接口列表文档才能显示对应扩展类库下的接口服务。

酒泉小程序制作【酒泉企业邮箱】酒泉网站外包、酒泉微信商城开发、酒泉网店美工、酒泉淘宝设计

上往建站提供搭建网站，域名注册，官网备案服务，网店详情页设计，企业网店，专业网络店铺管理运营全托管公司咨询电话，服务器空间，微信公众号托管，网页美工排版,致力于域名申请，竞价托管，软文推广，全网营销,提供标准级专业技术保障，了却后顾之忧,主营：虚拟主机，网站推广，百度竞价托管，网站建设，上网建站推广服务，网络公司有哪些等业务，专业团队服务，效果好。

服务热线：400-111-6878 手机微信同号:18118153152（各城市商务人员可上门服务）