规范

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，
{具体的业务功能}：
- App的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一样，只是传参数方式不同
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

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

标识映射

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

错误码描述

0 请求成功
性别关系映射

id 性别

0 未设置

1 男

2 女

错误码	描述
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 客户

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

channelCode	渠道标识
self	自有渠道

userCateGorg	用户类别
co	客户

glowd

发布了49 篇原创文章 · 获赞 31 · 访问量 13万+

私信关注

http api设计规范

规范

Path具体的实现

Request

压缩格式

数据库字段对应

Response

错误处理

标识映射

猜你喜欢