Implement APIs

phprs通过@注释定义类的路由、绑定输入输出、管理依赖

• 类注释
  • @path
• 方法注释
  • @route
  • @param
  • @return
  • @throws
  • @cache
• 属性注释
  • @property
  • @inject

类注释

在类头部的注释中声明

@path

必选

示例:

@path("/myapi")

指定此类下所有接口都在/myapi路径下(这里指url路径, 而不是文件在磁盘上的路径)，默认从第一季路径开始匹配，可以通过conf.json设置url_begin指定从何处开始匹配。

{
    "caoym\\phprs\\Router": {
        "properties": {
            "url_begin":1 //url_begin用于指定路由的从哪一级开始匹配,默认为0
        } 
    }
}

方法注释

@route

声明方法对应的路由

如果有多个路由匹配, 则命中最严格的规则

同一个方法可以声明多个@route

必选

示例:

@route("GET", "func1")

匹配 GET /myapi/func1

@route("*", "func1")

匹配 所有方法 /myapi/func1

@route("GET", "func1?param=1")

匹配GET /myapi/func1?param=1, 其中query_string参数的先后顺序无关(如/myapi/func1?param2=x&param=1也匹配)

@route("GET", "patha/*")

匹配GET /myapi/patha/下所有子路径,如/myapi/patha/123, 但不匹配/myapi/patha

@route("GET", "patha/*/pathb")

匹配GET /myapi/patha/下所有子路径中存在pathb的

@route("GET", "resources/type1") @route("GET", "resources/type2") @route("GET", "resources/type3")

匹配其中任意一条规则, 就调用接口

@param

对参数进行双向绑定, 使用jsonpath表达式, 绑定$GLOBALS数组中的数据，如$._GET,$._POST

1. 声明方法的参数，如果被声明的参数不存在, 且此参数没有默认值, 请求调用时,将抛出BadRequest异常.如:

   /**
    * @route({"GET","/test"})
    * @param({"arg0","$._GET.arg0"})
    * @param({"arg1","$._GET.arg1"})
    */
   function public test($arg0, $arg1=null){
   }

   那么 GET /test 因为缺少arg0将返回BadRequest, GET /test?arg0=1 将正常执行，且arg1使用默认值

2. 如果参数是引用方式传递, 则参数的来源可以在方法内部修改. 如:

   /**
    * @route({"GET","/test"})
    * @return({"cookie","token", "$token_val"})
    */
   function public test(&token_val){
       $token_val = 'xxxx';
   }

   test()内部通过赋值token_val而修改了cookie

必选(如果方法有参数)

示例:

@param({"arg0","$._GET.param0"})

指定方法被调用时,"$._GET.param0"对应的值将被作为参数$arg0,"$._GET.param0"是jsonpath表达式, 可以搜索$GLOBALS数组中的数据, 除此之外还有一些特殊的变量:

$.path 获取当前请求的路径(相对于Router中指定的root_path, 默认是相对于"/" )

@param({"arg1","123"})

指定方法被调用时,字符串常量"123"将被作为参数$arg1

@return

声明方法的返回

如果不声明@return, 将把方法的返回值作为http的body输出,输出时,数组将被json_encode成字符串

输出可以支持变量($开头)和常量(不以$开头)

可选

示例:

@return({"output_func", "$arg1","$arg2"...})

将通过output_func输出,output_func的两个参数分别是方法的参数$arg1,$arg2.$arg1,$arg2必须是引用参数

@return({"body"})

输出body, 将方法的返回值作为http的body输出

@return({"body", "$arg0"})

输出body, 取方法的$arg0参数（必须是引用参数）作为http的body输出

@return({"cookie", "$name", "$value", "$expire" })

输出cookie, 参数形式参考 setcookie ( string $name [, string $value [, int $expire = 0 [, string $path [, string $domain [, bool $secure = false [, bool $httponly = false ]]]]]] )

@return({"header", "$name", "$value", "$expire" })

输出header,参数形式参考void header ( string $string [, bool $replace = true [, int $http_response_code ]] )

@return({"status", "200 OK" })

输出http status code

@return({"res", "200 OK", {"res":"ok"} })

输出http status code + body

@throws

声明方法的异常, 声明后的, 方法如果抛出异常, 将被捕获

不要去尝试捕获所有异常, 原则上内部错误的异常都不要捕获, 只有如验证失败, 参数错误等外部异常, 需要根据异常指定不同的http status, 如"400 Bad Request"

可选

示例:

@throws({"MyException","output_fun", "arg0", "arg1"})

如果捕获MyException异常, 则通过output_fun输出,output_fun的参数是arg0, arg1. 支持的输出方式与@return一致.

匹配异常的规则时,如果有完全匹配的异常(异常类一样), 则只执行完全匹配的异常, 否则匹配异常的父类

@throws({"NotFoundException", "status", "404 Not Found"})

如果匹配异常NotFoundException, 则status输出404 Not Found

@cache

声明方法的结果是否缓存, 下次收到同样的输入参数时, 不执行此方法, 而是直接返回

可选

示例:

@cache({"ttl", 3600}))

使用缓存, 且缓存的有效期是3600秒

@cache({"check", "$check"}))

使用缓存, $check是方法的变量(通过引用返回),缓存的过期通过调用$check($data, $create_time)判断, 返回false表示过期, 如$check = newFileExpiredChecker('file.tmp'); 通过判断file.tmp是否修改, 判断缓存是否过期.

框架默认使用apc缓存，可以通过配置文件指定其他缓存方式如：

{
    ...

    "tinyESB\\rsapi\\Invoker": {
        "properties": {
        "cache":"@invokeCache"// 1.指定接口调用使用的缓存实例
        }
    },
     //缓存实例的配置
    "invokeCache":{
        "class":"utils\\RedisCache",
        "singleton":true,
        "properties":{
            "serialize":true,
            "host":"127.0.0.1",
            "port":"6379"
        }
    },

    ...
}

属性注释

在方法的属性中声明的注释

@property

注入属性, 在创建类时(构造函数调用之前), 由IoCFactory从配置文件中读取, 注入实例.

属性会在__construct之前被注入，所以可以在__construct中访问被注入的属性。

可选

示例:

/** @property */
private $name;

$name是一个属性, 且是必须被注入的

/** @property */
private $name='value';

$name是一个属性, 可选, 有默认值

/** @property({"optional":true}) */
private $name;

$name是一个属性, 可选, 没有默认值

@inject

注入框架的内部接口作为类的依赖

可选

示例:

/** @inject("$.path[0]") */
private $app_name;

/** @inject("$.factory") 注入创建该实例的工厂实例*/
private $factory; 

与方法的参数注入类似, 但不同的是, 属性会在类实例化的时候就注入