http api设计规范

规范

1. api 接口必须加版本号，初始版本 【v1】,多个版本api版本可能同时在线
2. 不使用rest的PUT和DELETE，因为很多浏览器不支持，很多框架也不支持
3. POST在需要传输大量数据的时候使用，其余使用GET就可以了；
   

   这里GET和POST没有明确的含义，GET也可以新增

4. 所有路径path全部小写，以下划线分隔，所有参数，包括POST里面的body，以及header使用驼峰。例如：http://127.0.0.1/v1/wechat/mch_info/list_mch_info?page=2&perPage=100
5. 我们返回一般统一使用json格式返回
6. 使用Token令牌来做用户身份的校验与权限分级
7. 暴露外部请求一定使用SSL

Path具体的实现

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

1. {版本}：开始时全部为V1，

2. {具体的业务功能}：

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

3. {表名}:就是数据的表名

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

http协议	方法	行为path	说明
POST	add(POJO)	/add	添加一个对象，接收json信息
GET	insert(param …)	/insert?param1=?¶m1=?	插入一个对象，多个参数的方式，作用和add一样，只是传参数方式不同
GET	deleteById(long)	/delete_by_id?id=?	数据库不删除，但是业务上有删除的语意
POST	update(POJO)	/update	更新一个对象，接收json信息
GET	updateById(long)	/update_by_id?id=?	{表名}中已经具体指明了实体，所有这里可以不用update_pojo_by_id
GET	getById(long)	/get_by_id?id=?	{表名}中已经具体指明了实体，所有这里可以不用get_pojo_by_id
GET	listByParam(Object)	/list_by_param?param=?&page=2&perPage=100	list查询多个，默认全部,可以带上limit，offset，page，sortBy，order等参数

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

Request

1. 请求必须带上公共参数，没有这些公共参数，可以不填写值，但是必须带上
2. 公共参数里面的token是必须带上的，因为我们会基于这个token，做用户登录验证
3. 公共参数写到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

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

{
      "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”

标识映射

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

  错误码	描述
  0	请求成功

• 性别关系映射

  id	性别
  0	未设置
  1	男
  2	女

• platformId 描述

  platformId	平台
  1	web
  2	iOS
  3	Android
  4	miniApp
  5	mp微信公众号

• appName 描述

  appName	应用名称
  app	XXXapp
  jincai	竞猜小程序

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

  channelCode	渠道标识
  self	自有渠道

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

  userCateGorg	用户类别
  co	客户