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：指定返回结果按照哪个属性排序，以及排序顺序。

http协议	方法	行为path	说明
POST	add(POJO)	/add	添加一个对象，接收json信息
GET	insert(param …)	/insert?param1=?&param1=?	插入一个对象，多个参数的方式，作用和add一样，只是传参数方式不同
	deleteById(long)	/delete_by_id?id=?	数据库不删除，但是业务上有删除的语意
	update(POJO)	/update	更新一个对象，接收json信息
	updateById(long)	/update_by_id?id=?	{表名}中已经具体指明了实体，所有这里可以不用update_pojo_by_id
	getById(long)	/get_by_id?id=?	{表名}中已经具体指明了实体，所有这里可以不用get_pojo_by_id
	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

• 请求必须带上公共参数，没有这些公共参数，可以不填写值，但是必须带上
• 公共参数里面的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”

标识映射

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

错误码	描述
请求成功

• 性别关系映射

id	性
未设置
1	男
2	女

• platformId 描述

	web
	iOS
3	Android
4	miniApp
5	mp微信公众号

• appName 描述

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

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

channelCode	渠道标识
self	自有渠道

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

userCateGorg	用户类别
co	客户