3.8.1

2022-03-21 11:16:38 +08:00
commit e89e807c64
1040 changed files with 284164 additions and 0 deletions
--- a/public/wiki/2x-how-to-use-api.md
+++ b/public/wiki/2x-how-to-use-api.md
@@ -0,0 +1,164 @@
+# 如何调用接口
+
+以下将通过简明的方式，介绍客户端如何调用接口。 
+
+## API入口
+假设您的域名是：http://open.phalapi.net，则：  
+
+ + App开放接口API入口：http://open.phalapi.net/api/app.php 
+ + Platform开放平台接口API入口：http://open.phalapi.net/api/app.php 
+ + Admin管理后台接口API入口：http://open.phalapi.net/api/admin.php
+ + Task计划任务接口API入口：http://open.phalapi.net/api/admin.php
+
+首先，不同系列的接口，必须要找到对应的API入口。因为不同的入口处理的方式、权限判断和场景都不相同，并且方便分别进行个性化控制而不相互影响。  
+
+## 请求方式
+
+通过HTTP/HTTPS协议，便可以请求接口。  
+
+例如对于默认的接口服务：http://open.phalapi.net/api/app.php?s=App.HelloWorld.Say，直接用浏览器打开访问，可以得到结果：  
+```
+{
+  "ret": 200,
+  "data": {
+    "content": "Hello PhalApi Pro!"
+  },
+  "msg": ""
+}
+``` 
+
+如果通过CURL方式请求，则结果为：  
+```
+$ curl http://open.phalapi.net/api/app.php\?s\=App.HelloWorld.Say
+{"ret":200,"data":{"content":"Hello PhalApi Pro!"},"msg":""}
+```
+
+通常情况下，可以使用GET或POST方式请求接口，但推荐使用POST方式请求接口。原因有几点： 
+ + 1、GET方式容易存在编码问题导致参数解析失败，但POST方式不会；
+ + 2、GET参数有最大长度限制，当GET参数过长过大时会提示错误，但POST方式不会；
+ + 3、GET方式容易被抓包或在服务器存在日志，容易导致密码等敏感信息泄露，POST方式相对安全。
+
+## 指定接口
+
+和PhalApi开源版一样，通过```s```参数（完整参数名是```service```，两者等效），可以指定调用哪一个接口服务。  
+
+关于全部的接口，可以通过在线接口文档查看。当未指定接口时，默认接口服务是```App.Site.Index```。  
+
+例如：  
+```
+# 请求默认接口
+http://open.phalapi.net/api/app.php
+
+# 请求会员注册接口
+http://open.phalapi.net/api/app.php?s=App.User.Register
+
+# 请求获取文件列表接口（需要切换到后台API入口）
+http://open.phalapi.net/api/admin.php?s=Admin.File.GetList
+```
+
+需要注意的是，不同接口的访问入口不同，需要注意区分。
+
+## 请求参数
+
+如你所见，s或service参数用于指定接口服务。除此之外，公共的接口参数目前有：  
+
+ + access_token：token令牌，用于接口验证，后面会继续讲解。
+
+每个接口的参数，可以通过接口文档查看，例如：  
+![](http://cdn7.okayapi.com/yesyesapi_20191230174817_d87cba5494b0d5c6902ee328bcb660bd.png)
+
+如无特殊说明，接口参数均可使用GET或POST。  
+
+## 返回结构
+
+如前文所述，以及遵循PhalApi开源版的格式，接口返回的是JSON格式。例如：  
+```
+{"ret":200,"data":{"title":"Hello PhalApi Pro","version":"1.0","time":1577697960},"msg":""}
+```
+格式后是：  
+```
+{
+    "ret": 200,
+    "data": {
+        "title": "Hello PhalApi Pro",
+        "version": "1.0",
+        "time": 1577697960
+    },
+    "msg": ""
+}
+```
+
+全部接口，返回的接口结果结构分为三部分：  
+
+ + ret：状态码，整型，200表示成功，4xx表示客户端非法请求，5xx表示服务器错误
+ + data：成功时返回的业务数据，通常为对象类型，具体由接口服务而定
+ + msg：失败时的错误提示信息，字符类型
+
+具体每个接口返回的结果，可以访问接口文档，查看指定接口服务文档的**返回结果**说明。例如：  
+![](http://cdn7.okayapi.com/yesyesapi_20200107145823_36980567e0ed1b9f416676abe3575b5c.png)
+
+也可以查看接口返回示例：  
+![](http://cdn7.okayapi.com/yesyesapi_20191230174538_fb50beb5aefb933567ff7654635d967f.png)
+
+
+## 验证方式
+
+PhalApi专业版使用的是access_token令牌验证的方式，在开始使用接口时，需要先申请令牌。申请令牌有两种方式：  
+
+ + 方式一：通过应用来申请令牌：根据开发者应用的app_key和app_secret申请access_token令牌
+ + 方式二：通过会员来申请令牌：结合已获得的应用access_token令牌，根据会员账号和密码进行登录并获取新的access_token令牌
+  
+
+## 获取令牌
+
+### 方式一：通过应用来申请令牌
+
+这种方式，要求：  
+
+ + 应用存在：首先需要创建应用，并且审核通过
+ + 密钥正确：应用app_key和app_secret正确
+ + 正常状态：应用处于正常状态（若为禁用则不可用）
+ + 接口权限：应用在调用指定接口时需要拥有相应接口的权限
+
+需要使用的接口是：```App.Auth.ApplyToken```。  
+
+### 方式二：通过会员登录来申请令牌
+
+方式二，要求：  
+
+ + 注册账号：已经有注册的会员账号
+ + 密码正确：会员账号和密码正确
+ + 正常状态：会员处于正常状态（若为禁用则不可登录）
+ + 指定应用：通过方式一获得有有效令牌
+
+需要使用的接口是：```App.User.UserLogin```。  
+
+通过access_token参数传递成功申请到的令牌，若令牌过期或无效，接口将会返回ret=406，例如：  
+```
+{
+    "ret": 406,
+    "data": {},
+    "msg": "非法请求：access_token校验不通过"
+}
+```
+若令牌有效，则可以正常请求接口。  
+
+## 刷新令牌
+
+令牌过期时间默认为30天，可以通过./config/app.php配置文件的jwt里的exp来自行修改，如设置为7天：  
+```
+/**
+ * JWT令牌
+ */
+'jwt' => array(
+        'key' => '1j7zo53mnsLK', // 用于加密的key（安装时自动生成，不能修改！）
+        'exp' => 7 * 86400, // 令牌生成后多少秒内有效，可自行修改
+),
+```
+在令牌过期前，可以通过```App.Auth.RefreshAccessToken```接口刷新令牌，从而延长有效期。刷新后有效期会重新延长到jwt里面exp指定的时间。  
+
+## 开放平台与管理后台的身份校验
+
+对于内部，可以通过登录开发者账号，或者通过登录管理员账号来获得令牌。此时使用的接口是```Platform.User.UserLogin```。
+
+