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

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

资兴市，湖南省辖县级市，由郴州市代管，位于湖南省东南部。因唐代旧县治位于资兴江畔（今东江湖）而得名，是郴商的发源地之一。资兴市地处湘江流域耒水的上游，在罗霄山脉西麓、茶永盆地南端，为湘、粤、赣三省交汇处。东邻桂东县、株洲市炎陵县，南接汝城县、宜章县，西连苏仙区，北抵永兴、安仁县。总面积2746.79平方公里。 [1] 

2017年，资兴市实现地区生产总值362.51亿元，按可比价格计算，增长8.3%。其中，第一产业增加值26.95亿元，增长4.2%；第二产业增加值223.59亿元，增长6.9%；第三产业增加值111.97亿元，增长12.5%。三次产业结构为7.4:61.7:30.9。 [2]  资兴市名优特产主要有杨梅、东江鱼、狗脑贡茶等；风景名胜主要有东江湖、寿佛寺、回龙山等。资兴市下辖2乡9镇2街道；户籍总人口37.85万人，常住人口34.97万人（2017年）。2017年10月，被住建部命名为国家园林城市。2018年11月，被科技部确定为首批创新型县（市）， [3]  入选中国县级市全面小康指数前100名。第三批“绿水青山就是金山银山”实践创新基地。 [4] 

2019年3月6日，中央宣传部、财政部、文化和旅游部、国家文物局《中央宣传部 财政部 文化和旅游部 国家文物局关于公布《革命文物保护利用片区分县名单（第一批）》的通知》资兴市名列其中。 [5] 

2020年6月，经中央依法治国委入选为第一批全国法治政府建设示范地区和项目名单。 [6]  2020年度真抓实干成效明显，被湖南省人民政府公布为推动高质量发展成效明显的县市区，给予100万元标准奖励。

2.1.2 参数规则

接口参数，对于接口服务本身来说，是非常重要的。对于外部调用的客户端来说，同等重要。对于接口参数，我们希望能够既减轻后台开发对接口参数获取、判断、验证、文档编写的痛苦；又能方便客户端快速调用，明确参数的意义。由此，我们引入了参数规则这一概念，即：通过配置参数的规则，自动实现对参数的获取和验证，同时自动生成在线接口文档。

参数规则是针对各个接口服务而配置的多维规则数组，由PhalApi_Api::getRules()方法返回。其中，参数规则数组的一维下标是接口类的方法名，对应接口服务的Action；二维下标是类属性名称，对应在服务端获取通过验证和转换化的最终客户端参数；三维下标name是接口参数名称，对应外部客户端请求时需要提供的参数名称。即：

    public function getRules() {
        return array(
            '接口类方法名' => array(
                '接口类属性' => array('name' => '接口参数名称', ... ... ),
            ),
        );
    }复制代码

通常情况下，接口类属性和接口参数名称一样，但也可以不一样。一种情况是客户端的接口参数名称惯用下划线分割，即蛇形(下划线)命名法，而服务端中则惯用驼峰命名法。例如对于“是否记住我”，客户端参数用is_remember_me，服务端用isRememberMe。另一种情况是如果参数名称较长，为了节省移动网络下的流量，也可以针对客户端参数使用有意义的缩写。如前面的“是否记住我”客户端缩写成is_rem_me。

在参数规则里，可以配置多个接口类方法名，每个方法名的规则，又可以配置多个接口类属性，即有多个接口参数。

配置好参数规则后，当接口参数通过验证后，就可以在接口类方法内，通过类成员属性获取相应的接口参数。

一个简单的示例

假设我们现在需要提供一个用户登录的接口，接口参数有用户名和密码，那么新增的接口类和规则如下：

// $ vim ./Shop/Api/User.php<?phpclass Api_User extends PhalApi_Api {

    public function getRules() {
        return array(
            'login' => array(
                'username' => array('name' => 'username'),
                'password' => array('name' => 'password'),
            ),
        );
    }

    public function login() {
        return array('username' => $this->username, 'password' => $this->password);
    }                               }复制代码

当我们请求此接口服务，并类似这样带上username和password参数时：

http://api.phalapi.net/shop/?service=User.Login&username=dogstar&password=123456复制代码

就可以得到这样的返回结果。

{"ret":0,"data":{"username":"dogstar","password":"123456"},"msg":""}复制代码

这是因为，在接口实现类里面getRules()成员方法配置参数规则后，便可以通过类属性的方式，根据配置指定的名称获取对应的接口参数，如这里的：$this->username和$this->password。

更完善的示例

在实际项目开发中，我们需要对接口参数有更细致的规定，如是否必须、长度范围、最值和默认值等。

继续上面的业务场景，用户登录接口服务的用户名参数和密码参数皆为必须，且密码长度至少为6个字符，则可以参数规则调整为：

// $ vim ./Shop/Api/User.php
    public function getRules() {
        return array(
            'login' => array(
                'username' => array('name' => 'username', 'require' => true),
                'password' => array('name' => 'password', 'require' => true, 'min' => 6),
            ),
           ... ...复制代码

配置好后，如果不带任何参数再次请求?service=User.Login，就会被视为非法请求，并得到这样的错误提示：

{
    "ret": 400,
    "data": [],
    "msg": "非法请求：缺少必要参数username"}复制代码

如果传递的密码长度不对，也会得到一个错误的返回。

温馨提示：当接口参数非法时，返回的ret都为400，且data为空。在这一章节中，当再次非法返回时，将省略ret与data，以节省篇幅。

三级参数规则配置

参数规则主要有三种，分别是：系统参数规则、应用参数规则、接口参数规则。

系统参数是指被框架保留使用的参数。目前已被PhalApi占用的系统参数只有一个，即：service参数。类型为字符串，格式为：Class.Action，首字母不区分大小写，建议统一以大写开头。

以下是一些示例：

• 推荐写法，类名和方法名开头大写

  ?service=User.Login复制代码

• 正确写法，类名和方法名开头都小写，或方法名全部小写

  ?service=user.login?service=user.getbaseinfo复制代码

• 错误写法，缺少方法名、缺少点号分割、使用竖线而非点号分割

  ?service=User?service=UserLogin?service=User|GetBaseInfo复制代码

温馨提示：service参数中的类名只能开头小写，否则会导致linux系统下类文件加载失败。

应用参数是指在一个接口系统中，全部项目的全部接口都需要的参数，或者通用的参数。假如我们的商城接口系统中全部的接口服务都需要必须的签名sign参数，以及非必须的版本号，则可以在./Config/app.php中的apiCommonRules进行应用参数规则的配置：

//$vim ./Config/app.php<?phpreturn array(
    /**
     * 应用接口层的统一参数
     */
    'apiCommonRules' => array(
        //签名
        'sign' => array(
            'name' => 'sign', 'require' => true,
        ),
        //客户端App版本号，默认为：1.4.0
        'version' => array(
            'name' => 'version', 'default' => '1.4.0', 
        ),
    ),

    ... ...复制代码

其配置格式和前面所说的接口参数规则配置类似，都是一个规则数组。区别是这里是二维数组，相当于全部方法的公共的接口类属性。

接口参数是指各个具体的接口服务所需要的参数，为特定的接口服务所持有，独立配置。并且进一步在内部又细分为两种：

• 通用接口参数规则：使用*作为下标，对当前接口类全部的方法有效。

• 指定接口参数规则：使用方法名作为下标，只对接口类的特定某个方法有效。

例如为了加强安全性，需要为全部的用户接口服务都加上长度为4位的验证码参数：

// $ vim ./Shop/Api/User.php
    public function getRules() {
        return array(
            '*' => array(
                'code' => array('name' => 'code', 'require' => true, 'min' => 4, 'max' => 4),
            ),
            'login' => array(
                'username' => array('name' => 'username', 'require' => true),
                'password' => array('name' => 'password', 'require' => true, 'min' => 6),
            ),
        );
    }复制代码

现在，当再次请求用户登录接口，除了要提供用户名和密码外，我们还要提供验证码code参数。并且，对于Api_User类的其他方法也一样。

多个参数规则时的优先级

当同一个参数规则分别在应用参数、通用接口参数及指定接口参数出现时，后面的规则会覆盖前面的，即具体化的规则会替换通用的规则，以保证接口参数满足特定场合的定制要求。

简而言之，多个参数规则的优先级从高到下，分别是（正如你想到的那样）：

• 1、指定接口参数规则

• 2、通用接口参数规则

• 3、应用参数规则

• 4、系统参数规则（通常忽略，当前只有service）

参数规则配置

具体的参数规则，根据不同的类型有不同的配置选项，以及一些公共的配置选项。目前，主要的类型有：字符串、整数、浮点数、布尔值、时间戳/日期、数组、枚举类型、文件上传和回调函数。

表2-2 参数规则选项一览表

公共配置选项

公共的配置选项，除了上面的类型、参数名称、是否必须、默认值，还有说明描述、数据来源。下面分别简单说明。

• 类型 type
  用于指定参数的类型，可以是string、int、float、boolean、date、array、enum、file、callable，或者自定义的类型。未指定时，默认为字符串。

• 参数名称 name
  接口参数名称，即客户端需要传递的参数名称。与PHP变量规则一样，以下划线或字母开头。此选项必须提供，否则会提示错误。

• 是否必须require
  为TRUE时，表示此参数为必须值；为FALSE时，表示此参数为可选。未指定时，默认为FALSE。

• 默认值 default
  未提供接口参数时的默认值。未指定时，默认为NULL。

• 最小值 min，最大值 max
  部分类型适用。用于指定接口参数的范围，比较时采用的是闭区间，即范围应该为：[min, max]。也可以只使用min或max，若只配置了min，则表示：[min, +∞)；若只配置了maz，则表示：(-∞, max]。

• 说明描述 desc
  用于自动生成在线接口详情文档，对参数的含义和要求进行扼要说明。未指定时，默认为空字符串。

• 数据来源 source
  指定当前单个参数的数据来源，可以是post、get、cookie、server、request、header、或其他自定义来源。未指定时，默认为统一数据源。目前支持的source与对应的数据源映射关系如下：

表2-3 source与对应的数据源映射关系

通过source参数可以轻松、更自由获取不同来源的参数。以下是一些常用的配置示例。

// 获取HTTP请求方法，判断是POST还是GET'method' => array('name' => 'REQUEST_METHOD', 'source' => 'server'),// 获取COOKIE中的标识'is_new_user' => array('name' => 'is_new_user', 'source' => 'cookie'),// 获取HTTP头部中的编码，判断是否为utf-8'charset' => array('name' => 'Accept-Charset', 'source' => 'header'),复制代码

若配置的source为无效或非法时，则会抛出异常。如配置了'source' => 'NOT_FOUND'，会得到：

"msg": "服务器运行错误: 参数规则中未知的数据源：NOT_FOUND"复制代码

9种参数类型

对于各种参数类型，结合示例说明如下。

• 字符串 string

当一个参数规则未指定类型时，默认为string。如最简单的：

array('name' => 'username')复制代码

温馨提示：这一小节的参数规则配置示例，都省略了类属性，以关注配置本身的内容。

这样就配置了一个参数规则，接口参数名字叫username，类型为字符串。

一个完整的写法可以为：

array('name' => 'username', 'type' => 'string', 'require' => true, 'default' => 'nobody', 'min' => 1, 'max' => 10)复制代码

这里指定了为必选参数，默认值为nobody，且最小长度为1个字符，最大长度为10个字符，若传递的参数长度过长，如&username=alonglonglonglongname，则会异常失败返回：

"msg": "非法请求：username.len应该小于等于10, 但现在username.len = 21"复制代码

当需要验证的是中文的话，由于一个中文字符会占用3个字节。所以在min和max验证的时候会出现一些问题。为此，PhalApi提供了format配置选项，用于指定字符集。如：

array('name' => 'username', 'type' => 'string', 'format' => 'utf8', 'min' => 1, 'max' => 10)复制代码

我们还可以使用regex下标来进行正则表达式的验证，一个邮箱的例子是：

array('name' => 'email', 'regex' => "/^([0-9A-Za-z\\-_\\.]+)@([0-9a-z]+\\.[a-z]{2,3}(\\.[a-z]{2})?)$/i")复制代码

• 整型 int

整型即自然数，包括正数、0和负数。如通常数据库中的id，即可配置成：

array('name' => 'id', 'type' => 'int', 'require' => true, 'min' => 1)复制代码

当传递的参数，不在其配置的范围内时，如&id=0，则会异常失败返回：

"msg": "非法请求：id应该大于或等于1, 但现在id = 0"复制代码

另外，对于常见的分页参数，可以这样配置：

array('name' => 'page_num', 'type' => 'int', 'min' => 1, 'max' => 20, 'default' => 20)复制代码

即每页数量最小1个，最大20个，默认20个。

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