如何设计一个好接口（一）

作为一个有经验的开发人员，写下的接口不说不计其数，也是盆满钵满了。
那，怎样才算一个好接口呢？又该如何设计出一个好的接口呢？
我们分三篇文章来探讨这个话题，分别从 接口参数的设计与校验、接口的业务逻辑、接口的性能与容错 来详细阐述。
那么，本文就从接口参数的设计与校验这方面来看看，一个设计良好的接口要注意哪些。

1.命名规范，格式规范。

○ 对于接口的作用，从接口名称上做到见名知意。比如queryById,就是根据ID查询。
○ 对于接口参数的意义，同理要见名知意。比如 device_type 就是 设备类型。
○ 接口参数的命名，实用驼峰命名法（如 deviceType）或下划线法（如 device_type）
○ 对于接口参数，应将共有的参数提取出来作为公共请求参数和公共响应参数。

2.响应参数有明确的状态码与描述

○ 响应参数要明确的告诉调用方是否成功、错误原因、错误码。
○ 如果是异常信息，要进行统一分装后将错误描述返回。

3.接口的扩展

○ 针对业务功能的扩展，可以考虑参数设计之初就可扩展（比如使用枚举）。
○ 针对业务功能的变化，既可以新增加一个方法，新旧接口同时使用；也可以使用版本控制，新功能使用新的版本号。

4.接口的防重

○ 判断请求报文中的时间戳与服务器当前时间戳间隔（比如小于60秒）
○ 判断请求报文中的随机数在一段时间内是新的（比如60秒内不能重复）

5.接口参数的校验

○ 根据业务规则对请求参数的有效性进行验证，无效则返回错误提示