介绍

@Param()注解，主要用于对客户端请求参数的过滤，和默认值预设。
该注解比较复杂，共支持13个参数设置。

用法

场景：对客户端请求参数的过滤，和默认值预设。
支持：HTTP、WebSocket、Rpc(2.5.2起)、Mqtt(2.5.2+)
注解：@Param()

参数：

• name=""

  • 功能：参数键名
  • 值单位：字符串
  • 默认值：无

• method=""

  • 功能：注解启用类型，支持GET或POST传入
  • 值单位：字符串
  • 默认值：不限制
  • 注意：该参数只对HTTP请求有效。

• type=""

  • 功能：参数类型，多个类型支持使用|符号分隔
  • 值单位：字符串
  • 默认值：不限制
  • 注意：由于HTTP表单的特性，提交int类型，在PHP中收到的会是string类型。

• value=""

  • 功能：为空时对参数的预设值（v2.5.19版本后改为isset为false时预设，会根据允许的请求类型进行数据判断。）
  • 值单位：字符串
  • 默认值：无

• empty=""

  • 功能：是否允许为空
  • 值单位：false允许为空，true不能为空
  • 默认值：false

• chinese=""

  • 功能：使用min=""、max=""参数时，是否使用mb_strlen()函数做为长度依据。
  • 值单位：false否，true是
  • 默认值：false

• min=""

  • 功能：最小长度限制
  • 值单位：根据chinese=""参数为准
  • 默认值：无

• max=""

  • 功能：最大长度限制
  • 值单位：根据chinese=""参数为准
  • 默认值：无

• regular=""

  • 功能：正则表达式判断
  • 值单位：正则字符串
  • 默认值：无

• tips=""

  • 功能：当注解属性过滤不通过时，输出给回调方法的提示内容
  • 值单位：字符串
  • 默认值：系统编译提示语

• callback=""

  • 功能：当过滤不通过时，系统调用的回调处理类，或函数。
  • 值单位：字符串
  • 默认值：系统生命周期处理：\box\lifecycle\annotate_param->run();

• validate=""

  • 功能：调用Validate验证器的规则。(2.5.6起)
  • 值单位：字符串
  • 默认值：无

• alias=""

  • 功能：Validate验证器不通过时，错误抛出的字段名对应中文别名。(2.5.6起)
  • 值单位：字符串
  • 默认值：无

使用案例

一个完整的参数过滤注解大概如下：

<?php
namespace app\http;
use x\controller\Http;

class Index extends Http
{
    /**
     * @RequestMapping(route="/test", method="GET", title="我是测试路由")
     * @Param(name="id", method="POST", type="int|string", value="1", empty="true", min="10", max="20", chinese="true", callback="\box\lifecycle\annotate_param")
     * @Param(name="name", value="sw-x")
    */
    public function param() {
        return $this->fetch('测试@Param()注解');
    }
}

上面最长的那条@Param()注解，可以解释为：

• HTTP请求类型为POST请求时该注解生效，或者WebSocket请求时生效
• param参数id，不允许为空
• 不存在或为null时，默认为1
• 只允许int或string类型
• 不使用mb_strlen获取字节长度
• 最小长度10
• 最大长度20
• 以上参数不通过时，使用\box\lifecycle\annotate_param类处理回调

使用案例(调用验证器规则)

实际开发中，对某个字段的校验，往往是很多场景下复用的，如果使用regular=""等属性，就会造成后期代码难以管理；
v2.5.6版本后，@Param注解加入了验证器的支持，对于内置验器规则不满足的开发者，还可以自行封装规则，具体的验证器使用方法，可以参考验证器相关文档；

下面介绍@Param注解中，关于validate的使用方法：

<?php
namespace app\http;
use x\controller\Http;

class Index extends Http
{
    /**
     * @RequestMapping(route="/test", method="GET", title="我是测试路由")
     * @Param(name="id", alias="注解", validate="require|int|min:10|max:100")
    */
    public function param() {
        return $this->fetch('测试 validate 的支持');
    }
}

上面的@Param()注解，可以解释为：

• param参数id，不允许为空
• 必须是整数
• 字符长度不能小于10
• 字符长度不能大于100