介绍

自定义注解的作用，主要用于支持开发者自己实现除系统内置的注解元外，自定义任意的注解标签。

在框架的源码包中，\box\annotation\目录下实现了一个Test自定义注解标签的案例，可查看参考。

使用场景

可能有的开发者会说，框架已经实现了这么丰富的注解标签支持，为什么还要浪费性能实现自定义注解呢？

下面我们来看一个场景：

项目A需要实现一个复杂的前置操作挂载，中间涉及了1，2，3种鉴权流程，
A接口权限高3种都要挂，
B接口只需要挂后2种。

这时候原系统内置的@AopBefore()前置注解就没办法很好的实现这个需求了。
而自定义注解的实现，就能很自由多变的应对这类业务场景。

注意事项

• 自定义的注解标签都应该统一存放在/box/annotation/目录下；
• 同一条路由请求中，自定义的注解标签均可以多次声明；
• 同个操作方法中多次声明同一个自定义的注解标签时，系统只会回调一次，但会携带多个标签参数，按声明顺序组合成list传入。

命名规范

• 所有自定义的注解标签，都需要统一继承至\x\doc\lable\Basics注解基类；
• 所有自定义的注解标签，都需要统一实现public function run($route, $type){}接口，用于接受注解回调处理；
• 当注解逻辑处理不通过时，应对调用return $this->route_error(自定义说明);方法，用于中断后续流程；该方法最终会触发框架的/box/lifecycle/route_error生命周期处理；
• 当逻辑处理通过时，应对调用return $this->_return();方法，用于告知系统继续向下执行；
• 假设，当我们声明一个注解标签为@Demo()注解元时，/box/annotation/下对应的文件名(类名)应该为Demo.php。

使用案例

下面为系统自带的案例注解标签@Test()，是如何实现的。
1、首先，我们先在/box/annotation/目录下，声明一个Test.php文件，并写入以下代码：

<?php
namespace box\annotation;
use \x\doc\lable\Basics;

class Test extends Basics
{
    /**
        * 启动项
        * @todo 无
        * @author 小黄牛
        * @version v1.2.10 + 2020.07.30
        * @deprecated 暂不启用
        * @global 无
        * @param array $route 路由参数
        * @param type int 路由类型 1.控制器注解 2.操作方法注解
        * @return bool 返回true表示继续向下执行
    */
    public function run($route, $type){
        // $route是多维数组
        // 当同一注释中，多次声明同一个注解时，只会回调一次，多次参数分别存放在该数组中
        var_dump($route);
        var_dump($type);

        // return route_error函数抛出自定义错误异常
        return $this->route_error('Msg内容自己随便写啦');

        // 若注解通过，应该调用_return()函数，代替return true;
        return $this->_return();
    }
}

2、然后，我们就可以选择一个控制器类，进行注解元挂载测试了：

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

/**
 * @Test(msg="我是自定义的注解1")
 * @Test(msg="我是自定义的注解2")
 * @Test(msg="我是自定义的注解3")
 * @Controller(prefix="")
*/
class Index extends Http
{
    /**
     * @Test(msg="我是自定义的注解1")
     * @Test(msg="我是自定义的注解2")
     * @Test(msg="我是自定义的注解3")
     * @RequestMapping(route="/", method="get", title="主页")
    */
    public function index() {
        return $this->fetch('我是主页');
    }

}

重启服务之后，我们访问该路由地址，就能在Shell界面里查看对应的注解参数，在浏览器中可以查看到生命周期回调的处理信息。