接口设计原则

一、接口的设计依据：

接口要符合rest、命名要规范优雅、单一性、扩展性

1.1 接口要符合rest

REST的要求:

客户端和服务器结构（通信只能由客户端单方面发起，表现为请求-响应的形式。）

连接协议具有无状态性（通信的会话状态（Session State）应该全部由客户端负责维护。）能够利用Cache机制增进性能（响应内容可以在通信链的某处被缓存，以改善网络效率。）一致性的操作界面（通信链的组件之间通过统一的接口相互通信，以提高交互的可见性。）

层次化的系统（通过限制组件的行为（即，每个组件只能“看到”与其交互的紧邻层），将架构分解为若干等级的层。）

1.2 接口命名一定要规范

①命名以英文或者英文缩写并以驼峰命名法命名

②返回字段中表示同一个含义的字段在不同接口中命名尽量一致

1.3 单一性、粒度合适

单一性是指接口要做的事情应该是一个比较单一的事情，比如登陆接口，登陆完成应该只是返回登陆成功以后一些用户信息即可，但很多人为了减少接口交互，返回一大堆额外的数据。比如有人设计一个用户列表接口，接口他返回每一条数据都是包含用户了一大堆跟另外无关的数据，结果一问，原来其他无关的数据是他下一步想要获取的，他想要懒加载，但这是一个工作多年的人设计的吗？(如此次有为患者端接口此类问题明显医护端首页待接订单中请求接口将两种类型订单和在一块导致无法分页请求问题)

1.4 扩展性

这边的扩展性是指我们的接口充分考虑客户端，想想他们是如何调用的，他要怎样使用我的代码，他会如何扩展我的代码，不要把过多的工作写在你的接口里面，而应该把更多的主动权交给客户程序员。如获取不同的列表数据接口，我们不可能将每个列表都写成一个接口。还有一点，我这里特别想指出来的是很多开发人员为了省事（姑且只能这么理解），将接口设计当成只是app页面展示，这些人将一个页面展示就用一个接口实现，而不考虑这些数据是不是属于不同的模块、是不是属于不同的展示范畴、结果下次视觉一改，整个接口又得重写，不能复用。

1.5 文档表述要清晰

良好的接口设计，离不开清晰的接口文档表述。文档表述一定要足够详细。

二、接口入参、返回数据包具体原则

2.1 入参

根据接口是否是涉及业务流程来判断是否添加相关校验参数（如目前的五个基本参数：在版本更新时不要基本参数传入；用户接单需要传入基本参数）。

能够在服务端完成的参数，尽量不要要求客服端传入，避免影响客户端性能(如患者端服务地址设置接口：需要传入16个参数其中Regioncode(区域编码参数) 需要客户端调用调用webAPI 查询)。

2.2 返回数据包（此处仅讨论Json格式）

按照前端相关页面以及相关业务流程所需要的参数返回对应的参数。

容错：1.当后台返回null、nil、、、NULL 已经相关为空的表示时统一成“”（空字符串）来表示。2.状态码，尽量定义过多的状态码，如0是正确,1是错误,3.可拓展性：预留字段（容器）