控制层接口规范

Posted 2021-08-28 木兮同学

文章目录

• 一、接口规范
• • 业务即文档
  • URL 规范
  • 动词规范
• 二、安全
• • 令牌
  • 接口加密
  • 接口权限
  • 数据权限

---

一、接口规范

业务即文档

• 控制层采用 REST 规范，可以将每个业务中心理解为一个超大的 JSON 文档，通过 URI 在文档中来定位资源，通过 Http 动词完成增删查改操作

{
    members: [
        {
            id: 100000001,
            mobile: [phone],
            addresses: [
                {
                    id:100000001, detail: 美创总部
                }
            ],
            tags: [100000001,100000002],
            pointRecords: [
                {id:100000001}
            ]
        },
        {
            id: 100000002,
            mobile: [phone],
            addresses: [
                {
                    id:100000002, detail: 美创总部
                }
            ],
            tags: [100000003],
            pointRecords: [
                {id:100000003}
            ]
        }
    ]
}

URL 规范

第一步是通过 URL 在文档中对资源进行定位

• URL 是统一资源定位符，用于在文档中定位资源。如果资源的单词是包含多个，采用驼峰形式，例如积分流水，采用：pointRecords
• 看几个常见的URL
  • https://cmms3.meicloud.com/webadmin/vip/members/100000001 定位到会员 id 为 100000001 的会员对象
  • https://cmms3.meicloud.com/webadmin/vip/members/100000001/addresses/100000002 定位到会员 100000001 下的 id 为 100000002 的会员地址对象（不推荐、推荐下面这个）
  • https://cmms3.meicloud.com/webadmin/vip/addresses/100000002 定位到 id 为 100000002 的会员地址
• 从上面的例子看出，URL 包含以下几部分
  • 协议，域名，端口
  • 业务应用：上面的 webadmin 就是应用
  • 业务模块：vip 是业务模块，表示会员中心
  • 具体的资源：具体中心的资源定位，包括复数名字和唯一资源定位符（ID）
• 对于操作会员地址，为什么不是先定位到会员再定位到地址？
  • 主要是通过地址的唯一标识也能定位到，所以直接简化为直接通过地址id定位到地址对象。

动词规范

第二步就是通过动词，对资源进行操作

• 标准动词
  • 增加： POST https://cmms3.meicloud.com/webadmin/vip/members
  • 删除： DELETE https://cmms3.meicloud.com/webadmin/vip/members/100000001
  • 根据ID查询： GET https://cmms3.meicloud.com/webadmin/vip/members/100000001
  • 修改： PATCH https://cmms3.meicloud.com/webadmin/vip/members/100000001（小程序不支持 PATCH ，改用 PUT 亦可）
• 自定义动词
  • 如果对应的操作，无法抽象成标准的 http 动词，允许定义自定义动词。为了 URL 规范，需要维护好自定义动词表。
  • 自定义动词采用 http POST 方法，在 URL 后面，通过动词的方法来定义。例如：
    • 根据条件查询： POST https://cmms3.meicloud.com/webadmin/vip/members:search
    • 批量更新： POST https://cmms3.meicloud.com/webadmin/vip/members:batchUpdate
    • 锁定操作： POST https://cmms3.meicloud.com/webadmin/vip/members/100000001:disable
    • 维护好自定义动词表，后续涉及的自定义动词都从动词表出，如果没有，才考虑新增，并维护进动词表。目前系统上用的自定义动词表有：
    • 分页查询： xxx:search，这个本来可以用GET方法，由于条件可能较多，就没有采用 GET方法+queryParmeter来实现。
    • 批量操作： batchXXX， 例如： batchGet，batchUpdate，batchDelete，batchCreate
    • 其它操作： 例如 :login，:lock，:unlock，:disable，:enable，:approve（审批）
    • 统计：stat

---

二、安全

令牌

• 令牌采用 JWT。需要了解 JWT 的优缺点才能更好地使用 JWT，下面只列出主要的优缺点，可以再找文章去了解
• 优点：
  • 无状态，不需要存储
  • 可扩展，可以通过 payload 对令牌的内容进行扩展
  • 依赖于算法对签名做加密，安全
• 缺点：
  • 过期时间固定，不可延长，如果要延长，需要重新创建令牌
  • 无法销毁，对 jwt 令牌的加入黑名单，需要引入额外的存储
• 令牌内容：
  • jwt 是明文的，令牌包括，header，payload，signature 三部分，前面两部分都是明文，可以直接进行 base64 解码，拿到明文的内容。
• 令牌的正确用法：
  • 签名校验，因为令牌本身是明文的，靠的是令牌的signature部分，如果不对签名进行校验，令牌是可以被伪造的。
  • 令牌里包含的应该都是大部分接口需要用到的，并且基本不会修改的字段。例如 memberId，手机号码，unionId，openid，用户类型
• 一些错误使用的例子：
  • 将某个业务字段加入到令牌中，例如当前用户的积分数。 积分数是会变化的，如果变化了，那令牌里的内容就不正确了。
  • 只保留一个会员id，其它信息从redis获取。这样就没有用上jwt令牌的特性，要完成业务基本是要依赖于缓存。
• 令牌图解
  

接口加密

• 在 C 端的活动运营过程中，发现有很多薅羊毛的工作室，为了避免接口被刷，需要对接口的请求报文和响应报文做加密，是通过在控制层做接口拦截来实现的。
• 大概的就是对请求的报文做对称性加密，额外增加签名字段做非对称加密，对接口响应结果做对称加密。
• 目前在项目上上的方案是，增加签名，对签名做校验，签名只和当前时间戳，用户令牌有关，和请求参数无关。

接口权限

• 接口权限目前是在控制层处理的，C 端功能不涉及接口权限，B 端（管理后台）功能会涉及数据权限，数据权限的控制是通过拦截器进行拦截。

数据权限

• 无论什么时候都要假设，前端也可以是 postman，也就意味着参数可以随意被篡改，所以在控制层做好数据权限就非常重要，如果接口加密做好了，这个阶段的风险会稍微降低。
• 以下几点要注意，第 1、2 点要特别注意
  • 对于查询和创建接口，需要获取当前用户作为条件，查询或者创建当前用户的数据
  • 对于根据 id 操作的接口，包括根据 id 查找对象，根据 id 更新或删除对象等，需要对查回来的结果，在控制层需要判断数据归属当前用户后对才允许对数据进行操作
  • 涉及用户资产的接口，不允许设置为匿名访问
  • 匿名接口都要考虑如果非匿名情况下访问会不会有差异