如何设计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();
posted @ 2016-07-19 13:55  52php  阅读(...)  评论(... 编辑 收藏