关于接口规范（关于接口的使用,说法错误的是）

「to前端、后端」公司/团队要不断的累积组织过程资产，一方面提升产能和效率；一方面丰富内涵。

本次主要讲解接口规范，无论是做APP、小程序还是H5，都离不开接口，应该封装一个接口消息类，用户反馈消息。

一、接口规范

接口返回四个字段：result、ret、code、message，分别说明：

result：结果，代表逻辑上接口是否执行成功，举例来说，如果登录成功，那么返回true、如果登录失败，则返回false

code：错误码，例如200代表成功，901代表内部错误等，特殊说明，result和code搭配使用，确保前端可以有效处理问题。还是以登录为例，用户登录失败，result返回false，但登录失败的情况有很多中，例如code=1001代表手机号不存在，则要引导至注册页面；code=1002代表密码过程，则引导至重置密码等。

message：结果说明，！！注意，这个message是给技术人员看的，提供接口时搭配错误码表，但为了调试效率，一般后端输出接口的时候，会将code的含义放入message，所以如果code=200代表成功，则message放入“调用成功”，code=1001代表手机号不存在，则message放入“手机号不存在”。

ret：具体的返回报文，例如获取文章信息，那么文章信息应该防止在ret中。

二、接口样式

拿个实例来说明，下面为登录接口返回报文，则code=200代表登录成功，result=true代表接口逻辑调用成功，message为code的中文描述，ret为具体点的接口信息。

{
 "code": 200,
 "result": true,
 "message": "调用成功",
 "ret": {
 "id": 2401,
 "real_name": null,
 "nick_name": null,
 "avatar": null,
 "phonenum": null,
 "gender": "0",
 "status": "1",
 "type": "0",
 "token": "D0CD9D4AC37873787049BCCA5EF14CD5",
 "country": null,
 "province": null,
 "city": null,
 "language": null,
 "level": 0,
 "sign": null,
 "yq_num": 0,
 "rel_num": 0,
 "created_at": "2018-11-19 18:58:22",
 "updated_at": "2018-11-19 18:58:22",
 "deleted_at": null,
 "attach": {
 "openid": "o_EXq0Ieo4TO8FTp29TRQQugWM8Q",
 "session_key": "GiB4hk4mRQXks7OuxpTFEQ==",
 "busi_name": "ysb",
 "unionid": "oYnBVw2LNhaz2Tnn6I6a5tgt9vsE"
 },
 "bind_flag": true,
 "new_flag": false
 }
 }

三、APIResponse的封装

那么有了接口规范，如何实施？此处给出推荐实施案例

//格式化返回
/*
 * 返回数据包括
 *
 * result：代表接口调用的逻辑结果 true代表成功 false代表失败
 * code：错误码，用于前端进行逻辑处理，特殊错误码应与后端特殊定义，以便处理特殊逻辑
 * message：错误返回信息，文字描述
 * ret：返回值，具体业务返回结果
 *
 */
//格式化返回
public static function makeResponse($result, $ret, $code, $mapping_function = null, $params = [])
{
 $rsp = [];
 $rsp['code'] = $code;
 if ($result === true) {
 $rsp['result'] = true;
 $rsp['message'] = self::$returnMessage[$code];
 $rsp['ret'] = $ret;
 } else {
 $rsp['result'] = false;
 if ($ret) {
 $rsp['message'] = $ret;
 } else {
 if (array_key_exists($code, self::$returnMessage)) {
 $rsp['message'] = self::$returnMessage[$code];
 } else {
 $rsp['message'] = 'undefind error code';
 }
 }
 $rsp['ret'] = $ret;
 }
 Utils::backLog(__METHOD__, $rsp);
 return response()->json($rsp);
}

调用时为：

return ApiResponse::makeResponse(true, $ad, ApiResponse::SUCCESS_CODE);

维护错误码：

/*
 * 以下为错误码表，全部逻辑错误遵循该表
 *
 *
 */
//通用错误码
const SUCCESS_CODE = 200; //成功
const MISSING_PARAM = 901; //缺少参数
const INNER_ERROR = 902; //逻辑错误
const UNKNOW_ERROR = 999; //未知错误
//token及用户校验错误
const TOKEN_ERROR = 101; //token校验失败
const USER_ID_LOST = 102; //用户编码丢失
const REGISTER_FAILED = 103; //注册失败
const NO_USER = 104; //未找到用户
const VERTIFY_ERROR = 105; //验证码验证失败
const PHONENUM_DUP = 106; //手机号重复
const PHONENUM_ALREAD_REGISTED = 107; //手机号已经注册过

四、小结

如果你管理一个技术团队，那么技术规范和技术管理工作应该是CTO的重点工作，我们希望达到的目标是在规范、标准库、标准方法的支持下，整个团队的开发效率、协同效率有提升。那么技术管理工作，并不是单单技术问题，更深层次的讲是“综合治理问题”。最后，推荐大家文档管理工具：

showdoc：免费的技术团队文档工具，支持多人协作，管理数据模型、接口文档和项目相关信息比较通畅。

eolinker：接口管理工具，收费