编程接口设计规范

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. 基本规范
   1. 公共参数

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

字段名称	说明
version	客户端版本。1.0.0
token	登录令牌
os	手机系统版本。12
from	请求来源。android/ios/h5
screen	手机尺寸。1080*1920
model	机型。IPhone7
net	网络状态。wifi

 

1. 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. 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. 1. 上传/下载

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

1. 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. 性能优化

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

字段简写

无用字段清理

图片裁剪

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

预加载