API设计总结
支付网关类API设计
- 网关类API由公共参数，业务参数，公共响应，业务响应组成。
公共参数
- method 方法参数控制网关向实际的服务转发
- biz_content 业务参数是具体的服务需要的参数，由具体的业务来解析，验证，处理
公共响应
- code 一般来说，需要两个返回code，网关code由网关返回，表示是否请求成功
- msg 具体的报错信息，应对用户友好
- sub_code 业务返回码，表示实际业务是否处理成功，根据业务不同，有不同的返回码
- sub_msg 业务返回信息，应对用户友好
- data 业务返回数据
APP后台API设计
授权
- APP授权一般使用token完成，jwt或者oahth2，客户端提供用户名密码向服务端请求授权token，以后的所有请求都必须带上token，（一般在请求头带上，便于统一拦截未授权请求）
敏感信息加密
- 某些敏感信息需加密后传输到后台，应约定一对非对称密钥，客户端持有公钥，服务队持有私钥，将敏感信息加密传输
风格
restful
URL
- URL应基于名词，视为资源，不能使用动词，使用请求方法表示对资源的增删改查。
操作
- GET => SELECT
- POST => INSERT
- PUT => UPDATE
- DELETE => DELETE
返回码
- 使用http status code作为返回码，如，200 成功。优点是符合restful，并且便于nginx等日志统计。缺点是，返回码不够丰富，难以表达不同的业务返回错误，并且404，5XX，等特殊返回码难以辨别是程序异常返回还是接口正常返回。
- 使用返回字段code作为返回码，如，{“code”:”200”}，好处是可以自定义丰富的返回码。
版本管理
- 每个接口有各自的版本，一般为接口添加个version的参数。
- 整个接口系统有统一的版本，一般在URL中添加版本号，比如http://api.domain.com/v2。
- 实际使用中，一般使用第一种方式，整个接口系统变动时采用第二种方式。
设计原则
- 所有对象类型下只包含基本类型字段，不再延申二级对象
若有收获，就点个赞吧
0 人点赞
