编程接口设计规范

  1. 接口示例

接口描述:用户登陆成功后,或进入首页时会获取一次用户信息。

URI

方法

/userinfo

GET

请求参数

名称

必填

备注

id

用户id

响应参数

名称

类型

备注

id

String

用户id

name

String

姓名,例:张三

age

String

年龄,例:20

json示例

{

"code":200,

"msg":"成功",

"time":"1482213602000",

"data": {

"id":"1001",

"name":"张三",

"age":"20"

}

}

  1. 基本规范
    <ol><li><a href="https://blog.csdn.net/weixin_38229356/article/details/83155559#21__44">公共参数</a></li>
    </ol></li>
    

公共参数是每个接口都要携带的参数,描述每个接口的基本信息,用于统计或其他用途,放在header或url参数中。例如:

字段名称

说明

version

客户端版本。1.0.0

token

登录令牌

os

手机系统版本。12

from

请求来源。android/ios/h5

screen

手机尺寸。1080*1920

model

机型。IPhone7

net

网络状态。wifi

    1. 响应数据

响应数据统一格式:code、msg、data。

array类型数据。通过list字段,保证data的Object结构。

分页类型数据。返回总条数,用于判断是否可以加载更多。

// object类型数据

{

"code":1,

"msg":"成功",

"data":{}

}

// array类型数据。

{

"code":1,

"msg":"成功",

"data":{

"list":[]

}

}

// 分页类型数据。

{

"code":1,

"msg":"成功",

"data":{

"list":[]

"total":"10"

}

}

列表类数据接口,无论是否要求分页,最好支持分页,pageSize=Integer.Max即可。

    1. 字段类型规范

统一使用String类型。某些情况,统一使用String可以防止解析失败,减少类型转化操作。Boolean类型,1是0否。客户端处理时,非1都是false。

if("1".equals(isVip)){

}else{

}

status类型字段,从1+开始,区别Boolean的0和1。“0”有两种含义,(1)Boolean类型的false,(2)默认的status

    1. 上传/下载

上传/下载,参数增加文件md5,用于完整性校验(传输过程可能丢失数据)。

    1. 避免精度丢失

缩小单位保存数据,如:钱以分为单位、距离以米为单位。

  1. 瘦客户端

客户端尽量不处理逻辑

客户端不处理金额

客户端参数校验规则可以通过接口返回,同时提供默认规则,接口不通则使用默认规则。

  1. 拓展性

图片文案等,与校验规则类似,通过接口返回,并提供默认。

列表界面

/ 静态列表

{

"name": "张三",

"sex": "男",

"age": "20岁",

"nickName": "小张"

}

// 动态列表

{

"userInfos":[

{

"key":"姓名",

"value":"张三"

},{

"key":"性别",

"value":"男"

},{

"key":"年龄",

"value":"20岁"

},{

"key":"昵称",

"value":"小张"

}]

}

  1. 安全性

保护API的关键在于确保您充分了解威胁模型以及防御方式:

1)、平面隔离,确定接口所属平面,且平面已清晰隔离等。

2)、安全传输,安全传输是否已默认启用,相关算法、套件以及证书管理符合要求等。

3)、认证,默认账户公开,强口令策略,防暴力破解机制以及会话管理机制等

4)、鉴权,确保所有接口都已鉴权,不存在横向和纵向越权问题,不存在直接对象引用问题等。

5)、敏感数据和隐私保护,敏感数据均需要加密存储及传输,加密算法符合要求,文件权限控制得当。

6)、web安全,如果是WebApi接口,需要考虑覆盖web安全相关内容,如文件上传下载、输入编码输出校验、参数服务端校验等。

7)、接口Fuzz,对于接口需要从传输层、应用层分别考虑协议的Fuzz,包括应用层API接口Fuzz

8)、泛洪攻击,从传输层、应用层以及鉴权未鉴权消息角度分别考虑DOS、DDOS攻击风险

9)、安全日志,管理操作需要记录日志。

10)、业务逻辑安全,除了基础的安全之外,还要考虑接口业务逻辑上的安全设计是否合理,是否可能被绕过;重点关注登陆、忘记密码、重置密码等高危操作。

11)、WebServer配置安全,如果是web服务,需要考虑容器的安全配置,可使用工具扫描。

12)、源码安全,测试过程中结合接口源码,覆盖安全功能点,主要关注自研接口代码。

  1. 兼容性

全部接口版本是否统一:

所有的接口都用相同的版本号:这样要发一个APP新版本就统一修改版本号,好修改,但是如果想修改其中一个接口的版本号就不行了。

每个接口的版本号可以不一样:这样比较灵活,建议这样做。

因为已经好多年没有做过服务端了。下面的见解如果有错误,希望指正。

1、每个接口逻辑里 加if 判断(不建议)

接口URL:api.xxx.com/api?version=v1&..

if (version == ‘1.5.0’) {

  do_something

} else if (version ==‘1.4.0') {

  do_something

}

优点:实现简单

缺点:不同版本的逻辑都在一个方法里,在于容易造成代码混乱,不利于维护。

2、不同的文件夹

相当于每个接口版本都是一个独立的项目。放到服务器的独立文件夹里。

例如:

接口URL:api.xxx.com/v1.0/xxxx.php

文件夹位置:Controller/V1.0/

-----------------/xxxx.php

文件夹位置:Controller/V2.1/

-----------------/xxxx.php

优点:版本逻辑分开维护。看url就能知道哪个版本。删除多余版本 不用修改代码。

缺点:同个接口不同版本 文件是重复的。并且 如果有个接口前几版就有问题,一直遗留到现在,就需要改好几套一样的代码。

3、不同版本 用不同的方法 :

类似:

接口URL:api.xxx.com/v1.0/xxxx.php

复制代码

class XXXX{

public functionV1_0() { }

public functionV2_0() { }

}

java或者C# 都有路由配置,可以用路由配置不同版本的URL跳转到不同的方法里。

4、用继承的方式

“一瓶真情”在评论中回复:采用继承的方式,既可以利用之前的接口代码,又可以采用override的方式修改部分接口的实现。

这样是可以的。但是如果你上个版本(也就是父类)修改了代码,就会影响后面的所有版本。

在线上有bug或者需求变更的时候 很可能会修改基类。

5、部署到不同的服务器

6、混合使用

服务端的几种方法混用:

6.1、第3种和第4种方法一起用。先用继承,如果新版本和以前的版本无法复用,就用路由设置新的方法。

6.2、第1种方法和第3中方法一起用,简单的小改动用 第1种,加个if判断。改动较大的用 第3种,新开个方法。

  1. 性能优化

合并接口。一个页面一个接口

字段简写

无用字段清理

图片裁剪

局部刷新。页面需要的数据,可以用前一个页面带来。

预加载

评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值