Web API系列(一)设计经验与总结

在移动互联网的时代, Web服务已经成为了异构系统之间的互联与集成的主要手段，各类 Web服务几乎都采用REST风格的Web Api来构建。 经过Http协议的形式来. 以Get/Post方式发送请求, 返回json格式(数据更小巧且自描述能力强)的数据。这里就不在介绍REST API 的好处和不足。这些网上一大堆资料。今天就说说，如何构建优秀的REST API ？

　　目前，各大互联网公司, 对自身的REST Api设计有各自的标准，他们的Api 的设计也很是成熟。 那么，咱们应该如何更好的设计咱们的接口， 来提升咱们 API 的可用性，易用性，可维护性与可扩展性呢？

　　一. API 设计方案
　　1. Http的请求分为URL约定规则、请求参数规则
　　　　URL规则: http://{server}/{product}/{version}/{logic}/{method}?{query_string}

　　　　server: 为具体的服务域名
　　　　product: 为应用工程名
　　　　version: 为具体版本号, 便于未来的功能扩展, 能够暂定为 v1, v2
　　　　logic: 为具体业务逻辑的初步划分, 好比后端管理方法, app端的请求方法
　　　　method: 具体业务的方法

　　　　具体的请求参数, 由指定的method方法决定, 全都做为HTTP GET/POST的参数列表。

　　　　这里不少人会问为何把 method 和 version 放到在URI中？

　　　　由于这样可使API 版本化，方便版本控制，同时也便于往后API的分流。固然关因而否将版本信息放入url仍是放入请求头里面，曾经有过很激烈的争论，各有各的道理。我我的认为放到 URL 中会好一些。具体的你们仍是根据本身的业务场景，综合考量吧。

　　2. Http的响应规则
　　　　HTTP响应码为200, 返回结果为JSON字符串的形式:
　　　　若是响应结果正确,则返回结果以下所示:
　　　　{　　
　　　　　　data : { // 请求数据，对象或数组都可
　　　　　　　　user_id: 123,
　　　　　　　　user_name: "zwz",
　　　　　　　　user_avatar_url: "http://www.abc.com/1.jpg"
　　　　　　　　...
　　　　　　},
　　　　　　msg : "done", // 请求状态描述，调试用
　　　　　　success : 1,
　　　　　　code" : 1001, // 业务自定义状态码
　　　　　　extra : { // 其余扩展的数据，字段、内容不定
　　　　　　　　type: 1,
　　　　　　　　desc: "签到成功！"
　　　　　　}
　　　　}

　　　　若是响应结果失败,则返回以下结果:
　　　　{
　　　　　　data : { // 请求数据，对象或数组都可
　　　　　　},
　　　　　　msg : "Internal Server Error", // 请求状态描述，调试用
　　　　　　success : 0,
　　　　　　code : 5001, // 业务自定义状态码
　　　　　　extra : {
　　　　　　}
　　　　}

 

　　3. Auth 权限验证

　　　　API 的权限验证，有不少方案，目前成熟的OAuth 2.0框架等，不过 ，最简单的仍是利用 Http Header 来完成这一目标。 将token 经过 Header 传递。来实现权限验证。

　　4. API 在设计的时候，最好不要将业务错误码与HTTP状态码的绑定,从新定义一套业务错误码，来区分HTTP 的状态码。
　　　　状态码的定义也最好有一套规范，相似于HTTP 的状态码，能够按照用户相关、受权相关、各类业务，作简单的分类。
　　　　// Code 业务自定义状态码定义示例
　　　　// 受权相关
　　　　1001: 无权限访问
　　　　1002: access_token过时
　　　　1003: unique_token无效
　　　　...

　　　　// 用户相关
　　　　2001: 未登陆
　　　　2002: 用户信息错误
　　　　2003: 用户不存在

　　　　// 业务相关
　　　　3001: 业务XXX
　　　　3002: 业务XXX

　　　　// 系统异常
　　　　5001：Internal Server Error

　　　二. 其余一些建议：

　　　　1. 规范统一的命名
　　　　　　使用驼峰式或者下划线格式均可以，统一规范就行。不过，目前基本都是统一小写加下划线比较好。如：user_id，user_name，user_age等。

　　　　2. 语义清晰，遵照经常使用缩写
　　　　　　字段的名字最好能体现字段的类型，遵照一些经常使用的缩写，如：user_name, task_desc, date_str 等

　　　　3. 空值、空字段的处理
　　　　　　空值、空字段的处理也是比较容易出问题。统一空值用null 。除了布尔类型的，其他的空值统一用null表示，客户端保证每种字段的null能够被正常处理。　

　　　　4. 各个Action 尽可能符合CRUD操做的原则。　　　

　　　　5. 给不一样类型设置默认空值
　　　　　　除了null，尽可能对字段设置“默认值”，如数字就是0，字符串就是空字符串""，数组就是空数组[]，对象就是空对象{}，这样能够避免客户端处理空值产生的异常。
　　　　　　具体的要根据业务、先后端约定而定。
　　　　　　好比，bool 类型的值，统一成数字0和1 。时间日期类型强制只能传标准GMT/UTC时间戳，而后由各自的客户端根据本身的时区、显示要求作处理后显示。

　　　　6. 完整的URL
　　　　　　API里面的数据也会有URL类型的，通常来讲如用户的头像、各类图片、音频等资源，都是以URL连接的形式返回的。
　　　　　　返回的URL必定要“完整”，主要指的是不要忘记URL里面的协议部分。应该是http://www.abc.com/1.jpg。

　　　　7. REST 安全
　　　　　　可使用固有的 HTTP 基本验证，你还能够考虑经过支持表单验证，LTPA 验证，Open ID 验证等方式，来知足更多的企业安全要求。

　　　　8. 尽可能将API部署在专用域名之下。例如：https://api.example.com。

　　　　9. API返回的数据格式，应该尽可能使用JSON，避免使用XML。

　　　　10. 返回正确 HTTP 响应代码,同时从新定义一套业务错误码，来区分HTTP 的状态码。

　　　　11. 完善的文档，最好能自动生成在线API文档，这样文档能随时保持最新。
　　　　　　目前有不少自动生成API 文档的攻击，例如：SwaggerUI。

 

 

本文来自：http://www.cnblogs.com/zhangweizhong/p/6196808.html