======================
接口（Interface）开发
======================
.. note::
    - 更新时间：2020-06-30
    - 整理一下日常接口开发规范和经验，主要包含基本概念、设计项目接口、接口开发原则、接口定义规范等。仅供参考！

参考
=====
- 《理解RESTful架构》 作者： 阮一峰
- 《RESTful API 设计指南》作者： 阮一峰

几个概念
==========
**平时开发基本都会听到这些高大上的词：API、REST-API、RESTful-API，对于追求事物本质的我就集中梳理总结下。**

1. API
    - Application Programming Interface（API）应用程序（编程）接口。 （有点蒙、有点蒙……）
    - 打个比方你现在用的电脑操作系统windows就是一个接口，这个接口连接了你和电脑的硬件。类似的，API就是连接程序和程序之间的接口。
    - 现在人工智能产品越来越多，好多公司也开放了功能接口，赋能各行各业，包括个人开发这。这就是接口的价值，你无需了解底层的原理，就可以使用开放的接口进行应用的开发。
2. REST API 
    - Representational State Transfer(REST) 表现层状态转化。
    - 关键的几个概念：资源、表现层、状态转移。
        + 资源：文本、图像、音频等实体；这里涉及两个概念URI和URL，URI统一资源*标识符*，就是标识前面提到资源的，一般用名词定义；URL统一资源*定位符*，URL是一种URI，标识一个资源，并指定对其进行*操作或获取该资源*的方法，一般用动词定义。
        + 表现层：将资源按照怎样的数据结构来表示。如XML、JSON、txt等；
        + 状态转移：指的是请求接口的操作，如GET、PUT、DELETE、POST。
3. RESTful API 
    - 理解了REST，再回头看RESTful就简单多了，只要符合REST的设计风格和原则就成为RESTful架构。
    - REST不完全等价于RESTful.REST API是Web API设计的一种规范或者指导原则，而RESTful API则是这中架构设计原则或者规范的一种*具体实现*方式之一。

图述概念
--------
*画两张图直观感受下这几个概念的关系。*

- API
    .. image:: image/API .png
        :width: 600px

- URI 
    .. image:: image/URL.png
        :width: 600px


接口的好处
===========
- 提高开发效率。前后端分类，通过约定来解藕前后端的开发。
- 便于维护。
- 便于功能扩展。

接口定义原则及规范
===================

*接口的好处，离不开清晰的原则和规范。只有接口设计的合理才能更好的满足系统的使用和管理。*

.. note::

    本文就采用Backend For Frontend(BFF层)，称为前端的后台，前端（网页、手机、平板等）的业务操作基于接口完成。

原则
------

常用规范（参考）
----------------
基本状态码
^^^^^^^^^^^^^^
.. note::

    一般根据实际业务前后端约定码就行，大多数是一个区间，如：1000-1999，2000-2999等

- 200 - 请求成功
- 301 - 资源（网页等）被永久转移到其它URL
- 404 - 请求的资源（网页等）不存在
- 500 - 内部服务器错误

1. 错误码设计
    + 核心是沟通：系统与系统、人与人、人与系统间的沟通。
    + 回答问题：谁的错？错在哪？
2. 错误码编码方式
    1. 纯数字（大多数采用，腾讯、微博、Google等）
    2. 纯英文
    3. 字母+数字（阿里巴巴推荐方式）
        + 模式：错误产生来源（表示错误来源）+四位数字编号（表示具体错误）
        + 如，A0001-9999，便于快速问题溯源和记忆。
            - A来自用户、B来自系统.（提取标准化约定好系统各个服务的字母编号）
            - 如A来用户端。A0001 用户端错误（一级）、A0100 用户注册错误 （二级） A0101 未同意隐私条约 （三级，具体细节错误）
        + 全部正常可选择错误码：00000
3. 错误码输出路径
    1. 面向日志输出
    2. 面向外部传递
        + 服务器端传向前端
        + OpenAPI 错误码
        + 内部不同域之间
4. 错误码组成
    1. HttpCode	HTTP响应码，符合HTTP协议语义
    2. Code	错误标识
    3. Message	错误消息
    4. Advice	建议处理方式

路由名称
^^^^^^^^^^^
1. 这里的路由名称就是请求接口时使用的，命名规则都是 *名词* ，即前面讲到的URI，也就是说定位资源。
2. 至于为何非要用名词，本质是定位资源（弄清概念），因此名称描述的也就是资源。
3. 我们很容易用动词，比如/get_results、/del_item等等，其实这是多此一举的，因为RESTful方法名（GET、HEAD、POST、PUT、DELETE、OPTIONS、TRACE、PATCH）已经表达了对资源进行的动作了，所以接口名应定义为：/resluts、/item就行了(即资源的名称，如学生、肥皂、汽车等)。

数据格式
^^^^^^^^^^^^^
.. tip::

    考虑到接口的可维护性和可扩展性，返回的msg、code最好集中定义，一一对应约定好。

.. code-block:: bash
    
    {
        "code": 0,        // 0 位正常,其他数字则为异常，这里不须强制使用http的状态码
        "msg": ""  // 附加信息
        "data": "",  // 返回数据
    }

项目结构
=========

接口开发经验
============