手记

HTTP接口文档设计原则

如何设计一个好的接口?

之前设计接口文档的时候,没有仔细想过为什么一个接口要这样去定义,因为很多时候我们只是定义接口,实现当下的功能;但是这种做法我是觉得很粗糙,没有经过思考的,接口设计的目标是用设计应为未来业务场景的不确定性,所以谁的接口设计的越好,水平就越高,自然拿到的薪资也越高,那设计的重要性不言而喻。

下面是我对接口设计的一些思考:


一 职责原则

在设计接口的时候,一定要考虑接口是为了完成哪个具体的功能,不同的业务需求需要单独定义接口;如果接口不包含业务属性,可以通过事件的方式用同一个接口通过事件类型区分

二 单一性原理

不同的业务接口需要独立的接口,好处是一个业务的代码变更,不会对另一个业务产生错误风险;

如果是事件类型区分的接口,可以用策略模式,不同的事件类型对应一个唯一的处理策略方法,这样可以做到业务处理隔离,做到事件类型业务变更不会对另一个事件业务产生影响。


三  请求路径的定义

下面的例子为新增用户

 /cloud/accout/user/add

命名的规则 /应用名称/子系统名称/模块名称/接口简称


四 使用RESTfull形式定义接口

这样就减少了 一中接口简称的描述,接口的意图也更加明显

定义:GET(获取),POST(新增),PUT(修改)和DELETE(删除)


五 统一返回类型

只有统一返回类型,不同业务系统间通信才有可能;

通常统一返回类型的定义为:

{
“code”:”0”,                   //状态码,0表示成功、其他表示业务一场
“error_des”:”业务处理失败原因” ,//错误描述,code不为0时有值
“data”: object               //一般用户在查询接口中,返回查询业务数据的统一封装
}


总结:

这是我目前的一些思考总结,大家相互交流,一起成长进步。



1人推荐
随时随地看视频
慕课网APP