https://www.heckjj.com/index.php zh-cn https://www.heckjj.com/post// Heck <@hecks.tk> Tue, 05 Nov 2024 02:18:56 +0000 https://www.heckjj.com/post//         RESTful API 是应用程序接口 (API) 的一种架构风格，它使用 HTTP 请求来访问和使用数据。该数据可用于 GET、PUT、POST 和 DELETE 数据类型，这些数据类型是指有关资源的操作的读取、更新、创建和删除。

        RESTful API（也称为 RESTful Web 服务或 REST API）基于表示状态传输 (REST)，它是一种架构风格和经常用于 Web 服务开发的通信方法。

二、设计原则。
URL即资源，使用名词表示资源
接口应直观、简洁、风格命名保持一致
必须版本化，具有足够的灵活性来支持上层UI
三、RFC3986标准。
        RFC3986标准，简单讲就是规定了如下：除了 数字 + 字母 + -_.~ 不会被转义，其他字符都会被以百分号（%）后跟两位十六进制数 %{hex} 的方式进行转义。

         www 的 post form data 也就是 x-www-form-urlencode 的编码规则：除 -_.（没有 ~） 之外的所有 非字母、非数字 的字符都将被替换成 百分号（%）后跟两位十六进制数 %{hex}，空格（注意）则编码为加号 +。

        RFC3986对 ~ 不做转码，x-www-form-urlencode 对 ~ 做转码 %7E。

        RFC3986对 空格 转为 %20，x-www-form-urlencode 对 空格 转为 +。

        JS的URL编码方式：encodeURIComponent。

// encodeURIComponent
console.log(encodeURIComponent("hello233 ~-_."))
hello233%20~-_.

四、URI、URL和URN


         URI（Uniform Resource Identifier ）：统一资源标识符，就是在某一规则下能把一个资源独一无二地标识出来。

        URL（Uniform Resource Locator）：统一资源定位符。

        URN（Uniform Resource Name）：统一资源名称。

        URI可以分为URL,URN或同时具备locators 和names特性的一个东西。URN作用就好像一个人的名字，URL就像一个人的地址。换句话说：URN确定了东西的身份，URL提供了找到它的方式。

        URL是URI的子集, 除了确定一个资源,还提供一种定位该资源的主要访问机制(如其网络“位置”)。例如： http://或 ftp://.。

        当我们替代web地址的时候，URI和URL那个更准确？
        URI更准确。

        我们经常使用的URI不是严格技术意义上的URL。例如：你需要的文件在files.hp.com. 这是URI，但不是URL--系统可能会对很多协议和端口都做出正确的反应。http://files.hp.com 和ftp://files.hp.com可能得到完全不同的内容。这种情况可能更加普遍，想想不同谷歌域名上的不同服务啊。所以，用URI吧，这样你通常技术上是正确的，URL可不一定。

五、设计规范。
1.版本号
        应该将API的版本号放入URL。 版本号以字符'v'开头，比如：v1

http://demo.com/cuc/sever/v1
2.路径(Endpoint)
        接口路径，也称为端点(Endpoint)，代表一种资源的访问地址。

        ①使用名词表示资源，使用HTTP Method 描述操作
                因为"资源"表示一种实体，所以应该是名词，URL不应该有动词，动词应该放在HTTP协议中，CRUD的操作不要体现在URL中。

                 反面教材：

查询员工 GET     /v1/findEmployee?id=1000  
新增员工 POST    /v1/addEmployee
更新员工 POST    /v1/updateEmployee?id=1000
删除员工 POST    /v1/deleteEmployee?id=1000
                 正确实例：

查询员工 GET     /v1/employee/1000  
新增员工 POST    /v1/employee
更新员工 PUT     /v1/employee/1000
删除员工 DELETE  /v1/employee/1000
        ② 资源既可以是单个，也可以是一个集合，比如：user是单个资源，users是集合资源。 由于英文名词的复数规则众多，为了保持接口命名的一致性，我们建议URL里描述集合资源的名词统一使用单数。
                反面示例：

查询单个员工 GET     /v1/employees/1000
查询一组员工 GET     /v1/employees
                正确示例：

查询单个员工 GET     /v1/employee/1000
查询一组员工 GET     /v1/employee
3.使用小写字母，多个单词用"-"分隔，提高URL的可读性
        RFC3986 定义了URI是大小写敏感的(除了scheme和host部分)，为了避免歧义，接口路径应尽量使用小写字母。

        对于由多个单词构成的路径，推荐使用'-'(hyphen)分隔，避免使用驼峰命名（camelCase）、下划线命名(snake_case)、首字母大写的驼峰命名（PascalCase），以提高可读性。

        例子：

camelCase  :  /v1/customer/1000/shippingAddress  [Bad]
snake_case :  /v1/customer/1000/shipping_address [Bad]
PascalCase :  /v1/customer/1000/ShippingAddress  [Bad]

hyphen     :  /v1/customer/1000/shipping-address [OK]
4.资源嵌套层次避免过深，尽量不超过2层
        定义REST接口时，通常使用资源嵌套（多级路径）来标识资源之间的关系，资源嵌套层次尽量不超过2层，否则很难阅读和使用。

        例子：

GET  /v1/user/1000/company    查询ID等于1000的用户的公司信息
GET  /v1/user/1000/company/10 查询ID等于1000的用户所属公司中ID=10的公司信息，嵌套两层
        反面例子：

GET /v1/company/10/department/20302/employee/10830
GET /v1/zoo/1/area/3/animal/4
六. 筛选(Filtering)、排序(Sorting)、分页(Pagination)、字段选择
  1.筛选（Filtering)
      接口URL尽量保持简短，对于集合资源不同纬度的筛选，可通过组合不同的Query Param来实现。

        反面案例：

GET /v1/externalEmployees
GET /v1/internalEmployees
GET /v1/internalAndSeniorEmployees
        正确案例：

GET /v1/employee?state=internal&title=senior
2.排序(Sorting)
        单个字段排序：

GET /v1/employee?sort=age&order=asc
GET /v1/employee?sort=age&order=desc
        多个字段排序：

        字段名前缀,'+'：表示升序，'-'：降序，多个字段名以逗号分隔

GET /v1/employee?sort=+age,-userName
3.分页(Pagination)
        对于数据量比较大的集合资源，接口实现一定要支持分页。

        常规分页有两个重要的参数：      

pageNo 获取那一页的记录，默认第一页。
pageSize 每页返回多少条数据，推荐默认值25，必须限定此参数的最大值。
        返回的资源列表为：[(pageNo-1)pageSize, pageNopageSize)

        请求示例：

GET /v1/employee?pageNo=8&pageSize=20&sort=age&order=desc
        返回值可以采用以下数据格式：

{  
    "pageSize":20,      // 页尺寸
    "pageNo":8,         // 页码
    "totalCount":182,  // 总记录数
    "pageList":[
                {
                    "id":13483,
                    "name":"Hehe",
                    "title":"senior"
                },
                 {
                    "id":13484,
                    "name":"haha",
                    "title":"junior"
                }
    ]
}

4.字段选择
        调用方可能只需要资源的少量属性，接口提供方可支持客户端通过请求参数fields来选择返回的字段，多个字段以逗号分隔，示例如下：

GET /v1/employee?fields=id,name,age&pageNo=1&pageSize=20&sort=age&order=desc ]]> https://www.heckjj.com/post//#blogcomment <user@domain.com> Thu, 01 Jan 1970 00:00:00 +0000 https://www.heckjj.com/post//#blogcomment