如何给程序接入api（闲谈应用程序接口API）

API（Application Programming Interface）是应用程序接口，可以将API看做是一种契约。App API就是App前端与后台Server之间的一种约定、一种通信，一种请求与相应的协议。是App与后台交互的桥梁。

那么如何设计App API呢？下面与大家一起从设计原则、安全设计、数据设计等几个方面探讨API设计实践。

• 关于命名。接口/参数命名应该面向具体业务场景，名称要清晰，见名知义，容易记忆。
• 接口功能。职责清晰，功能单一，专“人”专职，一个接口只负责一件事情，不要做顺带的事，接口之前尽量不耦合。
• 接口参数。

1. 参数数量尽量少（否则，简单的两个相同类型的参数顺序差错都可能浪费大量的时间），如果实在太多，可以考虑封装成Object（专业术语DO/DTO）。
2. 同一个接口有多种参数类型时，建议采用Builder模式。
3. 接口参数一定要校验，适当抛出异常。

• 接口返回/同步异步。尽量采用同步接口代替异步接口，适当使用回调参数，在多种返回情况下，适当进行封装，特定业务场景下最好返回状态码，避免单一回传结果。

• 接口设计中，安全是不可回避的一个问题，一般来说，有下述3种设计方案。

1. HTTPS。我们可以将敏感信息接口采用HTTPS协议（HTTP基础上添加SSL安全协议，能自动对数据过行压缩加密，可以在一定程度上防监听、劫持。重发等），但缺点是需要CA证书和交费，金融相关应用一般会采用这种做法。
2. 接口设计签名。在传统的token验证基础上，增加签名算法和AppKey验证。
3. 无密码登录。这是现在很多App采用的方式，通过手机号和验证码登录，相对来说，安全性有足够的保障。

• 数据方面，建议采用RESTful风格的API设计，具体包括协议（HTTP）、域名、版本、状态码、请求方法、错误码等。不了解RESTful的童鞋请自行百度。

RESTful API

• 请求路径。在RESTful风格的API中，每个路径都代表着互联网中的一个资源，所以URL中用名词，如https://api.xxx.com/v2/users。
• 请求方法。

1. 一些通用性参数，如版本号、token等放在HTTP请求头中，POST传递。
2. HTTP请求方法GET（查询）、POST（增加）、PUT（更新完整资源）、PATCH（更新部分资源）和DELETE（删除）。
3. 现在APP中基本都需要分页获取数据。请求方法设计时注意预留分页参数。

• 数据传输。

1. Request。使用JSON格式进行传输。JSON的值只有6种类型，分别为Number、String、Boolean、Array、Object、Null。不要肆意增加其他类型。
2. Response。使用JSON格式传输数据。响应格式应该统一，方便前端做统一的处理。尤其是数据字段，应该统一放在一个MAP里面，一个通用的全局响应格式示例如下：

{ code:0, //返回码 message:"成功", //描述信息 data:[{},{},{}], //数据，List或者Object time:1467883234 //时间戳 }

注意，如果返回数据为空，服务端需要提供空字段的默认值（如int默认为0，String默认为""，Object默认为{}，Array默认为[]等），减少前端漏检。

• 返回状态码。全局应该定义统一的状态码，而不应该每个接口单独去定义，一些常见的错误状态有普通异常、token不合法、重复登录、请求头不合法、数据解密错误等。具体定义时，可以根据错误类型划分错误区段，如1001~1010为登录相关错误等。

• App接口与传统Web接口有极大的差异性，App接口中必须考虑数据量和接口数量。
• 数据量。App运行在手机端，流量是一个不可不考虑的问题，这就要求我们接口做到按需返回，冗余的数据传递将浪费用户宝贵的数据流量。因此数据应尽可能做到精简。
• 接口数量。App中，一般要求一个页面对应一个接口，纵然可能存在多个不同的业务，也会建议进行接口合并，这当然主要是从请求效率和流量双方面考虑的，接口设计时也要考虑提供接口的数量，思考是否有合并的可能。

• 接口总会因为数据变化、参数变化或者接口废弃等不可抗拒的原因进行修改变更，这就涉及到接口版本管理。一般我们会在版本号直接放到URL中，如https://api.xxx.com/v2/,也有将版本号放到HTTP请求头的。除此之外，我们还可以为重要的接口设计单独的版本信息，添加version参数，每个接口都拥有自己独立的版本，如此可以很好的兼容旧版本，以便维护。
• 关于域名，建议尽量部署到专属域名下，以便于维护，如https://api.xxx.com/，xxx即你的专属身份，可以试着换成githup查看一下。

1. 本文根据《App架构师》（SkySeraph 潘旭玲著）2018年4月第1版第七章第5小节改编，如有侵权，请联系我删除。
2. 图源于网络，如有侵权，请联系我删除。