Api - APIPHP开源框架

>i 本文档的最新修订日期是： > **2023-10-13** # Api :: 输出接口响应或报错。 # 依赖本模块依赖于基础模块 `Log` 。 # 模块配置配置文件位于 `/config/core/Api.php` 。 * **`template`** `(Array)` `~` ：用以指定响应的内容模板。值为一个数组，将在输出响应时作为响应内容的模板，最终以JSON形式展现。 * **`wrong`** `(Array)` `~` ：有关报错的配置项集合。 * **`style`** `(Array)` `~` ：用以指定将配置项 `template` 数组中的哪些元素替换为仅在报错时才会出现的内容，或新增仅在报错时才会响应的内容。值为一个数组，如果配置项 `template` 数组中存在与之相同键名的元素，那么报错时该元素的值将会被替换为新指定的值。如果不存在与之相同键名的元素，那么报错时该元素将会出现在报错的响应内容中。元素的值如果包含字符串 `{info}` ，那么该字符串会被替换为报错的错误内容。元素的值如果包含字符串 `{code}` ，那么该字符串会被替换为报错的错误代码。元素的值如果包含字符串 `{time}` ，那么该字符串会被替换为Float型的时间戳。元素的值如果为 `{stack}` ，那么该元素的值会被替换为错误堆栈。 >w 以上替换对多维数组的子元素无效 * **`log`** `(String)` `'SFAU'` ：用以指定哪些等级的错误需要提交进日志缓存中，可选的值如下值中的一个或多个： ``` S | F | A | U ``` 当值的字符串包含 `S` 时，代表错误为脚本级（Script），此类错误由PHP代码运行出错引发，例如语法错误、使用了一个未定义的变量等。当值的字符串包含 `F` 时，代表错误为框架级（Framework），此类错误由框架报错引发，例如调用的模块方法不存在等，可在文档 `错误码` 中了解错误的类型和原因。当值的字符串包含 `A` 时，代表错误为应用级（Application），此类错误由业务侧引发，例如下发短信验证码或实名认证时远程的接口没有响应、回调远程接口失败等。当值的字符串包含 `U` 时，代表错误为用户级（User），此类错误由用户侧引发，例如Token过期、鉴权错误、请求了一个不存在的数据等。 * **`respond`** `(String)` `'U'` ：用以指定哪些等级的错误可以被输出。当 `调试模式` 开启时，所有等级的报错都将输出。取值的规则与上一个配置项 `log` 相同。 * **`replace`** `(Array)` `[]` ：用以将代码中已定义的错误码替换为新的错误码。值为一个一维数组，数组的 `键` 为需要被替换的代码，`值` 为替换后的错误代码。 * **`ignore`** `(Array)` `[]` ：用以指定当出现哪些关键字时，忽略错误（不进行任何处理，亦不影响代码执行）。值为一个一维数组，数组的 `值` 为用于忽略错误的关键字（大小写敏感）。 # respond() ## 说明 **Api :: respond ( <kbd>传参数组</kbd> )** 输出接口响应。此方法 `支持` 中文参数名。 ## 参数 * **`log（日志）`** `(Bool)` `FALSE`：用以指定是否将输出的响应以 `info` 级别提交到日志缓存中。 `TRUE` 代表提交到日志、`FALSE` 代表不提交到日志，默认不提交到日志。日志缓存是否会被写入日志文件，取决于 `Log` 模块的相关配置。 * **`http（响应码）`** `(Int)` `200`：用以指定输出响应时的HTTP状态码。 * **`content（内容）`** `(Array)` `~` ：用以指定将配置项 `Template` 数组中的哪些元素替换为新的内容，或向其新增内容。值为一个数组，如果配置项 `Template` 数组中存在与之相同键名的元素，那么该元素的值将会被替换为新指定的值。如果不存在与之相同键名的元素，那么该元素将会出现在输出的响应内容中。 # wrong() ## 说明 **Api :: wrong ( <kbd>传参数组</kbd> )** 清除已输出的内容并输出报错，同时中断代码运行。此方法 `支持` 中文参数名。此方法 `支持` 参数简写。 ## 参数 * **`detail（详情）`** `(String)` `<必须>` `可简写`：报错的详细信息。 * **`code（错误码）`** `(Int)` `0`：错误码，默认为 `0` 。 * **`stack（堆栈）`** `(Bool)` `FALSE`：用以指定是否在报错信息中展示错误堆栈。 * **`log（日志）`** `(Bool)` `TRUE`：用以指定是否将报错提交到日志缓存中。 `TRUE` 代表提交到日志、`FALSE` 代表不提交到日志，默认提交到日志。日志缓存是否会被写入日志文件，取决于本模块配置项中指定的日志记录等级，还取决于 `Log` 模块的相关配置。 * **`http（响应码）`** `(Int)` `200`：用以指定报错时的HTTP状态码。 * **`level（级别）`** `(String)` `'A'`：用以指定错误的等级，可选的值如下： ``` A | U ``` 取值为 `A` 时，代表错误为应用级（Application），此类错误由业务侧（应用内部）引起，例如下发短信验证码或实名认证时远程的接口没有响应、回调远程接口失败等。取值为 `U` 时，代表错误为用户级（User），此类错误由用户侧引起，例如Token过期、鉴权错误、请求了一个不存在的数据等。 >d 请勿在本参数中使用值 `S（脚本级，Script）` 和 `F（框架级，Framework）` ，避免混淆错误等级。 ## 返回无。 ## 示例进行报错并展现错误详情： ```php Api::wrong(['detail'=>'用户尚未登录','code'=>'032']); ```