# 接口开发技术规范

# 基础数据类型约定

类型名称 Java类型 字段类型 说明
布尔型 Integer smallint(1) 1表示true,用0表示false
日期时间型 Long bigint(13) 用毫秒数值表示,长度为13
金额 / 货币型 Long bigint 采用整数形式存储(即去除小数,以分/厘为单位)

# 数据库及表字段命名原则

表名称格式:[前缀_]<名称段1[_名称段n]>

字段名称格式:[is_]<名称段1[_名称段n]>

说明:

  • 数据库表和字段名称由A-Za-z0-9_下划线组成,尽量避免出现数字,多个单词之间用_下划线分隔,单词不允许使用复数形式;
  • 数据库表和字段名称除数据库特殊情况外,应尽量采用小写英文单词或英文短语或相应缩写,禁止使用汉语拼音和汉字;
  • 数据表主键名称尽量使用id,避免使用复合主键,建议使用索引替代;
  • 布尔型字段名称以is_作为前缀,如:is_deleted
  • 数据库中字段应预留create_timelast_modify_time作为版本字段;

示例:

  • 数据表名称:

      ymate_user
      ymate_user_attribute
    
  • 字段名称:

      is_deleted
      
      create_time
      last_modify_time
    

# 接口通用签名规则

  • 将所有发送或者接收到的数据放入集合中,将集合中的参数名称按ASCII码从小到大(字典序)排序;

  • 参数值为空不参与签名;

  • 参数名称区分大小写且参数内容不要进行URLEncoder编码处理;

  • 签名参数(如:signature)本身不参与签名;

  • 将参与签名的参数以URL键值对的格式进行拼接,示例如下:

      String _signStr = "client_id=CLIENT_ID&create_time=1487178385184&event=subscribe&qrscene=QRSCENE&union_id=o6_bmasdasdsad6_2sgVt7hMZOPfL"
    
  • 将拼接好的_signStr字符串与client_secret密钥进行拼接并生成签名,示例如下:

      // 拼接密钥
      _signStr = _signStr + "&client_secret=6bf18fa2f9a136273fb90e58dff4a964";
      // 执行MD5签名并将字符转换为大写
      _signStr = MD5(_signStr).toUpperCase();
    
  • 如果有必要,可以在请求参数集合中增加随机参数(如:nonce_str),通过随机数函数生成并转换为字符串,从而保证签名的不可预测性;

  • 客户端与服务端均采用相同规则进行参数签名后进行结果比对,两端签名结果一致则验签通过;

# 接口响应报文基础结构

基础报文示例一:

{
	"ret": -1,
	"msg": "参数验证无效",
	"data": {
		"username": "用户名称不能为空",
		"passwd": "登录密码不能为空"
	}
}

基础报文示例二:

{ "ret": -50, "msg": "系统忙,请稍后重试" }

参数说明:

参数 类型 是否必须 说明
ret int 返回码
msg string 消息内容,当ret!=0则此项为必须项
data object 业务数据内容,根据业务逻辑决定其具体数据类型及是否为必须项

# 全局返回码说明

ret = 0:正确返回;

ret > 0:具体业务相关的接口调用错误;

-50 < ret < 0:接口调用不能通过接口服务校验;

ret <= -50:系统内部错误;

全局返回码:

返回码 说明
0 请求成功
-1 参数验证无效
-2 访问的资源未找到或不存在
-3 请求的方法不支持或不正确
-4 请求的资源未授权或无权限
-5 用户会话无效或超时
-6 请求的操作被禁止
-7 用户会话已授权(登录)
-20 数据版本不匹配
-50 系统内部错误