如何设计PHP业务模块（函数/方法）返回结果的结构？
如题：如何设计业务模块返回结果的结构？
一个业务函数/方法执行后，对外输出数据的结构通常有以下几种：
1、返回数字，如 成功时返回 0，失败时返回 -1，有的还会用一个全局变量输出错误信息：
<?php
class UserLogic extends \Think\Model {
protected $error;
/**
* 更改用户名称
*
* @param int $userId 用户ID
* @param string $userName 用户名
* @return int -1: 操作失败, 0: 操作成功
*/
public function updateUserName($userId = 0, $userName = '') {
if (empty($userId)) {
$this->error = '用户ID不能为空';
return -1;
}
if (empty($userName)) {
$this->error = '用户名不能为空';
return -1;
}
$where = array(
'userId' => $userId
);
$data = array(
'userName' => $userName
);
$res = $this->where($where)->save($data);
if ($res !== false) {
return 0;
}
return -1;
}
}
2、返回 bool 值，如成功时返回 true，失败时返回 false。
例子跟上面的差不多，这里就不写了。
3、抛出异常
可以使用类似以下代码抛出异常：
throw new \Exception('用户ID不能为空');
更详细的 PHP 抛出异常，可以阅读先前的文章：PHP中的错误处理、异常处理机制详解
不过，我不建议在 业务函数中，使用 throw new \Exception('xxx') 方式抛出异常，在一些基础框架中使用它比较合适，比如：
(1).文件不存在时；
(2).类不存在时；
(3).方法/函数名不存在时；
(4).数据库连接失败时；
等等情况。
4、返回一个数组结构，如
<?php
class UserLogic extends \Think\Model {
/**
* 更改用户名称
*
* @param int $userId 用户ID
* @param string $userName 用户名
* @return array
*/
public function updateUserName($userId = 0, $userName = '') {
$return = array(
'code' => 0, // 状态码, 0: 操作失败, 1: 操作成功
'msg' => '操作失败', // 消息语
'data' => array() // 如果需要, 可以附带数据
);
if (empty($userId)) {
$return['msg'] = '用户ID不能为空';
return $return;
}
if (empty($userName)) {
$return['msg'] = '用户名不能为空';
return $return;
}
$where = array(
'userId' => $userId
);
$data = array(
'userName' => $userName
);
$res = $this->where($where)->save($data);
if ($res !== false) {
$return['code'] = 1;
$return['msg'] = '操作成功';
}
return $return;
}
}
5、返回一个类实例：
上面返回一个统一的数组结构，我还是蛮喜欢的，在项目中，也使用过一段时间，
但是，越来越发现，在每个函数开头，都要事先写个 $return 数组结构，还是挺麻烦的。
$return = array( 'code' => 0, // 状态码, 0: 操作失败, 1: 操作成功 'msg' => '操作失败', // 消息语 'data' => array() // 如果需要, 可以附带数据 );
我们可以改造下，让它面向对象化。
首先，定义一个 业务操作结果类：Result.class.php
<?php
namespace Think;
/**
* 业务操作结果类
*
* @package Think
* @autor 52php.cnblogs.com
*/
Class Result {
public $code = ''; // 状态码: success-成功, fail-失败
public $msg = ''; // 消息
public $data = array(); // 数据
/**
* 实例化
*/
public static function instance() {
return new self();
}
/**
* 设置 状态码
*
* @param string $code 状态码
* @return $this
*/
public function code($code = null) {
!is_null($code) && ($this->code = $code);
return $this;
}
/**
* 设置 消息
*
* @param string $msg 消息
* @return $this
*/
public function msg($msg = null) {
!is_null($msg) && ($this->msg = $msg);
return $this;
}
/**
* 设置 数据
*
* @param array $data 数据
* @return $this
*/
public function data($data = null) {
!is_null($data) && ($this->data = $data);
return $this;
}
/**
* 成功
*
* @param string $msg 消息
* @param array $data 数据
* @return $this
*/
public function success($msg = null, $data = null) {
$this->code = 'success';
is_null($msg) && ($this->msg === '') && ($this->msg = '操作成功');
!is_null($msg) && ($this->msg = $msg);
!is_null($data) && ($this->data = $data);
return $this;
}
/**
* 失败
*
* @param string $msg 消息
* @param array $data 数据
* @return $this
*/
public function fail($msg = null, $data = null) {
$this->code = 'fail';
is_null($msg) && ($this->msg === '') && ($this->msg = '操作失败');
!is_null($msg) && ($this->msg = $msg);
!is_null($data) && ($this->data = $data);
return $this;
}
/**
* 是否为 成功
*/
public function isSuccess() {
return ($this->code == 'success') ? true : false;
}
/**
* 是否为 失败
*/
public function isFail() {
return ($this->code != 'success') ? true : false;
}
/**
* 输出 (json数据)
*/
public function output() {
header('Content-type:text/json');
$res = array(
'code' => $this->code,
'msg' => $this->msg,
'data' => $this->data,
);
if (isset($_REQUEST['jsoncallback'])) {
echo $_REQUEST['jsoncallback'] . '(' . json_encode($res) . ')';
} else {
echo json_encode($res);
}
die();
}
}
这样，每个业务函数，统一输出 Result 类实例，一个业务函数调用另外一个或多个业务函数时，处理 业务异常 非常方便！
应用举例：
(1).业务模型中
<?php
namespace Common\Model;
use Think\Model;
use Think\Result;
class UserLogic extends Model {
/**
* 更改用户名称
*
* @param int $userId 用户ID
* @param string $userName 用户名
* @return Result
*/
public function updateUserName($userId = 0, $userName = '') {
if (empty($userId)) {
return Result::instance()->msg('用户ID不能为空')->fail();
}
if (empty($userName)) {
return Result::instance()->msg('用户名不能为空')->fail();
}
$where = array(
'userId' => $userId
);
$data = array(
'userName' => $userName
);
$res = $this->where($where)->save($data);
if ($res !== false) {
return Result::instance()->msg('操作成功')->success();
}
return Result::instance()->msg('操作失败')->fail();
}
}
(2).控制器中
<?php
namespace Common\Model;
use Think\Controller;
class UserController extends Controller {
/**
* 更改用户名称
*/
public function updateUserName() {
$userId = I('REQUEST.userId');
$userName = I('REQUEST.userName');
// "开启" 事务
D('User')->startTrans();
$result = D('User', 'Logic')->updateUserName($userId, $userName);
if ($result->isSuccess()) {
// "提交" 事务
D('User')->commit();
} else {
// "回滚" 事务
D('User')->rollback();
}
// 输出 API 的 json 结果 (主要是给 移动端 提供接口)
$result->output();
}
}
API返回的结果结构如下：
{
"code":"success",
"msg":"操作成功",
"data":[]
}
如何定义 API 输出结果的结构？
可以先阅读下文章：App架构设计经验谈：服务端接口的设计
一般也是定义一个统一的结构，如：
{
"code"："0",
"msg": "success",
"data": { "key1": "value1", "key2": "value2", ... }
}
很多人对这个“统一的输出结构”还是挺喜欢的，但是又发现他们对这个 code 值的设计 或 理解 或 使用 又是不对的。业界也没有统一的规则，所以比较乱象。
比如说，定义“code=400”，表示 “验证失败”，开发人员只要遇到“验证失败”的情况，统统返回 code=400 的错误状态码，
如：“用户不存在时”返回 code=400，“开始时间大于结束时间”也返回 code=400，“评论的内容不能为空”也返回 code=400，这样的设计和使用都是不对的。
如果非要把 code 的值设计为编码（一串数字，或一串数字和字母的组合）的话，它具有两层含义，一方面代表“状态码”，是成功还是失败，另一方面代表“错误码”，哪里出错了，出什么错。
同时，它还应该具有以下特性：
(1).唯一性
即一个编码代表具体的某个异常，如果 用 “code=400” 表示“评论的内容不能为空”的异常，就不能用“code=400”表示 “开始时间大于结束时间”的异常。
(2).多语言性
官方只需要对这个code错误码用一种语言（如英文）来描述错误详情，不同的开发使用者可以根据自己平台的需要，把这个错误信息（依据code）翻译成其他语言，如 中文，俄文等等。
(3).模块性
比如，用1开头的code值，表示某个模块里抛出的异常，用2开头的code值，表示另外一个模块抛出的异常。
可以参考下各大平台对 code 值的设计：
1、微信公众号
http://mp.weixin.qq.com/wiki/10/6380dc743053a91c544ffd2b7c959166.html
2、开心网
http://wiki.open.kaixin001.com/index.php?id=%E9%94%99%E8%AF%AF%E4%BB%A3%E7%A0%81%E9%87%8A%E4%B9%89
最后的建议：
如果你的项目不是“开放平台”类型（自己内部使用），再加上项目开发时间又比较紧，一时又没想好如何规划code值的时候，建议 code 只定义为 2 个值，成功时返回为“success”，失败时返回为“fail”。不要使用“true”和“false”，因为它们是各个开发语言的关键字，避免不必要的麻烦。
后记：
对旧项目的“返回一个数组结构”的业务模块接口，做了个小调整：
封装了一个函数，方便初始化，如：
<?php
/**
* 创建 业务函数/方法的（统一的）返回结构
*
* @param int $code 状态码 0-操作失败，1-操作成功
* @param string $msg 消息语
* @param array $data 返回数据
* @return array
*/
function core_return($code = 0, $msg = '操作失败', $data = array()) {
return array(
'code' => $code,
'msg' => $msg,
'data' => $data
);
}
业务函数中，可这样初始化
$return = core_return();
