统一的返回格式和结构：ret data msg.pdf

统⼀的返回格式和结构：ret data msg 表达，从简单开始。-- 《Robin Williams ：写给⼤家看的设计书》 1.14.1 统⼀返回的格式 很明显地，默认情况下，我 选择了 JSON 作为统⼀的格式返回接⼜结果。这⾥简单 说明⼀下选取JSON统⼀返回的原因： JSON当前很流⾏，且普通接⼜都采⽤此格式返回 JSON在绝⼤部分开发语⾔中都⽀持，跨语⾔ JSON在浏览器浏览时，有可视化插件⽀持，如FF下： 1.14.2 统⼀返回结构 通常，我 正常情况下请求接⼜会返回类似： { ret: 200, data: { title: Default Api, content: PHPer您好，欢迎使⽤PhalApi！, version: 1.1.0, time: 142 142802 }, msg: } 其中，ret表⽰为返回状态码，200表⽰成功；data为领域业务数据，由接⼜⾃定义；最 后msg为错误的提⽰信息。下⾯分别解释之。 (1)返回状态码 ret 参照HTTP的状态码，特约定： 200 ：接⼜正常请求并返回 4XX ：客户端⾮法请求 5XX ：服务器运⾏错误 200 正常返回 当返回200 时，需要同时返回data部分数据，以便客户端实现所需要的业务功能。 4XX 客户端⾮法请求 此类请求是由客户端不正确调⽤引起的，如请求的接⼜服务不存在，或者接⼜参数不 对，验证失败等等。当这种情况发⽣时，客户端同学只需要调整修正调⽤即可。 对于此系统的状态码，在进⾏接⼜开发时，可由项⽬⾃已定义约定。 通常地，我 需 要告知客户端签名失败时，可以这样： throw new PhalApi_Exception_BadRequest(wrong sign, 1); 即抛出PhalApi_Excepti n_BadRequest异常即可，错误信息会返回客户端，对应msg字 段；状态为1，系统对此类的异常会在400基础上相加的，即： 401 = 400 + 1 。 5XX 服务器运⾏错误 此类错误是应该避免的，但当客户端发现有这种情况时，应该知会后台接⼜开发⼈员 进⾏修正。 如当配置的参数规则不符合要求时，或者获取了不存在的参数等即会触发此类异常错 误，通常由框架抛出。 (2)业务 据 data data为接⼜和客户端主要沟通对接的数据部分，可以为任何类型，由接⼜⾃定义。但 为了更好地扩展、向后兼容，建议都使⽤array 。 返回格式的定义与在线查看 当我 在开发接⼜时，可以通过为接⼜添加注释的⽅式来定义接⼜的返回格式，然后 就可以为外部提供在线⽂档的实时查看了。 如： ?php class Api_User extends PhalApi_Api { /** * 获取⽤户基本信息 * @desc ⽤于获取单个⽤户基本信息 * @return int code 操作码，0表示成功，1表示⽤户不存在 * @return object info ⽤户信息对象 * @return int info.id ⽤户ID * @return string ⽤户名 * @return string info.note ⽤户来源 * @return string msg 提示信息 */ public function getBaseInfo() { // ... ... } 然后在浏览器访问： http://dem .phalapi .net/checkApiParams.php?service=User .getBaseInf 可以看到： 注释格式 格式是以d cs的 return 注释来标明的，其格式为： @return 返回的类型 段名 路径(以点号连接) 段名 及解析 其中，返回的类型可以为： 关键字 说明 string 字符串 int 整型 fl at 浮点型 b lean 布尔型 date ⽇期 array 数组 fixed 固定值 enum 枚举类型 bject 对象 温馨提⽰：array与 bj