Api

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