-
Notifications
You must be signed in to change notification settings - Fork 15
/
Api.php
321 lines (283 loc) · 8.96 KB
/
Api.php
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
<?php
namespace PhalApi;
use PhalApi\Exception\BadRequestException;
use PhalApi\Exception\InternalServerErrorException;
/**
* Api 接口服务基类
*
* - 实现身份验证、按参数规则解析生成接口参数等操作
* - 提供给开发人员自定义的接口服务具体类继承
*
* <br>通常地,可以这样继承:<br>
*
```
* class MyApi extends Api {
*
* public function getRules() {
* return array(
* // ...
* );
* }
*
* public function doSth() {
* $rs = array();
*
* // ...
*
* return $rs;
* }
* }
```
*
* @property mixed $whatever 接口参数
* @package PhalApi\Api
* @license http://www.phalapi.net/license GPL 协议 GPL 协议
* @link http://www.phalapi.net/
* @author dogstar <chanzonghuang@gmail.com> 2014-10-02
*
* @exception 400 表示客户端参数错误
* @exception 404 表示接口服务不存在
* @exception 500 表示服务端内部错误
*/
class Api {
/**
* @var boolean $__apiIsServiceWhitelist 是否为白名单服务
*/
private $__apiIsServiceWhitelist;
/**
* 设置规则解析后的接口参数
* @param string $name 接口参数名字
* @param mixed $value 接口参数解析后的值
*/
public function __set($name, $value) {
$this->$name = $value;
}
/**
* 获取规则解析后的接口参数
* @param string $name 接口参数名字
* @throws PhalApi\Exception\InternalServerErrorException 获取未设置的接口参数时,返回500
* @return mixed
*/
public function __get($name) {
if(!isset($this->$name) || empty($name)) {
throw new InternalServerErrorException(
T('Api::${name} undefined', array('name' => $name))
);
}
return $this->$name;
}
/**
* 初始化
*
* 主要完成的初始化工作有:
* - 1、[必须]按参数规则解析生成接口参数
* - 2、[可选]过滤器调用,如:签名验证
* - 3、[可选]用户身份验证
*
* @uses Api::createMemberValue()
* @uses Api::filterCheck()
* @uses Api::userCheck()
* @return null
*/
public function init() {
$this->checkRequestMethod();
$this->createMemberValue();
$this->filterCheck();
$this->userCheck();
}
/**
* 检测请求方式
*
* 根据接口方法@method注解,判断请求方式
*
* @throw \PhalApi\Exception\BadRequestException
*/
protected function checkRequestMethod() {
$action = \PhalApi\DI()->request->getServiceAction();
try {
$rMethod = new \ReflectionMethod($this, $action);
} catch (\ReflectionException $ex) {
return;
}
$commentArr = explode("\n", $rMethod->getDocComment());
foreach ($commentArr as $comment) {
$comment = trim($comment);
$pos = stripos($comment, '@method');
if ($pos !== FALSE) {
if (isset($_SERVER['REQUEST_METHOD']) && stripos($comment, ' ' . $_SERVER['REQUEST_METHOD']) === FALSE) {
throw new BadRequestException(
T('request method not allowed, only {method}', array('method' => substr($comment, $pos + 8))), 4
);
}
break;
}
}
}
/**
* 按参数规则解析生成接口参数
*
* 根据配置的参数规则,解析过滤,并将接口参数存放于类成员变量
*
* @uses Api::getApiRules()
*/
protected function createMemberValue() {
foreach ($this->getApiRules() as $key => $rule) {
$this->$key = DI()->request->getByRule($rule);
}
}
/**
* 取接口参数规则
*
* 主要包括有:
* - 1、[固定]系统级的service参数
* - 2、应用级统一接口参数规则,在app.apiCommonRules中配置
* - 3、接口级通常参数规则,在子类的*中配置
* - 4、接口级当前操作参数规则
*
* <b>当规则有冲突时,以后面为准。另外,被请求的函数名和配置的下标都转成小写再进行匹配。</b>
*
* @uses Api::getRules()
* @return array
*/
public function getApiRules() {
$rules = array();
$allRules = $this->getRules();
if (!is_array($allRules)) {
$allRules = array();
}
$allRules = array_change_key_case($allRules, CASE_LOWER);
$action = strtolower(DI()->request->getServiceAction());
if (isset($allRules[$action]) && is_array($allRules[$action])) {
$rules = $allRules[$action];
}
if (isset($allRules['*'])) {
$rules = array_merge($allRules['*'], $rules);
}
$apiCommonRules = $this->getApiCommonRules();
if (!empty($apiCommonRules) && is_array($apiCommonRules)) {
// fixed issue #22
if ($this->isServiceWhitelist()) {
foreach ($apiCommonRules as &$ruleRef) {
$ruleRef['require'] = false;
}
}
$rules = array_merge($apiCommonRules, $rules);
}
// 过滤置为空的参数规则 @dogstar 20191215
foreach ($rules as $key => $rule) {
if ($rule === NULL || $rule === FALSE) {
unset($rules[$key]);
}
}
return $rules;
}
/**
* 获取应用参数设置的规则
*
* 默认情况下读取app.apiCommonRules配置,可根据需要进行重载
*
* @return array
*/
protected function getApiCommonRules() {
return DI()->config->get('app.apiCommonRules', array());
}
/**
* 获取参数设置的规则
*
* 可由开发人员根据需要重载
*
* @return array
*/
public function getRules() {
return array();
}
/**
* 过滤器调用
*
* 可由开发人员根据需要重载,以实现项目拦截处理,需要:
* - 1、实现Filter::check()接口
* - 2、注册的过滤器到DI()->filter
*
* <br>以下是一个简单的示例:<br>
```
* class MyFilter implements Filter {
*
* public function check() {
* //TODO
* }
* }
*
*
* //在初始化文件 init.php 中注册过滤器
* DI()->filter = 'MyFilter';
```
*
* @see Filter::check()
* @throws PhalApi\Exception\BadRequestException 当验证失败时,请抛出此异常,以返回400
*/
protected function filterCheck() {
// 过滤服务白名单
if ($this->isServiceWhitelist()) {
return;
}
$filter = DI()->get('filter', '\\PhalApi\\Filter\\NoneFilter');
if (isset($filter)) {
if (!($filter instanceof Filter)) {
throw new InternalServerErrorException(
T('DI()->filter should be instanceof \PhalApi\Filter'));
}
$filter->check();
}
}
/**
* 用户身份验证
*
* 可由开发人员根据需要重载,此通用操作一般可以使用委托或者放置在应用接口基类
*
* @throws PhalApi\Exception\BadRequestException 当验证失败时,请抛出此异常,以返回400
*/
protected function userCheck() {
}
/**
* 是否为白名单的服务
*
* @return boolean
*/
protected function isServiceWhitelist() {
// 缓存返回,避免重复计算
if ($this->__apiIsServiceWhitelist !== NULL) {
return $this->__apiIsServiceWhitelist;
}
$this->__apiIsServiceWhitelist = FALSE;
$di = DI();
$api = $di->request->getServiceApi();
$action = $di->request->getServiceAction();
$namespace = $di->request->getNamespace();
// 优先命名空间的单独白名单配置,再到公共白名单配置
$serviceWhitelist = $di->config->get('app.service_whitelist.' . $namespace);
$serviceWhitelist = $serviceWhitelist !== NULL
? $serviceWhitelist : $di->config->get('app.service_whitelist', array());
foreach ($serviceWhitelist as $item) {
$cfgArr = is_string($item) ? explode('.', $item) : array();
if (count($cfgArr) < 2) {
continue;
}
// 短路返回
if ($this->equalOrIngore($api, $cfgArr[0]) && $this->equalOrIngore($action, $cfgArr[1])) {
$this->__apiIsServiceWhitelist = TRUE;
break;
}
}
return $this->__apiIsServiceWhitelist;
}
/**
* 相等或忽略
*
* @param string $str 等判断的字符串
* @param string $cfg 规则配置,*号表示通配
* @return boolean
*/
private function equalOrIngore($str, $cfg) {
return strcasecmp($str, $cfg) == 0 || $cfg == '*';
}
}