统一的返回格式和结构：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“: 1423142802},“msg“: ““ }其中，ret表⽰为返回状态码，200表⽰成功；data为领域业务数据，由接⼜⾃定义；最 后msg为错误的提⽰信息下⾯分别解释之1)返回状态码 ret参照HTTP的状态码，特约定：200：接⼜正常请求并返回 4XX：客户端⾮法请求 5XX：服务器运⾏错误200 正常返回当返回200时，需要同时返回data部分数据，以便客户端实现所需要的业务功能。

4XX 客户端⾮法请求此类请求是由客户端不正确调⽤引起的，如请求的接⼜服务不存在，或者接⼜参数不 对，验证失败等等当这种情况发⽣时，客户端同学只需要调整修正调⽤即可对于此系统的状态码，在进⾏接⼜开发时，可由项⽬⾃已定义约定 通常地，我们需 要告知客户端签名失败时，可以这样：throw new PhalApi_Exception_BadRequest('wrong sign', 1);即抛出PhalApi_Exception_BadRequest异常即可，错误信息会返回客户端，对应msg字 段；状态为1，系统对此类的异常会在400基础上相加的，即： 401 = 400 + 1 5XX 服务器运⾏错误此类错误是应该避免的，但当客户端发现有这种情况时，应该知会后台接⼜开发⼈员 进⾏修正 如当配置的参数规则不符合要求时，或者获取了不存在的参数等即会触发此类异常错 误，通常由框架抛出2)业务数据 datadata为接⼜和客户端主要沟通对接的数据部分，可以为任何类型，由接⼜⾃定义但 为了更好地扩展、向后兼容，建议都使⽤array返回格式的定义与查看当我们在开发接⼜时，可以通过为接⼜添加注释的⽅式来定义接⼜的返回格式，然后 就可以为外部提供⽂档的实时查看了。

如：response->addHeaders('Access-Control-Allow-Origin', '*');后⾯相同的头部信息会覆盖前⾯的1.14.3 关于Exception类异常没捕捉的原因我们没有对Exception类的异常进⾏捕捉，封装返回⾮200的形式，是因为我们出于以 下的考虑：⼀来为了⽅便开发过程中快速发现及定位具体出错的位置； ⼆来为了便于线上环境中nginx服务器对错误的捕捉和纪录；1.14.4 JsonP格式和其他的返回在部分H5页⾯异步请求的情况下，客户端需要我们返回JSONP格式的结果，则可以这 样在⼊⼜⽂件重新注册response：if (!empty($_GET['callback'])) {DI()->response = new PhalApi_Response_JsonP($_GET['callback' }但是在测试环境中，我们是不希望有内容输出的，所以我们可以测试时这样注册 response：DI()->response = 'PhalApi_Response_Explorer';1.14.5 扩展你的返回格式当你的项⽬需要返回其他格式时，如返回XML，则可以先这样实现你的格式类：class MyResponse_XML extends PhalApi_Response {protected function formatResult($result) {//TODO：把数组$result格式化成XML ...} }随后，也是简单重新注册⼀下即可：DI()->response = 'MyResponse_XML';1.14.6 各状态码产⽣的时机1.14.7 更好地建议很多时候，很多业务场景，客户端在完成⼀个接⼜请求并获取到所需要的数据后，需 要进⾏不同的处理的。

就登录来说，当登录失败时，可能需要知道： 是否⽤户名不存在？ 是否密码错误？ 是否已被系统屏蔽？ 是否密码错误次数超过了最⼤的重试次数？ ...显然，这⾥也有⼀个返回状态码，更准备来说，是业务操作状态码并且，此类的状态依接⼜不同⽽不同，很难做到统⼀SO？我们建议的是，项⽬接⼜在业务数据data⾥⾯统⼀再定义⼀个状态码，通常为code字 段，完整路径即： data.code ，同时为0时表⽰操作成功，⾮0时为不同的失败场景 如上⾯的登录：code = 0 登录成功 code = 1 ⽤户名不存在 code = 2 密码错误 code = 3 系统已屏蔽此账号 code = 4 密码错误次数超过了最⼤的重试次数 ...最后，客户端在获取到接⼜返回的数据后，先统⼀判断ret是否正常请求并正常返回， 即ret = 200；若是，则再各⾃判断操作状态码code是否为0，如果不为0，则提⽰相应 的⽂案并进⾏相应的引导，如果为0，则⾛正常流程！1.14.8 领域特定设计与Fiat标准在《RESTful Web APIs》⼀书中提及到，标准可以划归到4个分类，分别是：fiat标 准、个⼈标准、公司标准以及开放标准。

显然，我们这⾥推荐的是 JSON + ret-data-msg 返回格式既不是个⼈标准，也不是公 司标准（就笔者观察的范筹⽽⾔，未发现某个公司定义了此格式）⽽且，也不属于 开放标准，因为也还没达到此程度更多的，它是fiat标准 我们很容易发现，⾝边的应⽤、系统以及周围项⽬都在使⽤诸如此类的返回结构格 式，如⼀些AJAX的接⼜当然，我们可希望可以消除语义上的鸿沟，以便在后台接⼜开发上有⼀个很好地共 识同时，JSON + ret-data-msg 返回格式也是⼀种领域特定的格式，它更多是为app多端 获取业务数据⽽制作的规范虽然它不是很完美，不具备⾃描述消息，也没有资源链 接的能⼒，但我们认为它是⼀种恰到好处的格式 在基于JSON通⽤格式的基础上，加以 ret-data-msg 的约束，它很好地具备了统⼀ 性，可能门槛低，容易理解W3Cschool（）最⼤的技术知识分享与学习平台此篇内容来⾃于⽹站⽤户上传并发布。