http api设计规范

规范

• api 接口必须加版本号，初始版本 【v1】,多个版本api版本可能同时在线
• 不使用rest的PUT和DELETE，因为很多浏览器不支持，很多框架也不支持
• POST在需要传输大量数据的时候使用，其余使用GET就可以了；
  这里GET和POST没有明确的含义，GET也可以新增
• 所有路径path全部小写，以下划线分隔，所有参数，包括POST里面的body，以及header使用驼峰。例如：http://127.0.0.1/v1/wechat/mch_info/list_mch_info?page=2&perPage=100
• 我们返回一般统一使用json格式返回
• 使用Token令牌来做用户身份的校验与权限分级
• 暴露外部请求一定使用SSL

Path具体的实现

path = /{版本}/{具体的业务功能}/{表名}/{行为}

• {版本}：开始时全部为V1，
• {具体的业务功能}：

pp的setting，数据库命名为 app_setting，那么，具体的业务功能=setting
架构组的wechat，数据库命名为arch_wechat，那么，具体的业务功能=wechat

• {表名}:就是数据的表名
• {行为}：一般就是方法名
• ?limit=10：指定返回记录的数量
• ?offset=10：指定返回记录的开始位置。
• ?page=2&perPage=100：指定第几页，以及每页的记录数。
• ?sortBy=name&order=asc：指定返回结果按照哪个属性排序，以及排序顺序。

*参考数据库设计
https://blog.csdn.net/zengqiang1/article/details/79338660
【推荐】表的命名最好是加上“业务名称_表的作用”。
正例:app_user / trade_config
【推荐】库名与应用名称尽量一致，{业务项目}_{功能},业务项目和功能怎么写参考
*

Request

• 请求必须带上公共参数，没有这些公共参数，可以不填写值，但是必须带上
• 公共参数里面的token是必须带上的，因为我们会基于这个token，做用户登录验证
• 公共参数写到http header里面，key:_head,value json格式，后端直接转为对象
  {

“token”: “123”, //sso token，必须带上，通过这个参数验证用户是否登录，已经确认是哪个用户
“timestamp”: “1234”, //发送请求时间戳
“userId”: “123”, //sso 用户id
“channel”: “123”, //渠道来源,从哪个渠道上面下载的包（iOS就只有一个App Store，Android有小米，应用宝，豌豆荚等国内的渠道),这个也必须有一个对照表
“channelCode”: “123”, //渠道标识，self：自有渠道，其他外部渠道也可以注册企鹅用户，比如问诊的业务渠道映射为：’sq:手机qq渠道,qb:qq浏览器渠道’,表明来自于哪个渠道，这个也必须有一个对照表
“pushId”: “134”, //假如产品或者运营需要我们给部分用户推送消息，可以根据其他公共参数把用户分群，然后拿到pushid给他push消息。
“initStamp”: “123”, //首次安装包时间戳
“device”: “123”, //设备名
“deviceId”: “123”, //设备唯一码
“systemVersion”: “123”, //APP专用，系统平台（Android，iOS）的版本号
“comeFrom”: “123”, //项目来源，例如APP要做一个母亲节的活动,或者520活动，from=母亲节活动,from=520活动，表明我做活动的一个转化率,这个也必须有一个对照表
“platformId”: “123”, //platformId 对照表@see 例如 1:web，2:iOS，3:Android，4:miniApp
“appName”: “123”, //appName 应用名称，对照表，, 例如app:app应用，cai:竞猜小程序
“appVersion”: “123”, //我们自己的app版本号
“extra”: “123” //额外参数，后续做ABTesting等场景的时候会用到，也可以做一些额外的业务需求字段，视各业务而定
}

压缩格式

{"token":"123","timestamp":"1234","userId":"123","channel":"123","channelCode":"123","pushId":"134","initStamp":"123","device":"123","deviceId":"123","systemVersion":"123","come_from":"123","platformId":"123","appName":"123","appVersion":"123","extra":"123"}

数据库字段对应

CREATE TABLE `user_extra_relation` (
  `id` bigint(20) unsigned NOT NULL AUTO_INCREMENT COMMENT '自增主键',
  `user_id` bigint(20) DEFAULT NULL COMMENT 'user表中的id',
  `come_from` varchar(64)  NOT NULL DEFAULT '' COMMENT '项目来源，例如APP要做一个母亲节的活动,或者520活动，from=母亲节活动,from=520活动，表明我做活动的一个转化率,这个也必须有一个对照表,
  `device_id` varchar(64)  NOT NULL DEFAULT '' COMMENT '第一次产生用户注册的设备id',
  `channel_code` varchar(32)  NOT NULL DEFAULT 'self' COMMENT '渠道标识，self：自有渠道，其他外部渠道也可以注册用户,非必传，默认 self',
  `platform_id` tinyint(3) unsigned NOT NULL DEFAULT '0' COMMENT '平台ID，platformId 对照表,例如 1:web，2:iOS，3:Android，4:miniApp',
  `app_name` varchar(32)  NOT NULL DEFAULT '' COMMENT 'appName 应用名称,
  `token` varchar(64)  NOT NULL DEFAULT '' COMMENT '用户token',
  `timestamp` varchar(64)  NOT NULL DEFAULT '' COMMENT '发送请求时间戳',
  `channel` varchar(32)  NOT NULL DEFAULT '' COMMENT '渠道来源,从哪个渠道上面下载的包（iOS就只有一个App Store，Android有小米，应用宝，豌豆荚等国内的渠道),这个也必须有一个对照表https://lexiangla.com/docs/27c78dba373e11e8892b5254004fae61',
  `push_id` varchar(64)  NOT NULL DEFAULT '' COMMENT '假如产品或者运营需要我们给部分用户推送消息，可以根据其他公共参数把用户分群，然后拿到pushid给他push消息。',
  `init_stamp` varchar(64)  NOT NULL DEFAULT '' COMMENT '首次安装包时间戳',
  `device` varchar(64)  NOT NULL DEFAULT '' COMMENT '设备名',
  `system_version` varchar(32)  NOT NULL DEFAULT '' COMMENT '系统版本',
  `app_version` varchar(32)  NOT NULL DEFAULT '' COMMENT '我们自己APP的版本号',
  `extra` varchar(128)  NOT NULL DEFAULT '' COMMENT '额外参数，后续做ABTesting等场景的时候会用到，也可以做一些额外的业务需求字段，视各业务而定',
  `is_delete` tinyint(3) unsigned NOT NULL DEFAULT '0' COMMENT '是否删除 0-未删除、1-删除',
  `gmt_create` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
  `gmt_modified` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '修改时间',
  PRIMARY KEY (`id`),
  UNIQUE KEY `uk_user_id` (`user_id`)
) ENGINE=InnoDB COMMENT='用户附加信息表，表明用户来源等，第一次产生userId时插入信息到此表'

Response

• 采用JSON，不要使用XML
• 默认情况下要支持gzip
• 格式统一：

{
      "code" : 0,
      "msg" : "Something bad happened",
      "data" : {

      }
    }

• code: 0为成功，非0为失败
• msg: 当code为非0时，获取错误信息。当code-
  为0时，msg一般为”success”。
• data: 当code为0时，获取结果，全部以json方式表示。当code为非0时，data没有数据

错误处理

不要直接将异常抛给客户端处理，一般需要一个统一的异常处理类，并且以统一格式将异常信息返回前端，统一格式参照目录“Response”

标识映射

• 保留错误码，可以自定义错误码,错误码全部参考

• 性别关系映射

• platformId 描述

• appName 描述

• channelCode 渠道标识描述，默认为self(自有渠道)，来源于哪次活动，添加活动，需要在这里添加相应标识

• userCateGorg 用户类别，默认为客户。以后可能我们还会有销售，或者其他