HTTP接口文档设计原则

如何设计一个好的接口？

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

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

一 职责原则

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

二 单一性原理

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

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

三  请求路径的定义

下面的例子为新增用户

 /cloud/accout/user/add

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

四 使用RESTfull形式定义接口

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

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

五 统一返回类型

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

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

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

总结：

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